167 lines
6.5 KiB
Groff
167 lines
6.5 KiB
Groff
'\"
|
|
'\" Copyright (c) 1989-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/SetVar.3,v 1.15 93/06/05 15:40:17 ouster Exp $ SPRITE (Berkeley)
|
|
'\"
|
|
.so man.macros
|
|
.HS Tcl_SetVar tclc 7.0
|
|
.BS
|
|
.SH NAME
|
|
Tcl_SetVar, Tcl_SetVar2, Tcl_GetVar, Tcl_GetVar2, Tcl_UnsetVar, Tcl_UnsetVar2 \- manipulate Tcl variables
|
|
.SH SYNOPSIS
|
|
.nf
|
|
\fB#include <tcl.h>\fR
|
|
.sp
|
|
char *
|
|
\fBTcl_SetVar\fR(\fIinterp, varName, newValue, flags\fR)
|
|
.sp
|
|
char *
|
|
\fBTcl_SetVar2\fR(\fIinterp, name1, name2, newValue, flags\fR)
|
|
.sp
|
|
char *
|
|
\fBTcl_GetVar\fR(\fIinterp, varName, flags\fR)
|
|
.sp
|
|
char *
|
|
\fBTcl_GetVar2\fR(\fIinterp, name1, name2, flags\fR)
|
|
.sp
|
|
int
|
|
\fBTcl_UnsetVar\fR(\fIinterp, varName, flags\fR)
|
|
.sp
|
|
int
|
|
\fBTcl_UnsetVar2\fR(\fIinterp, name1, name2, flags\fR)
|
|
.SH ARGUMENTS
|
|
.AS Tcl_Interp *newValue
|
|
.AP Tcl_Interp *interp in
|
|
Interpreter containing variable.
|
|
.AP char *varName in
|
|
Name of variable. May refer to a scalar variable or an element of
|
|
an array variable.
|
|
.AP char *newValue in
|
|
New value for variable.
|
|
.AP int flags in
|
|
OR-ed combination of bits providing additional information for
|
|
operation. See below for valid values.
|
|
.AP char *name1 in
|
|
Name of scalar variable, or name of array variable if \fIname2\fR
|
|
is non-NULL.
|
|
.AP char *name2 in
|
|
If non-NULL, gives name of element within array and \fIname1\fR
|
|
must refer to an array variable.
|
|
.BE
|
|
|
|
.SH DESCRIPTION
|
|
.PP
|
|
These procedures may be used to create, modify, read, and delete
|
|
Tcl variables from C code.
|
|
\fBTcl_SetVar\fR and \fBTcl_SetVar2\fR will create a new variable
|
|
or modify an existing one.
|
|
Both of these procedures set the given variable to the value
|
|
given by \fInewValue\fR, and they return a pointer to a
|
|
copy of the variable's new value, which is stored in Tcl's
|
|
variable structure.
|
|
Tcl keeps a private copy of the variable's value, so the caller
|
|
may change \fInewValue\fR after these procedures return without
|
|
affecting the value of the variable.
|
|
If an error occurs in setting the variable (e.g. an array
|
|
variable is referenced without giving an index into the array),
|
|
then NULL is returned.
|
|
.PP
|
|
The name of the variable may be specified in either of two ways.
|
|
If \fBTcl_SetVar\fR is called, the variable name is given as
|
|
a single string, \fIvarName\fR.
|
|
If \fIvarName\fR contains an open parenthesis and ends with a
|
|
close parenthesis, then the value between the parentheses is
|
|
treated as an index (which can have any string value) and
|
|
the characters before the first open
|
|
parenthesis are treated as the name of an array variable.
|
|
If \fIvarName\fR doesn't have parentheses as described above, then
|
|
the entire string is treated as the name of a scalar variable.
|
|
If \fBTcl_SetVar2\fR is called, then the array name and index
|
|
have been separated by the caller into two separate strings,
|
|
\fIname1\fR and \fIname2\fR respectively; if \fIname2\fR is
|
|
zero it means that a scalar variable is being referenced.
|
|
.PP
|
|
The \fIflags\fR argument may be used to specify any of several
|
|
options to the procedures.
|
|
It consists of an OR-ed combination of any of the following
|
|
bits:
|
|
.IP TCL_GLOBAL_ONLY
|
|
Under normal circumstances the procedures look up variables
|
|
at the current level of procedure call for \fIinterp\fR, or
|
|
at global level if there is no call active.
|
|
However, if this bit is set in \fIflags\fR then the variable
|
|
is looked up at global level even if there is a procedure
|
|
call active.
|
|
.IP TCL_LEAVE_ERR_MSG
|
|
If an error is returned and this bit is set in \fIflags\fR, then
|
|
an error message will be left in \fI\%interp->result\fR. If this
|
|
flag bit isn't set then no error message is left (\fI\%interp->result\fR
|
|
will not be modified).
|
|
.IP TCL_APPEND_VALUE
|
|
If this bit is set then \fInewValue\fR is appended to the current
|
|
value, instead of replacing it.
|
|
If the variable is currently undefined, then this bit is ignored.
|
|
.IP TCL_LIST_ELEMENT
|
|
If this bit is set, then \fInewValue\fR is converted to a valid
|
|
Tcl list element before setting (or appending to) the variable.
|
|
A separator space is appended before the new list element unless
|
|
.VS
|
|
the list element is going to be the first element in a list or
|
|
sublist (i.e. the variable's current value is empty, or contains
|
|
the single character ``{'', or ends in `` }'').
|
|
.VE
|
|
.PP
|
|
\fBTcl_GetVar\fR and \fBTcl_GetVar2\fR return the current value
|
|
of a variable.
|
|
The arguments to these procedures are treated in the same way
|
|
as the arguments to \fBTcl_SetVar\fR and \fBTcl_SetVar2\fR.
|
|
Under normal circumstances, the return value is a pointer
|
|
to the variable's value (which is stored in Tcl's variable
|
|
structure and will not change before the next call to \fBTcl_SetVar\fR
|
|
or \fBTcl_SetVar2\fR).
|
|
The only bits of \fIflags\fR that are used are TCL_GLOBAL_ONLY
|
|
and TCL_LEAVE_ERR_MSG, both of
|
|
which have
|
|
the same meaning as for \fBTcl_SetVar\fR.
|
|
If an error occurs in reading the variable (e.g. the variable
|
|
doesn't exist or an array element is specified for a scalar
|
|
variable), then NULL is returned.
|
|
.PP
|
|
\fBTcl_UnsetVar\fR and \fBTcl_UnsetVar2\fR may be used to remove
|
|
a variable, so that future calls to \fBTcl_GetVar\fR or \fBTcl_GetVar2\fR
|
|
for the variable will return an error.
|
|
The arguments to these procedures are treated in the same way
|
|
as the arguments to \fBTcl_GetVar\fR and \fBTcl_GetVar2\fR.
|
|
.VS
|
|
If the variable is successfully removed then TCL_OK is returned.
|
|
If the variable cannot be removed because it doesn't exist then
|
|
TCL_ERROR is returned.
|
|
.VE
|
|
If an array element is specified, the given element is removed
|
|
but the array remains.
|
|
If an array name is specified without an index, then the entire
|
|
array is removed.
|
|
|
|
.SH "SEE ALSO"
|
|
Tcl_TraceVar
|
|
|
|
.SH KEYWORDS
|
|
array, interpreter, scalar, set, unset, variable
|