232 lines
10 KiB
Groff
232 lines
10 KiB
Groff
|
'\"
|
||
|
|
'\" 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
|