diff options
Diffstat (limited to 'doc/ObjSetVar.3')
| -rw-r--r-- | doc/ObjSetVar.3 | 162 |
1 files changed, 0 insertions, 162 deletions
diff --git a/doc/ObjSetVar.3 b/doc/ObjSetVar.3 deleted file mode 100644 index e34f9d3..0000000 --- a/doc/ObjSetVar.3 +++ /dev/null @@ -1,162 +0,0 @@ -'\" -'\" Copyright (c) 1996-1997 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: ObjSetVar.3,v 1.2 1998/09/14 18:39:49 stanton Exp $ -'\" -.so man.macros -.TH Tcl_ObjSetVar2 3 8.0 Tcl "Tcl Library Procedures" -.BS -.SH NAME -Tcl_ObjSetVar2, Tcl_ObjGetVar2 \- manipulate Tcl variables -.SH SYNOPSIS -.nf -\fB#include <tcl.h>\fR -.sp -Tcl_Obj * -\fBTcl_ObjSetVar2\fR(\fIinterp, part1Ptr, part2Ptr, newValuePtr, flags\fR) -.sp -Tcl_Obj * -\fBTcl_ObjGetVar2\fR(\fIinterp, part1Ptr, part2Ptr, flags\fR) -.SH ARGUMENTS -.AS Tcl_Interp *newValuePtr -.AP Tcl_Interp *interp in -Interpreter containing variable. -.AP Tcl_Obj *part1Ptr in -Points to a Tcl object containing the variable's name. -The name may include a series of \fB::\fR namespace qualifiers -to specify a variable in a particular namespace. -May refer to a scalar variable or an element of an array variable. -.AP Tcl_Obj *part2Ptr in -If non-NULL, points to an object containing the name of an element -within an array and \fIpart1Ptr\fR must refer to an array variable. -.AP Tcl_Obj *newValuePtr in -Points to a Tcl object containing the new value for the variable. -.AP int flags in -OR-ed combination of bits providing additional information for -operation. See below for valid values. -.BE - -.SH DESCRIPTION -.PP -These two procedures may be used to read and modify -Tcl variables from C code. -\fBTcl_ObjSetVar2\fR will create a new variable or modify an existing one. -It sets the specified variable to -the object referenced by \fInewValuePtr\fR -and returns a pointer to the object which is the variable's new value. -The returned object may not be the same one -referenced by \fInewValuePtr\fR; -this might happen because variable traces may modify the variable's value. -The reference count for the variable's old value is decremented -and the reference count for its new value is incremented. -If the new value for the variable -is not the same one referenced by \fInewValuePtr\fR -(perhaps as a result of a variable trace), -then \fInewValuePtr\fR's reference count is left unchanged. -The reference count for the returned object is not incremented -to reflect the returned reference. -If the caller needs to keep a reference to the object, -say in a data structure, -it must increment its reference count using \fBTcl_IncrRefCount\fR. -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 variable name specified to \fBTcl_ObjSetVar2\fR consists of two parts. -\fIpart1Ptr\fR contains the name of a scalar or array variable. -If \fIpart2Ptr\fR is NULL, the variable must be a scalar. -If \fIpart2Ptr\fR is not NULL, -it contains the name of an element in the array named by \fIpart2Ptr\fR. -As a special case, if the flag TCL_PARSE_PART1 is specified, -\fIpart1Ptr\fR may contain both an array and an element name: -if the name contains an open parenthesis and ends with a -close parenthesis, then the value between the parentheses is -treated as an element name (which can have any string value) and -the characters before the first open -parenthesis are treated as the name of an array variable. -If the flag TCL_PARSE_PART1 is given, -\fIpart2Ptr\fR should be NULL since the array and element names -are taken from \fIpart2Ptr\fR. -.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: -.TP -\fBTCL_GLOBAL_ONLY\fR -Under normal circumstances the procedures look up variables as follows: -If a procedure call is active in \fIinterp\fR, -a variable is looked up at the current level of procedure call. -Otherwise, a variable is looked up first in the current namespace, -then in the global namespace. -However, if this bit is set in \fIflags\fR then the variable -is looked up only in the global namespace -even if there is a procedure call active. -If both \fBTCL_GLOBAL_ONLY\fR and \fBTCL_NAMESPACE_ONLY\fR are given, -\fBTCL_GLOBAL_ONLY\fR is ignored. -.TP -\fBTCL_NAMESPACE_ONLY\fR -Under normal circumstances the procedures look up variables as follows: -If a procedure call is active in \fIinterp\fR, -a variable is looked up at the current level of procedure call. -Otherwise, a variable is looked up first in the current namespace, -then in the global namespace. -However, if this bit is set in \fIflags\fR then the variable -is looked up only in the current namespace -even if there is a procedure call active. -.TP -\fBTCL_LEAVE_ERR_MSG\fR -If an error is returned and this bit is set in \fIflags\fR, then -an error message will be left in the interpreter's result, -where it can be retrieved with \fBTcl_GetObjResult\fR -or \fBTcl_GetStringResult\fR. -If this flag bit isn't set then no error message is left -and the interpreter's result will not be modified. -.TP -\fBTCL_APPEND_VALUE\fR -If this bit is set then \fInewValuePtr\fR is appended to the current -value, instead of replacing it. -If the variable is currently undefined, then this bit is ignored. -.TP -\fBTCL_LIST_ELEMENT\fR -If this bit is set, then \fInewValuePtr\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 -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 `` }''). -.TP -\fBTCL_PARSE_PART1\fR -If this bit is set, -then \fBTcl_ObjGetVar2\fR and \fBTcl_ObjSetVar2\fR -will parse \fIpart1Ptr\fR -to obtain both an array name and an element name. -If the name in \fIpart1Ptr\fR contains an open parenthesis -and ends with a close parenthesis, -the name is treated as the name of an element of an array; -otherwise, the name in \fIpart1Ptr\fR -is interpreted as the name of a scalar variable. -When this bit is set, -\fIpart2Ptr\fR is ignored. -.PP -\fBTcl_ObjGetVar2\fR returns the value of the specified variable. -Its arguments are treated the same way as those for \fBTcl_ObjSetVar2\fR. -It returns a pointer to the object which is the variable's value. -The reference count for the returned object is not incremented. -If the caller needs to keep a reference to the object, -say in a data structure, -it must increment the reference count using \fBTcl_IncrRefCount\fR. -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. - -.SH "SEE ALSO" -Tcl_GetObjResult, Tcl_GetStringResult, Tcl_GetVar, Tcl_GetVar2, Tcl_SetVar, Tcl_SetVar2, Tcl_TraceVar, Tcl_UnsetVar, Tcl_UnsetVar2 - -.SH KEYWORDS -array, interpreter, object, scalar, set, unset, variable |