diff options
Diffstat (limited to 'doc/LinkVar.3')
| -rw-r--r-- | doc/LinkVar.3 | 204 |
1 files changed, 54 insertions, 150 deletions
diff --git a/doc/LinkVar.3 b/doc/LinkVar.3 index f5e97b4..9c13008 100644 --- a/doc/LinkVar.3 +++ b/doc/LinkVar.3 @@ -4,12 +4,12 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" +'\" .TH Tcl_LinkVar 3 7.5 Tcl "Tcl Library Procedures" .so man.macros .BS .SH NAME -Tcl_LinkArray, Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar \- link Tcl variable to C variable +Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar \- link Tcl variable to C variable .SH SYNOPSIS .nf \fB#include <tcl.h>\fR @@ -17,53 +17,34 @@ Tcl_LinkArray, Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar \- link Tcl varia int \fBTcl_LinkVar\fR(\fIinterp, varName, addr, type\fR) .sp -.VS "TIP 312" -int -\fBTcl_LinkArray\fR(\fIinterp, varName, addr, type, size\fR) -.VE "TIP 312" -.sp \fBTcl_UnlinkVar\fR(\fIinterp, varName\fR) .sp \fBTcl_UpdateLinkedVar\fR(\fIinterp, varName\fR) .SH ARGUMENTS -.AS Tcl_Interp varName in +.AS Tcl_Interp writable .AP Tcl_Interp *interp in Interpreter that contains \fIvarName\fR. Also used by \fBTcl_LinkVar\fR to return error messages. .AP "const char" *varName in Name of global variable. -.AP void *addr in +.AP char *addr in Address of C variable that is to be linked to \fIvarName\fR. -.sp -.VS "TIP 312" -In \fBTcl_LinkArray\fR, may be NULL to tell Tcl to create the storage -for the array in the variable. -.VE "TIP 312" .AP int type in -Type of C variable for \fBTcl_LinkVar\fR or type of array element for -\fBTcl_LinkArray\fR. Must be one of \fBTCL_LINK_INT\fR, +Type of C variable. Must be one of \fBTCL_LINK_INT\fR, +.VS 8.5 \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 one of the extra ones listed below. -.sp -In \fBTcl_LinkVar\fR, the additional linked type \fBTCL_LINK_STRING\fR may be -used. -.sp -.VS "TIP 312" -In \fBTcl_LinkArray\fR, the additional linked types \fBTCL_LINK_CHARS\fR and -\fBTCL_LINK_BINARY\fR may be used. -.VE "TIP 312" -.sp -All the above for both functions may be -optionally OR'ed with \fBTCL_LINK_READ_ONLY\fR to make the Tcl -variable read-only. -.AP int size in -.VS "TIP 312" -The number of elements in the C array. Must be greater than zero. -.VE "TIP 312" +\fBTCL_LINK_ULONG\fR, +.VE 8.5 +\fBTCL_LINK_WIDE_INT\fR, +.VS 8.5 +\fBTCL_LINK_WIDE_UINT\fR, \fBTCL_LINK_FLOAT\fR, +.VE 8.5 +\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 @@ -77,177 +58,112 @@ while setting up the link (e.g. because \fIvarName\fR is the name of array) then \fBTCL_ERROR\fR is returned and the interpreter's result contains an error message. .PP -.VS "TIP 312" -\fBTcl_LinkArray\fR is similar, but for arrays of fixed size (given by -the \fIsize\fR argument). When asked to allocate the backing C array -storage (via the \fIaddr\fR argument being NULL), it writes the -address that it allocated to the Tcl interpreter result. -.VE "TIP 312" -.PP The \fItype\fR 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, optionally OR'ed with \fBTCL_LINK_READ_ONLY\fR: .TP \fBTCL_LINK_INT\fR -. -The C variable, or each element of the C array, is of type \fBint\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_GetIntFromObj\fR; attempts to write non-integer values into \fIvarName\fR 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 errors. +.VS 8.5 .TP \fBTCL_LINK_UINT\fR -. -The C variable, or each element of the C array, is of type \fBunsigned int\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. Incomplete integer -representations (like the empty string, '+', '-' or the hex/octal/decimal/binary -prefix) are accepted as if they are valid too. +\fIvarName\fR will be rejected with Tcl errors. .TP \fBTCL_LINK_CHAR\fR -. -The C variable, or each element of the C array, is of type \fBchar\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. Incomplete -integer representations (like the empty string, '+', '-' or the -hex/octal/decimal/binary prefix) are accepted as if they are valid too. -.RS -.PP -.VS "TIP 312" -If using an array of these, consider using \fBTCL_LINK_CHARS\fR instead. -.VE "TIP 312" -.RE -.TP -\fBTCL_LINK_CHARS\fR -.VS "TIP 312" -The C array is of type \fBchar *\fR and is mapped into Tcl as a string. -Any value written into the Tcl variable must have the same length as -the underlying storage. Only supported with \fBTcl_LinkArray\fR. -.VE "TIP 312" +values into \fIvarName\fR will be rejected with Tcl errors. .TP \fBTCL_LINK_UCHAR\fR -. -The C variable, or each element of the C array, is of type \fBunsigned char\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. Incomplete integer -representations (like the empty string, '+', '-' or the hex/octal/decimal/binary -prefix) are accepted as if they are valid too. -.RS -.PP -.VS "TIP 312" -If using an array of these, consider using \fBTCL_LINK_BINARY\fR instead. -.VE "TIP 312" -.RE -.TP -\fBTCL_LINK_BINARY\fR -.VS "TIP 312" -The C array is of type \fBunsigned char *\fR and is mapped into Tcl -as a bytearray. -Any value written into the Tcl variable must have the same length as -the underlying storage. Only supported with \fBTcl_LinkArray\fR. -.VE "TIP 312" +\fIvarName\fR will be rejected with Tcl errors. .TP \fBTCL_LINK_SHORT\fR -. -The C variable, or each element of the C array, is of type \fBshort\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. Incomplete -integer representations (like the empty string, '+', '-' or the -hex/octal/decimal/binary prefix) are accepted as if they are valid too. +values into \fIvarName\fR will be rejected with Tcl errors. .TP \fBTCL_LINK_USHORT\fR -. -The C variable, or each element of the C array, is of type \fBunsigned short\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. Incomplete integer -representations (like the empty string, '+', '-' or the hex/octal/decimal/binary -prefix) are accepted as if they are valid too. +\fIvarName\fR will be rejected with Tcl errors. .TP \fBTCL_LINK_LONG\fR -. -The C variable, or each element of the C array, is of type \fBlong\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. Incomplete -integer representations (like the empty string, '+', '-' or the -hex/octal/decimal/binary prefix) are accepted as if they are valid too. +values into \fIvarName\fR will be rejected with Tcl errors. .TP \fBTCL_LINK_ULONG\fR -. -The C variable, or each element of the C array, is of type \fBunsigned long\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. Incomplete integer -representations (like the empty string, '+', '-' or the hex/octal/decimal/binary -prefix) are accepted as if they are valid too. +\fIvarName\fR will be rejected with Tcl errors. +.VE 8.5 .TP \fBTCL_LINK_DOUBLE\fR -. -The C variable, or each element of the C array, is of type \fBdouble\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_GetDoubleFromObj\fR; attempts to write non-real values into \fIvarName\fR 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 errors. +.VS 8.5 .TP \fBTCL_LINK_FLOAT\fR -. -The C variable, or each element of the C array, is of type \fBfloat\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. Incomplete integer -or real representations (like the empty string, '.', '+', '-' or -the hex/octal/decimal/binary prefix) are accepted as if they are valid too. +\fIvarName\fR will be rejected with Tcl errors. +.VE 8.5 .TP \fBTCL_LINK_WIDE_INT\fR -. -The C variable, or each element of the C array, is of type \fBTcl_WideInt\fR -(which is an integer type +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. Incomplete integer representations (like the empty -string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted -as if they are valid too. +Tcl errors. +.VS 8.5 .TP \fBTCL_LINK_WIDE_UINT\fR -. -The C variable, or each element of the C array, is of type \fBTcl_WideUInt\fR -(which is an unsigned integer type at least 64-bits wide on all platforms that -can support it.) +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 -wideinteger form acceptable to \fBTcl_GetWideUIntFromObj\fR; +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. Incomplete integer representations (like -the empty string, '+', '-' or the hex/octal/decimal/binary prefix) are accepted -as if they are valid too. +rejected with Tcl errors. +.VE 8.5 .TP \fBTCL_LINK_BOOLEAN\fR -. -The C variable, or each element of the C array, is of type \fBint\fR. +The C variable is of type \fBint\fR. If its value is zero then it will read from Tcl as .QW 0 ; otherwise it will read from Tcl as @@ -260,7 +176,6 @@ 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. If its value is not NULL then it must be a pointer to a string allocated with \fBTcl_Alloc\fR or \fBckalloc\fR. @@ -270,7 +185,6 @@ new value. If the C variable contains a NULL pointer then the Tcl variable will read as .QW NULL . -This is only supported by \fBTcl_LinkVar\fR. .PP 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 @@ -290,16 +204,6 @@ 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, trace, variable +boolean, integer, link, read-only, real, string, traces, variable |