Tcl_LinkVar(3) Tcl Library Procedures Tcl_LinkVar(3) ________________________________________________________________________________ NAME Tcl_LinkArray, Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar - link Tcl variable to C variable SYNOPSIS #include <tcl.h> int Tcl_LinkVar(interp, varName, addr, type) int 2 Tcl_LinkArray(interp, varName, addr, type, size) 2 Tcl_UnlinkVar(interp, varName) Tcl_UpdateLinkedVar(interp, varName) ARGUMENTS Tcl_Interp *interp (in) Interpreter that contains varName. Also used by Tcl_LinkVar to return error mes- sages. const char *varName (in) Name of global variable. void *addr (in) Address of C variable that is to be linked to varName. In Tcl_LinkArray, may be NULL to tell Tcl 2 to create the storage for the array in the 2 variable. int type (in) Type of C variable for Tcl_LinkVar or type of array element for Tcl_LinkArray. Must be one of TCL_LINK_INT, TCL_LINK_UINT, TCL_LINK_CHAR, TCL_LINK_UCHAR, TCL_LINK_SHORT, TCL_LINK_USHORT, TCL_LINK_LONG, TCL_LINK_ULONG, TCL_LINK_WIDE_INT, TCL_LINK_WIDE_UINT, TCL_LINK_FLOAT, TCL_LINK_DOUBLE, TCL_LINK_BOOLEAN, or one of the extra ones listed below. In Tcl_LinkVar, the additional linked type TCL_LINK_STRING may be used. In Tcl_LinkArray, the additional linked 2 types TCL_LINK_CHARS and TCL_LINK_BINARY 2 may be used. All the above for both functions may be optionally OR'ed with TCL_LINK_READ_ONLY to make the Tcl variable read-only. Tcl_Size size (in) The number of elements in the C array. 2 Must be greater than zero. ________________________________________________________________________________ DESCRIPTION Tcl_LinkVar uses variable traces to keep the Tcl variable named by varName in sync with the C variable at the address given by addr. 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. Tcl_LinkVar normally returns TCL_OK; if an error occurs while set- ting up the link (e.g. because varName is the name of array) then TCL_ERROR is returned and the interpreter's result contains an error message. Tcl_LinkArray is similar, but for arrays of fixed size (given by the size 2 argument). When asked to allocate the backing C array storage (via the addr 2 argument being NULL), it writes the address that it allocated to the Tcl 2 interpreter result. The type argument specifies the type of the C variable, or the type of the elements of the C array, and must have one of the following values, option- ally OR'ed with TCL_LINK_READ_ONLY: TCL_LINK_INT The C variable, or each element of the C array, is of type int. Any value written into the Tcl variable must have a proper integer form acceptable to Tcl_GetIntFromObj; attempts to write non-integer val- ues into varName will be rejected with Tcl errors. Incomplete inte- ger representations (like the empty string, '+', '-' or the hex/oc- tal/decimal/binary prefix) are accepted as if they are valid too. TCL_LINK_UINT The C variable, or each element of the C array, is of type unsigned int. Any value written into the Tcl variable must have a proper un- signed integer form acceptable to Tcl_GetWideIntFromObj and in the platform's defined range for the unsigned int type; attempts to write non-integer values (or values outside the range) into varName will be rejected with Tcl errors. Incomplete integer representations (like the empty string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too. TCL_LINK_CHAR The C variable, or each element of the C array, is of type char. Any value written into the Tcl variable must have a proper integer form acceptable to Tcl_GetIntFromObj and be in the range of the char datatype; attempts to write non-integer or out-of-range values into varName will be rejected with Tcl errors. Incomplete integer repre- sentations (like the empty string, '+', '-' or the hex/octal/deci- mal/binary prefix) are accepted as if they are valid too. If using an array of these, consider using TCL_LINK_CHARS instead. 2 TCL_LINK_CHARS The C array is of type char * and is mapped into Tcl as a string. 2 Any value written into the Tcl variable must have the same length as 2 the underlying storage. Only supported with Tcl_LinkArray. TCL_LINK_UCHAR The C variable, or each element of the C array, is of type unsigned char. Any value written into the Tcl variable must have a proper unsigned integer form acceptable to Tcl_GetIntFromObj and in the platform's defined range for the unsigned char type; attempts to write non-integer values (or values outside the range) into varName will be rejected with Tcl errors. Incomplete integer representations (like the empty string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too. If using an array of these, consider using TCL_LINK_BINARY instead. 2 TCL_LINK_BINARY The C array is of type unsigned char * and is mapped into Tcl as a 2 bytearray. Any value written into the Tcl variable must have the 2 same length as the underlying storage. Only supported with 2 Tcl_LinkArray. TCL_LINK_SHORT The C variable, or each element of the C array, is of type short. Any value written into the Tcl variable must have a proper integer form acceptable to Tcl_GetIntFromObj and be in the range of the short datatype; attempts to write non-integer or out-of-range values into varName will be rejected with Tcl errors. Incomplete integer representations (like the empty string, '+', '-' or the hex/oc- tal/decimal/binary prefix) are accepted as if they are valid too. TCL_LINK_USHORT The C variable, or each element of the C array, is of type unsigned short. Any value written into the Tcl variable must have a proper unsigned integer form acceptable to Tcl_GetIntFromObj and in the platform's defined range for the unsigned short type; attempts to write non-integer values (or values outside the range) into varName will be rejected with Tcl errors. Incomplete integer representations (like the empty string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too. TCL_LINK_LONG The C variable, or each element of the C array, is of type long. Any value written into the Tcl variable must have a proper integer form acceptable to Tcl_GetLongFromObj; attempts to write non-integer or out-of-range values into varName will be rejected with Tcl er- rors. Incomplete integer representations (like the empty string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too. TCL_LINK_ULONG The C variable, or each element of the C array, is of type unsigned long. Any value written into the Tcl variable must have a proper unsigned integer form acceptable to Tcl_GetWideIntFromObj and in the platform's defined range for the unsigned long type; attempts to write non-integer values (or values outside the range) into varName will be rejected with Tcl errors. Incomplete integer representations (like the empty string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too. TCL_LINK_DOUBLE The C variable, or each element of the C array, is of type double. Any value written into the Tcl variable must have a proper real form acceptable to Tcl_GetDoubleFromObj; attempts to write non-real val- ues into varName will be rejected with Tcl errors. Incomplete inte- ger or real representations (like the empty string, '.', '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too. TCL_LINK_FLOAT The C variable, or each element of the C array, is of type float. Any value written into the Tcl variable must have a proper real form acceptable to Tcl_GetDoubleFromObj and must be within the range ac- ceptable for a float; attempts to write non-real values (or values outside the range) into varName will be rejected with Tcl errors. Incomplete integer or real representations (like the empty string, '.', '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too. TCL_LINK_WIDE_INT The C variable, or each element of the C array, is of type Tcl_WideInt (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 Tcl_GetWideIntFromObj; attempts to write non-integer values into varName will be rejected with Tcl errors. Incomplete integer repre- sentations (like the empty string, '+', '-' or the hex/octal/deci- mal/binary prefix) are accepted as if they are valid too. TCL_LINK_WIDE_UINT The C variable, or each element of the C array, is of type Tcl_WideUInt (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 wideinteger form ac- ceptable to Tcl_GetWideUIntFromObj; attempts to write non-integer values into varName will be rejected with Tcl errors. Incomplete in- teger representations (like the empty string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted as if they are valid too. TCL_LINK_BOOLEAN The C variable, or each element of the C array, is of type int. If its value is zero then it will read from Tcl as "0"; otherwise it will read from Tcl as "1". Whenever varName 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 Tcl_Get- BooleanFromObj; attempts to write non-boolean values into varName will be rejected with Tcl errors. TCL_LINK_STRING The C variable is of type char *. If its value is not NULL then it must be a pointer to a string allocated with Tcl_Alloc. 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 vari- able will read as "NULL". This is only supported by Tcl_LinkVar. If the TCL_LINK_READ_ONLY flag is present in type 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. Tcl_UnlinkVar removes the link previously set up for the variable given by varName. If there does not exist a link for varName then the procedure has no effect. Tcl_UpdateLinkedVar may be invoked after the C variable has changed to force the Tcl variable to be updated immediately. In many cases this pro- cedure is not needed, since any attempt to read the Tcl variable will re- turn the latest value of the C variable. However, if a trace has been set on the Tcl variable (such as a Tk widget that wishes to display the value of the variable), the trace will not trigger when the C variable has changed. Tcl_UpdateLinkedVar ensures that any traces on the Tcl variable are invoked. Note that, as with any call to a Tcl interpreter, Tcl_UpdateLinkedVar 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 Tcl_ThreadQueueEvent), but when it is necessary to update the variable in a separate thread, it is advised that Tcl_AsyncMark be used to indicate to the thread hosting the interpreter that it is ready to run Tcl_UpdateLinkedVar. SEE ALSO Tcl_TraceVar(3) KEYWORDS boolean, integer, link, read-only, real, string, trace, variable Tcl 7.5 Tcl_LinkVar(3)
Want to link to this manual page? Use this URL:
<https://man.FreeBSD.org/cgi/man.cgi?query=Tcl_UpdateLinkedVar.tcl90&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>