114 lines
4.2 KiB
Groff
114 lines
4.2 KiB
Groff
'\"
|
|
'\" Copyright (c) 1993 The Regents of the University of California.
|
|
'\" All rights reserved.
|
|
'\"
|
|
'\" Permission is hereby granted, without written agreement and without
|
|
'\" license or royalty fees, to use, copy, modify, and distribute this
|
|
'\" documentation for any purpose, provided that the above copyright
|
|
'\" notice and the following two paragraphs appear in all copies.
|
|
'\"
|
|
'\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
|
|
'\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
|
|
'\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
|
|
'\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
'\"
|
|
'\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
|
|
'\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
|
|
'\" AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS
|
|
'\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
|
|
'\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
|
|
'\"
|
|
'\" $Header: /user6/ouster/tcl/man/RCS/LinkVar.3,v 1.4 93/07/28 15:18:56 ouster Exp $ SPRITE (Berkeley)
|
|
'\"
|
|
.so man.macros
|
|
.HS Tcl_LinkVar tclc 7.0
|
|
.BS
|
|
.SH NAME
|
|
.na
|
|
Tcl_LinkVar, Tcl_UnlinkVar \- link Tcl variable to C variable
|
|
.ad
|
|
.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)
|
|
.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 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
|
|
.na
|
|
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.
|
|
.ad
|
|
.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 TCL_OK; 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
|
|
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:
|
|
.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
|
|
non-integer values 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
|
|
non-real 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''.
|
|
Whenver \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
|
|
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 \fBmalloc\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''.
|
|
.PP
|
|
If the TCL_LINK_READ_ONLY 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.
|
|
|
|
.SH KEYWORDS
|
|
boolean, integer, link, read-only, real, string, variable
|