2 '\" Copyright (c) 1989-1993 The Regents of the University of California.
3 '\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
5 '\" See the file "license.terms" for information on usage and redistribution
6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
8 .TH Tcl_SetResult 3 8.0 Tcl "Tcl Library Procedures"
9 .\" The -*- nroff -*- definitions below are for supplemental macros used
10 .\" in Tcl/Tk manual entries.
12 .\" .AP type name in/out ?indent?
13 .\" Start paragraph describing an argument to a library procedure.
14 .\" type is type of argument (int, etc.), in/out is either "in", "out",
15 .\" or "in/out" to describe whether procedure reads or modifies arg,
16 .\" and indent is equivalent to second arg of .IP (shouldn't ever be
17 .\" needed; use .AS below instead)
20 .\" Give maximum sizes of arguments for setting tab stops. Type and
21 .\" name are examples of largest possible arguments that will be passed
22 .\" to .AP later. If args are omitted, default tab stops are used.
25 .\" Start box enclosure. From here until next .BE, everything will be
26 .\" enclosed in one large box.
29 .\" End of box enclosure.
32 .\" Begin code excerpt.
37 .\" .VS ?version? ?br?
38 .\" Begin vertical sidebar, for use in marking newly-changed parts
39 .\" of man pages. The first argument is ignored and used for recording
40 .\" the version when the .VS was added, so that the sidebars can be
41 .\" found and removed when they reach a certain age. If another argument
42 .\" is present, then a line break is forced before starting the sidebar.
45 .\" End of vertical sidebar.
48 .\" Begin an indented unfilled display.
51 .\" End of indented unfilled display.
54 .\" Start of list of standard options for a Tk widget. The manpage
55 .\" argument defines where to look up the standard options; if
56 .\" omitted, defaults to "options". The options follow on successive
57 .\" lines, in three columns separated by tabs.
60 .\" End of list of standard options for a Tk widget.
62 .\" .OP cmdName dbName dbClass
63 .\" Start of description of a specific option. cmdName gives the
64 .\" option's name as specified in the class command, dbName gives
65 .\" the option's name in the option database, and dbClass gives
66 .\" the option's class in the option database.
69 .\" Print arg1 underlined, then print arg2 normally.
72 .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
75 .\" Print an open parenthesis, arg1 in quotes, then arg2 normally
76 .\" (for trailing punctuation) and then a closing parenthesis.
78 .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
82 .\" # Start an argument description
86 . ie !"\\$2"" .TP \\n()Cu
91 \&\\$1 \\fI\\$2\\fP (\\$3)
104 .\" # define tabbing values for .AP
107 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
110 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
111 .nr )C \\n()Bu+\\w'(in/out)'u+2n
113 .AS Tcl_Interp Tcl_CreateInterp in/out
114 .\" # BS - start boxed text
115 .\" # ^y = starting y location
123 .if n \l'\\n(.lu\(ul'
126 .\" # BE - end boxed text (draw box now)
131 .ie n \l'\\n(^lu\(ul'
133 .\" Draw four-sided box normally, but don't draw top of
134 .\" box if the box started on an earlier page.
136 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
139 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
146 .\" # VS - start vertical sidebar
147 .\" # ^Y = starting y location
148 .\" # ^v = 1 (for troff; for nroff this doesn't matter)
152 .ie n 'mc \s12\(br\s0
155 .\" # VE - end of vertical sidebar
163 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
170 .\" # Special macro to handle page bottom: finish off current
171 .\" # box/sidebar if in box/sidebar mode, then invoked standard
172 .\" # page bottom macro.
179 .\" Draw three-sided box if this is the box's first page,
180 .\" draw two sides but no top otherwise.
181 .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
182 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
185 .nr ^x \\n(^tu+1v-\\n(^Yu
186 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
199 .\" # DS - begin display
205 .\" # DE - end display
211 .\" # SO - start of list of standard options
213 'ie '\\$1'' .ds So \\fBoptions\\fR
214 'el .ds So \\fB\\$1\\fR
215 .SH "STANDARD OPTIONS"
221 .\" # SE - end of list of standard options
226 See the \\*(So manual entry for details on the standard options.
228 .\" # OP - start of full description for a single option
233 Command-Line Name: \\fB\\$1\\fR
234 Database Name: \\fB\\$2\\fR
235 Database Class: \\fB\\$3\\fR
239 .\" # CS - begin code excerpt
245 .\" # CE - end code excerpt
250 .\" # UL - underline word
254 .\" # QW - apply quotation marks to word
256 .ie '\\*(lq'"' ``\\$1''\\$2
257 .\"" fix emacs highlighting
258 .el \\*(lq\\$1\\*(rq\\$2
260 .\" # PQ - apply parens and quotation marks to word
262 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
263 .\"" fix emacs highlighting
264 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
266 .\" # QR - quoted range
268 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
269 .\"" fix emacs highlighting
270 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
272 .\" # MT - "empty" string
278 Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult, Tcl_AppendResult, Tcl_AppendResultVA, Tcl_AppendElement, Tcl_ResetResult, Tcl_TransferResult, Tcl_FreeResult \- manipulate Tcl result
281 \fB#include <tcl.h>\fR
283 \fBTcl_SetObjResult\fR(\fIinterp, objPtr\fR)
286 \fBTcl_GetObjResult\fR(\fIinterp\fR)
288 \fBTcl_SetResult\fR(\fIinterp, result, freeProc\fR)
291 \fBTcl_GetStringResult\fR(\fIinterp\fR)
293 \fBTcl_AppendResult\fR(\fIinterp, result, result, ... , \fB(char *) NULL\fR)
295 \fBTcl_AppendResultVA\fR(\fIinterp, argList\fR)
297 \fBTcl_ResetResult\fR(\fIinterp\fR)
300 \fBTcl_TransferResult\fR(\fIsourceInterp, result, targetInterp\fR)
303 \fBTcl_AppendElement\fR(\fIinterp, element\fR)
305 \fBTcl_FreeResult\fR(\fIinterp\fR)
307 .AS Tcl_FreeProc sourceInterp out
308 .AP Tcl_Interp *interp out
309 Interpreter whose result is to be modified or read.
310 .AP Tcl_Obj *objPtr in
311 Tcl value to become result for \fIinterp\fR.
313 String value to become result for \fIinterp\fR or to be
314 appended to the existing result.
315 .AP "const char" *element in
316 String value to append as a list element
317 to the existing result of \fIinterp\fR.
318 .AP Tcl_FreeProc *freeProc in
319 Address of procedure to call to release storage at
320 \fIresult\fR, or \fBTCL_STATIC\fR, \fBTCL_DYNAMIC\fR, or
322 .AP va_list argList in
323 An argument list which must have been initialized using
324 \fBva_start\fR, and cleared using \fBva_end\fR.
325 .AP Tcl_Interp *sourceInterp in
327 Interpreter that the result and error information should be copied from.
329 .AP Tcl_Interp *targetInterp in
331 Interpreter that the result and error information should be copied to.
335 If \fBTCL_OK\fR, only copy the result. If \fBTCL_ERROR\fR, copy the error
341 The procedures described here are utilities for manipulating the
342 result value in a Tcl interpreter.
343 The interpreter result may be either a Tcl value or a string.
344 For example, \fBTcl_SetObjResult\fR and \fBTcl_SetResult\fR
345 set the interpreter result to, respectively, a value and a string.
346 Similarly, \fBTcl_GetObjResult\fR and \fBTcl_GetStringResult\fR
347 return the interpreter result as a value and as a string.
348 The procedures always keep the string and value forms
349 of the interpreter result consistent.
350 For example, if \fBTcl_SetObjResult\fR is called to set
351 the result to a value,
352 then \fBTcl_GetStringResult\fR is called,
353 it will return the value's string representation.
355 \fBTcl_SetObjResult\fR
356 arranges for \fIobjPtr\fR to be the result for \fIinterp\fR,
357 replacing any existing result.
358 The result is left pointing to the value
359 referenced by \fIobjPtr\fR.
360 \fIobjPtr\fR's reference count is incremented
361 since there is now a new reference to it from \fIinterp\fR.
362 The reference count for any old result value
363 is decremented and the old result value is freed if no
364 references to it remain.
366 \fBTcl_GetObjResult\fR returns the result for \fIinterp\fR as a value.
367 The value's reference count is not incremented;
368 if the caller needs to retain a long-term pointer to the value
369 they should use \fBTcl_IncrRefCount\fR to increment its reference count
370 in order to keep it from being freed too early or accidentally changed.
373 arranges for \fIresult\fR to be the result for the current Tcl
374 command in \fIinterp\fR, replacing any existing result.
375 The \fIfreeProc\fR argument specifies how to manage the storage
376 for the \fIresult\fR argument;
377 it is discussed in the section
378 \fBTHE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT\fR below.
379 If \fIresult\fR is \fBNULL\fR, then \fIfreeProc\fR is ignored
380 and \fBTcl_SetResult\fR
381 re-initializes \fIinterp\fR's result to point to an empty string.
383 \fBTcl_GetStringResult\fR returns the result for \fIinterp\fR as a string.
384 If the result was set to a value by a \fBTcl_SetObjResult\fR call,
385 the value form will be converted to a string and returned.
386 If the value's string representation contains null bytes,
387 this conversion will lose information.
388 For this reason, programmers are encouraged to
389 write their code to use the new value API procedures
390 and to call \fBTcl_GetObjResult\fR instead.
392 \fBTcl_ResetResult\fR clears the result for \fIinterp\fR
393 and leaves the result in its normal empty initialized state.
394 If the result is a value,
395 its reference count is decremented and the result is left
396 pointing to an unshared value representing an empty string.
397 If the result is a dynamically allocated string, its memory is free*d
398 and the result is left as a empty string.
399 \fBTcl_ResetResult\fR also clears the error state managed by
400 \fBTcl_AddErrorInfo\fR, \fBTcl_AddObjErrorInfo\fR,
401 and \fBTcl_SetErrorCode\fR.
403 \fBTcl_AppendResult\fR makes it easy to build up Tcl results in pieces.
404 It takes each of its \fIresult\fR arguments and appends them in order
405 to the current result associated with \fIinterp\fR.
406 If the result is in its initialized empty state (e.g. a command procedure
407 was just invoked or \fBTcl_ResetResult\fR was just called),
408 then \fBTcl_AppendResult\fR sets the result to the concatenation of
409 its \fIresult\fR arguments.
410 \fBTcl_AppendResult\fR may be called repeatedly as additional pieces
411 of the result are produced.
412 \fBTcl_AppendResult\fR takes care of all the
413 storage management issues associated with managing \fIinterp\fR's
414 result, such as allocating a larger result area if necessary.
415 It also manages conversion to and from the \fIresult\fR field of the
416 \fIinterp\fR so as to handle backward-compatibility with old-style
418 Any number of \fIresult\fR arguments may be passed in a single
419 call; the last argument in the list must be a NULL pointer.
421 \fBTcl_AppendResultVA\fR is the same as \fBTcl_AppendResult\fR except that
422 instead of taking a variable number of arguments it takes an argument list.
425 \fBTcl_TransferResult\fR moves a result from one interpreter to another,
426 optionally (dependent on the \fIresult\fR parameter) including the error
427 information dictionary as well. The interpreters must be in the same thread.
428 The source interpreter will have its result reset by this operation.
430 .SH "DEPRECATED INTERFACES"
431 .SS "OLD STRING PROCEDURES"
433 Use of the following procedures (is deprecated
434 since they manipulate the Tcl result as a string.
435 Procedures such as \fBTcl_SetObjResult\fR
436 that manipulate the result as a value
437 can be significantly more efficient.
439 \fBTcl_AppendElement\fR is similar to \fBTcl_AppendResult\fR in
440 that it allows results to be built up in pieces.
441 However, \fBTcl_AppendElement\fR takes only a single \fIelement\fR
442 argument and it appends that argument to the current result
443 as a proper Tcl list element.
444 \fBTcl_AppendElement\fR adds backslashes or braces if necessary
445 to ensure that \fIinterp\fR's result can be parsed as a list and that
446 \fIelement\fR will be extracted as a single element.
447 Under normal conditions, \fBTcl_AppendElement\fR will add a space
448 character to \fIinterp\fR's result just before adding the new
449 list element, so that the list elements in the result are properly
451 However if the new list element is the first in a list or sub-list
452 (i.e. \fIinterp\fR's current result is empty, or consists of the
455 or ends in the characters
457 then no space is added.
459 \fBTcl_FreeResult\fR performs part of the work
460 of \fBTcl_ResetResult\fR.
461 It frees up the memory associated with \fIinterp\fR's result.
462 It also sets \fIinterp->freeProc\fR to zero, but does not
463 change \fIinterp->result\fR or clear error state.
464 \fBTcl_FreeResult\fR is most commonly used when a procedure
465 is about to replace one result value with another.
466 .SS "DIRECT ACCESS TO INTERP->RESULT"
468 It used to be legal for programs to
469 directly read and write \fIinterp->result\fR
470 to manipulate the interpreter result. The Tcl headers no longer
471 permit this access by default, and C code still doing this must
472 be updated to use supported routines \fBTcl_GetObjResult\fR,
473 \fBTcl_GetStringResult\fR, \fBTcl_SetObjResult\fR, and \fBTcl_SetResult\fR.
474 As a migration aid, access can be restored with the compiler directive
476 #define USE_INTERP_RESULT
478 but this is meant only to offer life support to otherwise dead code.
479 .SH "THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT"
481 \fBTcl_SetResult\fR's \fIfreeProc\fR argument specifies how
482 the Tcl system is to manage the storage for the \fIresult\fR argument.
483 If \fBTcl_SetResult\fR or \fBTcl_SetObjResult\fR are called
484 at a time when \fIinterp\fR holds a string result,
485 they do whatever is necessary to dispose of the old string result
486 (see the \fBTcl_Interp\fR manual entry for details on this).
488 If \fIfreeProc\fR is \fBTCL_STATIC\fR it means that \fIresult\fR
489 refers to an area of static storage that is guaranteed not to be
490 modified until at least the next call to \fBTcl_Eval\fR.
492 is \fBTCL_DYNAMIC\fR it means that \fIresult\fR was allocated with a call
493 to \fBTcl_Alloc\fR and is now the property of the Tcl system.
494 \fBTcl_SetResult\fR will arrange for the string's storage to be
495 released by calling \fBTcl_Free\fR when it is no longer needed.
496 If \fIfreeProc\fR is \fBTCL_VOLATILE\fR it means that \fIresult\fR
497 points to an area of memory that is likely to be overwritten when
498 \fBTcl_SetResult\fR returns (e.g. it points to something in a stack frame).
499 In this case \fBTcl_SetResult\fR will make a copy of the string in
500 dynamically allocated storage and arrange for the copy to be the
501 result for the current Tcl command.
503 If \fIfreeProc\fR is not one of the values \fBTCL_STATIC\fR,
504 \fBTCL_DYNAMIC\fR, and \fBTCL_VOLATILE\fR, then it is the address
505 of a procedure that Tcl should call to free the string.
506 This allows applications to use non-standard storage allocators.
507 When Tcl no longer needs the storage for the string, it will
508 call \fIfreeProc\fR. \fIFreeProc\fR should have arguments and
509 result that match the type \fBTcl_FreeProc\fR:
512 typedef void \fBTcl_FreeProc\fR(
513 char *\fIblockPtr\fR);
516 When \fIfreeProc\fR is called, its \fIblockPtr\fR will be set to
517 the value of \fIresult\fR passed to \fBTcl_SetResult\fR.
519 Tcl_AddErrorInfo, Tcl_CreateObjCommand, Tcl_SetErrorCode, Tcl_Interp
521 append, command, element, list, value, result, return value, interpreter
OSDN Git Service
