diff options
Diffstat (limited to 'doc/LinkVar.3')
| -rw-r--r-- | doc/LinkVar.3 | 146 |
1 files changed, 119 insertions, 27 deletions
diff --git a/doc/LinkVar.3 b/doc/LinkVar.3 index 25d3c17..c64720b 100644 --- a/doc/LinkVar.3 +++ b/doc/LinkVar.3 @@ -5,10 +5,8 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: LinkVar.3,v 1.2 1998/09/14 18:39:49 stanton Exp $ -'\" -.so man.macros .TH Tcl_LinkVar 3 7.5 Tcl "Tcl Library Procedures" +.so man.macros .BS .SH NAME Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar \- link Tcl variable to C variable @@ -27,17 +25,20 @@ int .AP Tcl_Interp *interp in Interpreter that contains \fIvarName\fR. Also used by \fBTcl_LinkVar\fR to return error messages. -.AP char *varName in -Name of global variable. Must be in writable memory: Tcl may make -temporary modifications to it while parsing the variable name. +.AP "const char" *varName in +Name of global variable. .AP char *addr in Address of C variable that is to be linked to \fIvarName\fR. .AP int type in -Type of C variable. Must be one of TCL_LINK_INT, TCL_LINK_DOUBLE, -TCL_LINK_BOOLEAN, or TCL_LINK_STRING, optionally OR'ed with -TCL_LINK_READ_ONLY to make Tcl variable read-only. +Type of C variable. Must be one of \fBTCL_LINK_INT\fR, +\fBTCL_LINK_UINT\fR, \fBTCL_LINK_CHAR\fR, \fBTCL_LINK_UCHAR\fR, +\fBTCL_LINK_SHORT\fR, \fBTCL_LINK_USHORT\fR, \fBTCL_LINK_LONG\fR, +\fBTCL_LINK_ULONG\fR, \fBTCL_LINK_WIDE_INT\fR, +\fBTCL_LINK_WIDE_UINT\fR, \fBTCL_LINK_FLOAT\fR, +\fBTCL_LINK_DOUBLE\fR, \fBTCL_LINK_BOOLEAN\fR, or +\fBTCL_LINK_STRING\fR, optionally OR'ed with \fBTCL_LINK_READ_ONLY\fR +to make Tcl variable read-only. .BE - .SH DESCRIPTION .PP \fBTcl_LinkVar\fR uses variable traces to keep the Tcl variable @@ -46,53 +47,134 @@ given by \fIaddr\fR. Whenever the Tcl variable is read the value of the C variable will be returned, and whenever the Tcl variable is written the C variable will be updated to have the same value. -\fBTcl_LinkVar\fR normally returns TCL_OK; if an error occurs +\fBTcl_LinkVar\fR normally returns \fBTCL_OK\fR; if an error occurs while setting up the link (e.g. because \fIvarName\fR is the -name of array) then TCL_ERROR is returned and \fIinterp->result\fR +name of array) then \fBTCL_ERROR\fR is returned and the interpreter's result contains an error message. .PP The \fItype\fR argument specifies the type of the C variable, and must have one of the following values, optionally OR'ed with -TCL_LINK_READ_ONLY: +\fBTCL_LINK_READ_ONLY\fR: .TP \fBTCL_LINK_INT\fR The C variable is of type \fBint\fR. Any value written into the Tcl variable must have a proper integer -form acceptable to \fBTcl_GetInt\fR; attempts to write +form acceptable to \fBTcl_GetIntFromObj\fR; attempts to write non-integer values into \fIvarName\fR will be rejected with Tcl errors. .TP +\fBTCL_LINK_UINT\fR +The C variable is of type \fBunsigned int\fR. +Any value written into the Tcl variable must have a proper unsigned +integer form acceptable to \fBTcl_GetWideIntFromObj\fR and in the +platform's defined range for the \fBunsigned int\fR type; attempts to +write non-integer values (or values outside the range) into +\fIvarName\fR will be rejected with Tcl errors. +.TP +\fBTCL_LINK_CHAR\fR +The C variable is of type \fBchar\fR. +Any value written into the Tcl variable must have a proper integer +form acceptable to \fBTcl_GetIntFromObj\fR and be in the range of the +\fBchar\fR datatype; attempts to write non-integer or out-of-range +values into \fIvarName\fR will be rejected with Tcl errors. +.TP +\fBTCL_LINK_UCHAR\fR +The C variable is of type \fBunsigned char\fR. +Any value written into the Tcl variable must have a proper unsigned +integer form acceptable to \fBTcl_GetIntFromObj\fR and in the +platform's defined range for the \fBunsigned char\fR type; attempts to +write non-integer values (or values outside the range) into +\fIvarName\fR will be rejected with Tcl errors. +.TP +\fBTCL_LINK_SHORT\fR +The C variable is of type \fBshort\fR. +Any value written into the Tcl variable must have a proper integer +form acceptable to \fBTcl_GetIntFromObj\fR and be in the range of the +\fBshort\fR datatype; attempts to write non-integer or out-of-range +values into \fIvarName\fR will be rejected with Tcl errors. +.TP +\fBTCL_LINK_USHORT\fR +The C variable is of type \fBunsigned short\fR. +Any value written into the Tcl variable must have a proper unsigned +integer form acceptable to \fBTcl_GetIntFromObj\fR and in the +platform's defined range for the \fBunsigned short\fR type; attempts to +write non-integer values (or values outside the range) into +\fIvarName\fR will be rejected with Tcl errors. +.TP +\fBTCL_LINK_LONG\fR +The C variable is of type \fBlong\fR. +Any value written into the Tcl variable must have a proper integer +form acceptable to \fBTcl_GetLongFromObj\fR; attempts to write +non-integer or out-of-range +values into \fIvarName\fR will be rejected with Tcl errors. +.TP +\fBTCL_LINK_ULONG\fR +The C variable is of type \fBunsigned long\fR. +Any value written into the Tcl variable must have a proper unsigned +integer form acceptable to \fBTcl_GetWideIntFromObj\fR and in the +platform's defined range for the \fBunsigned long\fR type; attempts to +write non-integer values (or values outside the range) into +\fIvarName\fR will be rejected with Tcl errors. +.TP \fBTCL_LINK_DOUBLE\fR The C variable is of type \fBdouble\fR. Any value written into the Tcl variable must have a proper real -form acceptable to \fBTcl_GetDouble\fR; attempts to write +form acceptable to \fBTcl_GetDoubleFromObj\fR; attempts to write non-real values into \fIvarName\fR will be rejected with Tcl errors. .TP +\fBTCL_LINK_FLOAT\fR +The C variable is of type \fBfloat\fR. +Any value written into the Tcl variable must have a proper real +form acceptable to \fBTcl_GetDoubleFromObj\fR and must be within the +range acceptable for a \fBfloat\fR; attempts to +write non-real values (or values outside the range) into +\fIvarName\fR will be rejected with Tcl errors. +.TP +\fBTCL_LINK_WIDE_INT\fR +The C variable is of type \fBTcl_WideInt\fR (which is an integer type +at least 64-bits wide on all platforms that can support it.) +Any value written into the Tcl variable must have a proper integer +form acceptable to \fBTcl_GetWideIntFromObj\fR; attempts to write +non-integer values into \fIvarName\fR will be rejected with +Tcl errors. +.TP +\fBTCL_LINK_WIDE_UINT\fR +The C variable is of type \fBTcl_WideUInt\fR (which is an unsigned +integer type at least 64-bits wide on all platforms that can support +it.) +Any value written into the Tcl variable must have a proper unsigned +integer form acceptable to \fBTcl_GetWideIntFromObj\fR (it will be +cast to unsigned); +.\" FIXME! Use bignums instead. +attempts to write non-integer values into \fIvarName\fR will be +rejected with Tcl errors. +.TP \fBTCL_LINK_BOOLEAN\fR The C variable is of type \fBint\fR. -If its value is zero then it will read from Tcl as ``0''; -otherwise it will read from Tcl as ``1''. +If its value is zero then it will read from Tcl as +.QW 0 ; +otherwise it will read from Tcl as +.QW 1 . Whenever \fIvarName\fR is modified, the C variable will be set to a 0 or 1 value. Any value written into the Tcl variable must have a proper boolean -form acceptable to \fBTcl_GetBoolean\fR; attempts to write +form acceptable to \fBTcl_GetBooleanFromObj\fR; attempts to write non-boolean values into \fIvarName\fR will be rejected with Tcl errors. .TP \fBTCL_LINK_STRING\fR The C variable is of type \fBchar *\fR. -.VS -If its value is not null then it must be a pointer to a string -allocated with \fBTcl_Alloc\fR. -.VE +If its value is not NULL then it must be a pointer to a string +allocated with \fBTcl_Alloc\fR or \fBckalloc\fR. Whenever the Tcl variable is modified the current C string will be freed and new memory will be allocated to hold a copy of the variable's new value. -If the C variable contains a null pointer then the Tcl variable -will read as ``NULL''. +If the C variable contains a NULL pointer then the Tcl variable +will read as +.QW NULL . .PP -If the TCL_LINK_READ_ONLY flag is present in \fItype\fR then the +If the \fBTCL_LINK_READ_ONLY\fR flag is present in \fItype\fR then the variable will be read-only from Tcl, so that its value can only be changed by modifying the C variable. Attempts to write the variable from Tcl will be rejected with errors. @@ -110,6 +192,16 @@ Tk widget that wishes to display the value of the variable), the trace will not trigger when the C variable has changed. \fBTcl_UpdateLinkedVar\fR ensures that any traces on the Tcl variable are invoked. - +.PP +Note that, as with any call to a Tcl interpreter, \fBTcl_UpdateLinkedVar\fR +must be called from the same thread that created the interpreter. The safest +mechanism is to ensure that the C variable is only ever updated from the same +thread that created the interpreter (possibly in response to an event posted +with \fBTcl_ThreadQueueEvent\fR), but when it is necessary to update the +variable in a separate thread, it is advised that \fBTcl_AsyncMark\fR be used +to indicate to the thread hosting the interpreter that it is ready to run +\fBTcl_UpdateLinkedVar\fR. +.SH "SEE ALSO" +Tcl_TraceVar(3) .SH KEYWORDS -boolean, integer, link, read-only, real, string, traces, variable +boolean, integer, link, read-only, real, string, trace, variable |