util/X86LINUX64/man/man3/Tcl_GlobalEvalObj.3

   1 '\"
   2 '\" Copyright (c) 1989-1993 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
   4 '\" Copyright (c) 2000 Scriptics Corporation.
   5 '\"
   6 '\" See the file "license.terms" for information on usage and redistribution
   7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   8 '\"
   9 .TH Tcl_Eval 3 8.1 Tcl "Tcl Library Procedures"
  10 .\" The -*- nroff -*- definitions below are for supplemental macros used
  11 .\" in Tcl/Tk manual entries.
  12 .\"
  13 .\" .AP type name in/out ?indent?
  14 .\"     Start paragraph describing an argument to a library procedure.
  15 .\"     type is type of argument (int, etc.), in/out is either "in", "out",
  16 .\"     or "in/out" to describe whether procedure reads or modifies arg,
  17 .\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  18 .\"     needed;  use .AS below instead)
  19 .\"
  20 .\" .AS ?type? ?name?
  21 .\"     Give maximum sizes of arguments for setting tab stops.  Type and
  22 .\"     name are examples of largest possible arguments that will be passed
  23 .\"     to .AP later.  If args are omitted, default tab stops are used.
  24 .\"
  25 .\" .BS
  26 .\"     Start box enclosure.  From here until next .BE, everything will be
  27 .\"     enclosed in one large box.
  28 .\"
  29 .\" .BE
  30 .\"     End of box enclosure.
  31 .\"
  32 .\" .CS
  33 .\"     Begin code excerpt.
  34 .\"
  35 .\" .CE
  36 .\"     End code excerpt.
  37 .\"
  38 .\" .VS ?version? ?br?
  39 .\"     Begin vertical sidebar, for use in marking newly-changed parts
  40 .\"     of man pages.  The first argument is ignored and used for recording
  41 .\"     the version when the .VS was added, so that the sidebars can be
  42 .\"     found and removed when they reach a certain age.  If another argument
  43 .\"     is present, then a line break is forced before starting the sidebar.
  44 .\"
  45 .\" .VE
  46 .\"     End of vertical sidebar.
  47 .\"
  48 .\" .DS
  49 .\"     Begin an indented unfilled display.
  50 .\"
  51 .\" .DE
  52 .\"     End of indented unfilled display.
  53 .\"
  54 .\" .SO ?manpage?
  55 .\"     Start of list of standard options for a Tk widget. The manpage
  56 .\"     argument defines where to look up the standard options; if
  57 .\"     omitted, defaults to "options". The options follow on successive
  58 .\"     lines, in three columns separated by tabs.
  59 .\"
  60 .\" .SE
  61 .\"     End of list of standard options for a Tk widget.
  62 .\"
  63 .\" .OP cmdName dbName dbClass
  64 .\"     Start of description of a specific option.  cmdName gives the
  65 .\"     option's name as specified in the class command, dbName gives
  66 .\"     the option's name in the option database, and dbClass gives
  67 .\"     the option's class in the option database.
  68 .\"
  69 .\" .UL arg1 arg2
  70 .\"     Print arg1 underlined, then print arg2 normally.
  71 .\"
  72 .\" .QW arg1 ?arg2?
  73 .\"     Print arg1 in quotes, then arg2 normally (for trailing punctuation).
  74 .\"
  75 .\" .PQ arg1 ?arg2?
  76 .\"     Print an open parenthesis, arg1 in quotes, then arg2 normally
  77 .\"     (for trailing punctuation) and then a closing parenthesis.
  78 .\"
  79 .\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  80 .if t .wh -1.3i ^B
  81 .nr ^l \n(.l
  82 .ad b
  83 .\"     # Start an argument description
  84 .de AP
  85 .ie !"\\$4"" .TP \\$4
  86 .el \{\
  87 .   ie !"\\$2"" .TP \\n()Cu
  88 .   el          .TP 15
  89 .\}
  90 .ta \\n()Au \\n()Bu
  91 .ie !"\\$3"" \{\
  92 \&\\$1 \\fI\\$2\\fP (\\$3)
  93 .\".b
  94 .\}
  95 .el \{\
  96 .br
  97 .ie !"\\$2"" \{\
  98 \&\\$1  \\fI\\$2\\fP
  99 .\}
 100 .el \{\
 101 \&\\fI\\$1\\fP
 102 .\}
 103 .\}
 104 ..
 105 .\"     # define tabbing values for .AP
 106 .de AS
 107 .nr )A 10n
 108 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 109 .nr )B \\n()Au+15n
 110 .\"
 111 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 112 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 113 ..
 114 .AS Tcl_Interp Tcl_CreateInterp in/out
 115 .\"     # BS - start boxed text
 116 .\"     # ^y = starting y location
 117 .\"     # ^b = 1
 118 .de BS
 119 .br
 120 .mk ^y
 121 .nr ^b 1u
 122 .if n .nf
 123 .if n .ti 0
 124 .if n \l'\\n(.lu\(ul'
 125 .if n .fi
 126 ..
 127 .\"     # BE - end boxed text (draw box now)
 128 .de BE
 129 .nf
 130 .ti 0
 131 .mk ^t
 132 .ie n \l'\\n(^lu\(ul'
 133 .el \{\
 134 .\"     Draw four-sided box normally, but don't draw top of
 135 .\"     box if the box started on an earlier page.
 136 .ie !\\n(^b-1 \{\
 137 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 138 .\}
 139 .el \}\
 140 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 141 .\}
 142 .\}
 143 .fi
 144 .br
 145 .nr ^b 0
 146 ..
 147 .\"     # VS - start vertical sidebar
 148 .\"     # ^Y = starting y location
 149 .\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 150 .de VS
 151 .if !"\\$2"" .br
 152 .mk ^Y
 153 .ie n 'mc \s12\(br\s0
 154 .el .nr ^v 1u
 155 ..
 156 .\"     # VE - end of vertical sidebar
 157 .de VE
 158 .ie n 'mc
 159 .el \{\
 160 .ev 2
 161 .nf
 162 .ti 0
 163 .mk ^t
 164 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 165 .sp -1
 166 .fi
 167 .ev
 168 .\}
 169 .nr ^v 0
 170 ..
 171 .\"     # Special macro to handle page bottom:  finish off current
 172 .\"     # box/sidebar if in box/sidebar mode, then invoked standard
 173 .\"     # page bottom macro.
 174 .de ^B
 175 .ev 2
 176 'ti 0
 177 'nf
 178 .mk ^t
 179 .if \\n(^b \{\
 180 .\"     Draw three-sided box if this is the box's first page,
 181 .\"     draw two sides but no top otherwise.
 182 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 183 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 184 .\}
 185 .if \\n(^v \{\
 186 .nr ^x \\n(^tu+1v-\\n(^Yu
 187 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 188 .\}
 189 .bp
 190 'fi
 191 .ev
 192 .if \\n(^b \{\
 193 .mk ^y
 194 .nr ^b 2
 195 .\}
 196 .if \\n(^v \{\
 197 .mk ^Y
 198 .\}
 199 ..
 200 .\"     # DS - begin display
 201 .de DS
 202 .RS
 203 .nf
 204 .sp
 205 ..
 206 .\"     # DE - end display
 207 .de DE
 208 .fi
 209 .RE
 210 .sp
 211 ..
 212 .\"     # SO - start of list of standard options
 213 .de SO
 214 'ie '\\$1'' .ds So \\fBoptions\\fR
 215 'el .ds So \\fB\\$1\\fR
 216 .SH "STANDARD OPTIONS"
 217 .LP
 218 .nf
 219 .ta 5.5c 11c
 220 .ft B
 221 ..
 222 .\"     # SE - end of list of standard options
 223 .de SE
 224 .fi
 225 .ft R
 226 .LP
 227 See the \\*(So manual entry for details on the standard options.
 228 ..
 229 .\"     # OP - start of full description for a single option
 230 .de OP
 231 .LP
 232 .nf
 233 .ta 4c
 234 Command-Line Name:      \\fB\\$1\\fR
 235 Database Name:  \\fB\\$2\\fR
 236 Database Class: \\fB\\$3\\fR
 237 .fi
 238 .IP
 239 ..
 240 .\"     # CS - begin code excerpt
 241 .de CS
 242 .RS
 243 .nf
 244 .ta .25i .5i .75i 1i
 245 ..
 246 .\"     # CE - end code excerpt
 247 .de CE
 248 .fi
 249 .RE
 250 ..
 251 .\"     # UL - underline word
 252 .de UL
 253 \\$1\l'|0\(ul'\\$2
 254 ..
 255 .\"     # QW - apply quotation marks to word
 256 .de QW
 257 .ie '\\*(lq'"' ``\\$1''\\$2
 258 .\"" fix emacs highlighting
 259 .el \\*(lq\\$1\\*(rq\\$2
 260 ..
 261 .\"     # PQ - apply parens and quotation marks to word
 262 .de PQ
 263 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
 264 .\"" fix emacs highlighting
 265 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
 266 ..
 267 .\"     # QR - quoted range
 268 .de QR
 269 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
 270 .\"" fix emacs highlighting
 271 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
 272 ..
 273 .\"     # MT - "empty" string
 274 .de MT
 275 .QW ""
 276 ..
 277 .BS
 278 .SH NAME
 279 Tcl_EvalObjEx, Tcl_EvalFile, Tcl_EvalObjv, Tcl_Eval, Tcl_EvalEx, Tcl_GlobalEval, Tcl_GlobalEvalObj, Tcl_VarEval, Tcl_VarEvalVA \- execute Tcl scripts
 280 .SH SYNOPSIS
 281 .nf
 282 \fB#include <tcl.h>\fR
 283 .sp
 284 int
 285 \fBTcl_EvalObjEx\fR(\fIinterp, objPtr, flags\fR)
 286 .sp
 287 int
 288 \fBTcl_EvalFile\fR(\fIinterp, fileName\fR)
 289 .sp
 290 int
 291 \fBTcl_EvalObjv\fR(\fIinterp, objc, objv, flags\fR)
 292 .sp
 293 int
 294 \fBTcl_Eval\fR(\fIinterp, script\fR)
 295 .sp
 296 int
 297 \fBTcl_EvalEx\fR(\fIinterp, script, numBytes, flags\fR)
 298 .sp
 299 int
 300 \fBTcl_GlobalEval\fR(\fIinterp, script\fR)
 301 .sp
 302 int
 303 \fBTcl_GlobalEvalObj\fR(\fIinterp, objPtr\fR)
 304 .sp
 305 int
 306 \fBTcl_VarEval\fR(\fIinterp, part, part, ... \fB(char *) NULL\fR)
 307 .sp
 308 int
 309 \fBTcl_VarEvalVA\fR(\fIinterp, argList\fR)
 310 .SH ARGUMENTS
 311 .AS Tcl_Interp **termPtr
 312 .AP Tcl_Interp *interp in
 313 Interpreter in which to execute the script.  The interpreter's result is
 314 modified to hold the result or error message from the script.
 315 .AP Tcl_Obj *objPtr in
 316 A Tcl value containing the script to execute.
 317 .AP int flags in
 318 ORed combination of flag bits that specify additional options.
 319 \fBTCL_EVAL_GLOBAL\fR and \fBTCL_EVAL_DIRECT\fR are currently supported.
 320 .AP "const char" *fileName in
 321 Name of a file containing a Tcl script.
 322 .AP int objc in
 323 The number of values in the array pointed to by \fIobjPtr\fR;
 324 this is also the number of words in the command.
 325 .AP Tcl_Obj **objv in
 326 Points to an array of pointers to values; each value holds the
 327 value of a single word in the command to execute.
 328 .AP int numBytes in
 329 The number of bytes in \fIscript\fR, not including any
 330 null terminating character.  If \-1, then all characters up to the
 331 first null byte are used.
 332 .AP "const char" *script in
 333 Points to first byte of script to execute (null-terminated and UTF-8).
 334 .AP char *part in
 335 String forming part of a Tcl script.
 336 .AP va_list argList in
 337 An argument list which must have been initialized using
 338 \fBva_start\fR, and cleared using \fBva_end\fR.
 339 .BE
 340
 341 .SH DESCRIPTION
 342 .PP
 343 The procedures described here are invoked to execute Tcl scripts in
 344 various forms.
 345 \fBTcl_EvalObjEx\fR is the core procedure and is used by many of the others.
 346 It executes the commands in the script stored in \fIobjPtr\fR
 347 until either an error occurs or the end of the script is reached.
 348 If this is the first time \fIobjPtr\fR has been executed,
 349 its commands are compiled into bytecode instructions
 350 which are then executed.  The
 351 bytecodes are saved in \fIobjPtr\fR so that the compilation step
 352 can be skipped if the value is evaluated again in the future.
 353 .PP
 354 The return value from \fBTcl_EvalObjEx\fR (and all the other procedures
 355 described here) is a Tcl completion code with
 356 one of the values \fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR,
 357 \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR, or possibly some other
 358 integer value originating in an extension.
 359 In addition, a result value or error message is left in \fIinterp\fR's
 360 result; it can be retrieved using \fBTcl_GetObjResult\fR.
 361 .PP
 362 \fBTcl_EvalFile\fR reads the file given by \fIfileName\fR and evaluates
 363 its contents as a Tcl script.  It returns the same information as
 364 \fBTcl_EvalObjEx\fR.
 365 If the file could not be read then a Tcl error is returned to describe
 366 why the file could not be read.
 367 The eofchar for files is
 368 .QW \e32
 369 (^Z) for all platforms. If you require a
 370 .QW ^Z
 371 in code for string comparison, you can use
 372 .QW \e032
 373 or
 374 .QW \eu001a ,
 375 which will be safely substituted by the Tcl interpreter into
 376 .QW ^Z .
 377 .PP
 378 \fBTcl_EvalObjv\fR executes a single pre-parsed command instead of a
 379 script.  The \fIobjc\fR and \fIobjv\fR arguments contain the values
 380 of the words for the Tcl command, one word in each value in
 381 \fIobjv\fR.  \fBTcl_EvalObjv\fR evaluates the command and returns
 382 a completion code and result just like \fBTcl_EvalObjEx\fR.
 383 The caller of \fBTcl_EvalObjv\fR has to manage the reference count of the
 384 elements of \fIobjv\fR, insuring that the values are valid until
 385 \fBTcl_EvalObjv\fR returns.
 386 .PP
 387 \fBTcl_Eval\fR is similar to \fBTcl_EvalObjEx\fR except that the script to
 388 be executed is supplied as a string instead of a value and no compilation
 389 occurs.  The string should be a proper UTF-8 string as converted by
 390 \fBTcl_ExternalToUtfDString\fR or \fBTcl_ExternalToUtf\fR when it is known
 391 to possibly contain upper ASCII characters whose possible combinations
 392 might be a UTF-8 special code.  The string is parsed and executed directly
 393 (using \fBTcl_EvalObjv\fR) instead of compiling it and executing the
 394 bytecodes.  In situations where it is known that the script will never be
 395 executed again, \fBTcl_Eval\fR may be faster than \fBTcl_EvalObjEx\fR.
 396  \fBTcl_Eval\fR returns a completion code and result just like
 397 \fBTcl_EvalObjEx\fR.  Note: for backward compatibility with versions before
 398 Tcl 8.0, \fBTcl_Eval\fR copies the value result in \fIinterp\fR to
 399 \fIinterp->result\fR (use is deprecated) where it can be accessed directly.
 400  This makes \fBTcl_Eval\fR somewhat slower than \fBTcl_EvalEx\fR, which
 401 does not do the copy.
 402 .PP
 403 \fBTcl_EvalEx\fR is an extended version of \fBTcl_Eval\fR that takes
 404 additional arguments \fInumBytes\fR and \fIflags\fR.  For the
 405 efficiency reason given above, \fBTcl_EvalEx\fR is generally preferred
 406 over \fBTcl_Eval\fR.
 407 .PP
 408 \fBTcl_GlobalEval\fR and \fBTcl_GlobalEvalObj\fR are older procedures
 409 that are now deprecated.  They are similar to \fBTcl_EvalEx\fR and
 410 \fBTcl_EvalObjEx\fR except that the script is evaluated in the global
 411 namespace and its variable context consists of global variables only
 412 (it ignores any Tcl procedures that are active).  These functions are
 413 equivalent to using the \fBTCL_EVAL_GLOBAL\fR flag (see below).
 414 .PP
 415 \fBTcl_VarEval\fR takes any number of string arguments
 416 of any length, concatenates them into a single string,
 417 then calls \fBTcl_Eval\fR to execute that string as a Tcl command.
 418 It returns the result of the command and also modifies
 419 \fIinterp->result\fR in the same way as \fBTcl_Eval\fR.
 420 The last argument to \fBTcl_VarEval\fR must be NULL to indicate the end
 421 of arguments.  \fBTcl_VarEval\fR is now deprecated.
 422 .PP
 423 \fBTcl_VarEvalVA\fR is the same as \fBTcl_VarEval\fR except that
 424 instead of taking a variable number of arguments it takes an argument
 425 list. Like \fBTcl_VarEval\fR, \fBTcl_VarEvalVA\fR is deprecated.
 426
 427 .SH "FLAG BITS"
 428 .PP
 429 Any ORed combination of the following values may be used for the
 430 \fIflags\fR argument to procedures such as \fBTcl_EvalObjEx\fR:
 431 .TP 23
 432 \fBTCL_EVAL_DIRECT\fR
 433 .
 434 This flag is only used by \fBTcl_EvalObjEx\fR; it is ignored by
 435 other procedures.  If this flag bit is set, the script is not
 436 compiled to bytecodes; instead it is executed directly
 437 as is done by \fBTcl_EvalEx\fR.  The
 438 \fBTCL_EVAL_DIRECT\fR flag is useful in situations where the
 439 contents of a value are going to change immediately, so the
 440 bytecodes will not be reused in a future execution.  In this case,
 441 it is faster to execute the script directly.
 442 .TP 23
 443 \fBTCL_EVAL_GLOBAL\fR
 444 .
 445 If this flag is set, the script is processed at global level.  This
 446 means that it is evaluated in the global namespace and its variable
 447 context consists of global variables only (it ignores any Tcl
 448 procedures that are active).
 449
 450 .SH "MISCELLANEOUS DETAILS"
 451 .PP
 452 During the processing of a Tcl command it is legal to make nested
 453 calls to evaluate other commands (this is how procedures and
 454 some control structures are implemented).
 455 If a code other than \fBTCL_OK\fR is returned
 456 from a nested \fBTcl_EvalObjEx\fR invocation,
 457 then the caller should normally return immediately,
 458 passing that same return code back to its caller,
 459 and so on until the top-level application is reached.
 460 A few commands, like \fBfor\fR, will check for certain
 461 return codes, like \fBTCL_BREAK\fR and \fBTCL_CONTINUE\fR, and process them
 462 specially without returning.
 463 .PP
 464 \fBTcl_EvalObjEx\fR keeps track of how many nested \fBTcl_EvalObjEx\fR
 465 invocations are in progress for \fIinterp\fR.
 466 If a code of \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR is
 467 about to be returned from the topmost \fBTcl_EvalObjEx\fR
 468 invocation for \fIinterp\fR,
 469 it converts the return code to \fBTCL_ERROR\fR
 470 and sets \fIinterp\fR's result to an error message indicating that
 471 the \fBreturn\fR, \fBbreak\fR, or \fBcontinue\fR command was
 472 invoked in an inappropriate place.
 473 This means that top-level applications should never see a return code
 474 from \fBTcl_EvalObjEx\fR other then \fBTCL_OK\fR or \fBTCL_ERROR\fR.
 475
 476 .SH KEYWORDS
 477 execute, file, global, result, script, value