Tcl_SetResult(3Tcl)					   Tcl_SetResult(3Tcl)

NAME    [Toc]    [Back]

     Tcl_SetResult, Tcl_AppendResult, Tcl_AppendElement, Tcl_ResetResult -
     manipulate	Tcl result string

SYNOPSIS    [Toc]    [Back]

     #include <tcl.h>

     Tcl_SetResult(interp, string, freeProc)

     Tcl_AppendResult(interp, string, string, ... , (char *) NULL)

     Tcl_AppendElement(interp, string)					      |

     Tcl_ResetResult(interp)

     Tcl_FreeResult(interp)

ARGUMENTS    [Toc]    [Back]

     Tcl_Interp	    *interp    (out)	 Interpreter whose result is to	be
					 modified.

     char	    *string    (in)	 String	value to become	result for
					 interp	or to be appended to existing
					 result.

     Tcl_FreeProc   *freeProc  (in)	 Address of procedure to call to
					 release storage at string, or
					 TCL_STATIC, TCL_DYNAMIC, or
					 TCL_VOLATILE.

DESCRIPTION    [Toc]    [Back]

     The procedures described here are utilities for setting the result/error
     string in a Tcl interpreter.

     Tcl_SetResult arranges for	string to be the return	string for the current
     Tcl command in interp, replacing any existing result.  If freeProc	is
     TCL_STATIC	it means that string refers to an area of static storage that
     is	guaranteed not to be modified until at least the next call to
     Tcl_Eval.	If freeProc is TCL_DYNAMIC it means that string	was allocated
     with a call to malloc() and is now	the property of	the Tcl	system.
     Tcl_SetResult will	arrange	for the	string's storage to be released	by
     calling free() when it is no longer needed.  If freeProc is TCL_VOLATILE
     it	means that string points to an area of memory that is likely to	be
     overwritten when Tcl_SetResult returns (e.g. it points to something in a
     stack frame).  In this case Tcl_SetResult will make a copy	of the string
     in	dynamically allocated storage and arrange for the copy to be the
     return string for the current Tcl command.

     If	freeProc isn't one of the values TCL_STATIC, TCL_DYNAMIC, and
     TCL_VOLATILE, then	it is the address of a procedure that Tcl should call
     to	free the string.  This allows applications to use non-standard storage



									Page 1






Tcl_SetResult(3Tcl)					   Tcl_SetResult(3Tcl)



     allocators.  When Tcl no longer needs the storage for the string, it will
     call freeProc.  FreeProc should have arguments and	result that match the
     type Tcl_FreeProc:

	  typedef void Tcl_FreeProc(char *blockPtr);

     When freeProc is called, its blockPtr will	be set to the value of string
     passed to Tcl_SetResult.

     If	string is NULL,	then freeProc is ignored and Tcl_SetResult reinitializes
 interp's result to point to the pre-allocated result area,
     with an empty string in the result	area.

     If	Tcl_SetResult is called	at a time when interp holds a result,
     Tcl_SetResult does	whatever is necessary to dispose of the	old result
     (see the Tcl_Interp manual	entry for details on this).

     Tcl_AppendResult makes it easy to build up	Tcl results in pieces.	It
     takes each	of its string arguments	and appends them in order to the
     current result associated with interp.  If	the result is in its
     initialized empty state (e.g. a command procedure was just	invoked	or
     Tcl_ResetResult was just called), then Tcl_AppendResult sets the result
     to	the concatenation of its string	arguments.  Tcl_AppendResult may be
     called repeatedly as additional pieces of the result are produced.
     Tcl_AppendResult takes care of all	the storage management issues
     associated	with managing interp's result, such as allocating a larger
     result area if necessary.	Any number of string arguments may be passed
     in	a single call;	the last argument in the list must be a	NULL pointer.

     Tcl_AppendElement is similar to Tcl_AppendResult in that it allows
     results to	be built up in pieces.	However, Tcl_AppendElement takes only
     a single string argument and it appends that argument to the current
     result as a proper	Tcl list element.  Tcl_AppendElement adds backslashes
     or	braces if necessary to ensure that interp's result can be parsed as a
     list and that string will be extracted as a single	element.  Under	normal
     conditions, Tcl_AppendElement will	add a space character to interp's
     result just before	adding the new list element, so	that the list elements
     in	the result are properly	separated.  However if the new list element is|
     the first in a list or sub-list (i.e. interp's current result is empty,  |
     or	consists of the	single character ``{'',	or ends	in the characters ``  |
     {'') then no space	is added.

     Tcl_ResetResult clears the	result for interp, freeing the memory
     associated	with it	if the current result was dynamically allocated.  It
     leaves the	result in its normal initialized state with interp->result
     pointing to a static buffer containing TCL_RESULT_SIZE characters,	of
     which the first character is zero.	 Tcl_ResetResult also clears the error
     state managed by Tcl_AddErrorInfo and Tcl_SetErrorCode.

     Tcl_FreeResult is a macro that performs part of the work of
     Tcl_ResetResult.  It frees	up the memory associated with interp's result
     and sets interp->freeProc to zero,	but it doesn't change interp->result



									Page 2






Tcl_SetResult(3Tcl)					   Tcl_SetResult(3Tcl)



     or	clear error state.  Tcl_FreeResult is most commonly used when a
     procedure is about	to replace one result value with another.

SEE ALSO    [Toc]    [Back]

     Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_Interp

KEYWORDS    [Toc]    [Back]

     append, command, element, list, result, return value, interpreter


									PPPPaaaaggggeeee 3333