diff options
Diffstat (limited to 'tcl8.6/doc/LinkVar.3')
| -rw-r--r-- | tcl8.6/doc/LinkVar.3 | 231 |
1 files changed, 0 insertions, 231 deletions
diff --git a/tcl8.6/doc/LinkVar.3 b/tcl8.6/doc/LinkVar.3 deleted file mode 100644 index c80d30d..0000000 --- a/tcl8.6/doc/LinkVar.3 +++ /dev/null @@ -1,231 +0,0 @@ -'\" -'\" Copyright (c) 1993 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" 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_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar \- link Tcl variable to C variable -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -int -\fBTcl_LinkVar\fR(\fIinterp, varName, addr, type\fR) -.sp -\fBTcl_UnlinkVar\fR(\fIinterp, varName\fR) -.sp -\fBTcl_UpdateLinkedVar\fR(\fIinterp, varName\fR) -.SH ARGUMENTS -.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 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 \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 -named by \fIvarName\fR in sync with the C variable at the address -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 \fBTCL_OK\fR; if an error occurs -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 -The \fItype\fR argument specifies the type of the C variable, -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 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/binary prefix) are accepted -as if they are valid too. -.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. Incomplete integer -representations (like the empty string, '+', '-' or the hex/octal/binary -prefix) are accepted as if they are valid too. -.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. Incomplete -integer representations (like the empty string, '+', '-' or the -hex/octal/binary prefix) are accepted as if they are valid too. -.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. Incomplete integer -representations (like the empty string, '+', '-' or the hex/octal/binary -prefix) are accepted as if they are valid too. -.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. Incomplete -integer representations (like the empty string, '+', '-' or the -hex/octal/binary prefix) are accepted as if they are valid too. -.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. Incomplete integer -representations (like the empty string, '+', '-' or the hex/octal/binary -prefix) are accepted as if they are valid too. -.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. Incomplete -integer representations (like the empty string, '+', '-' or the -hex/octal/binary prefix) are accepted as if they are valid too. -.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. Incomplete integer -representations (like the empty string, '+', '-' or the hex/octal/binary -prefix) are accepted as if they are valid too. -.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_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/binary prefix) are -accepted as if they are valid too. -.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. Incomplete integer -or real representations (like the empty string, '.', '+', '-' or -the hex/octal/binary prefix) are accepted as if they are valid too. -.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. Incomplete integer representations (like the empty -string, '+', '-' or the hex/octal/binary prefix) are accepted -as if they are valid too. -.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. Incomplete integer representations (like -the empty string, '+', '-' or the hex/octal/binary prefix) are accepted -as if they are valid too. -.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 -.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_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. -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 -.QW NULL . -.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 -changed by modifying the C variable. -Attempts to write the variable from Tcl will be rejected with errors. -.PP -\fBTcl_UnlinkVar\fR removes the link previously set up for the -variable given by \fIvarName\fR. If there does not exist a link -for \fIvarName\fR then the procedure has no effect. -.PP -\fBTcl_UpdateLinkedVar\fR may be invoked after the C variable has -changed to force the Tcl variable to be updated immediately. -In many cases this procedure is not needed, since any attempt to -read the Tcl variable will return 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. -\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 |