Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Tcl_SetResult(3)	    Tcl	Library	Procedures	      Tcl_SetResult(3)


       Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult,
       Tcl_AppendResult, Tcl_AppendResultVA,  Tcl_AppendElement,  Tcl_ResetRe-
       sult, Tcl_TransferResult, Tcl_FreeResult	- manipulate Tcl result

       #include	<tcl.h>

       Tcl_SetObjResult(interp,	objPtr)

       Tcl_Obj *

       Tcl_SetResult(interp, result, freeProc)

       const char *

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

       Tcl_AppendResultVA(interp, argList)


       Tcl_TransferResult(sourceInterp,	result,	targetInterp)		       |

       Tcl_AppendElement(interp, element)


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

       Tcl_Obj *objPtr (in)		       Tcl value to become result  for

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

       const char *element (in)		       String  value  to  append  as a
					       list element  to	 the  existing
					       result of interp.

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

       va_list argList (in)		       An  argument  list  which  must
					       have   been  initialized	 using
					       va_start,  and  cleared	 using

       Tcl_Interp *sourceInterp	(in)	       Interpreter that	the result and |
					       error  information  should   be |
					       copied from.

       Tcl_Interp *targetInterp	(in)	       Interpreter that	the result and |
					       error  information  should   be |
					       copied to.

       int result (in)			       If  TCL_OK,  only  copy the re- |
					       sult. If	 TCL_ERROR,  copy  the |
					       error information as well.

       The procedures described	here are utilities for manipulating the	result
       value in	a Tcl interpreter.  The	interpreter result may be either a Tcl
       value or	a string.  For example,	Tcl_SetObjResult and Tcl_SetResult set
       the interpreter result to, respectively,	a value	and a  string.	 Simi-
       larly,  Tcl_GetObjResult	and Tcl_GetStringResult	return the interpreter
       result as a value and as	a string.   The	 procedures  always  keep  the
       string and value	forms of the interpreter result	consistent.  For exam-
       ple, if Tcl_SetObjResult	is called to set the result to a  value,  then
       Tcl_GetStringResult is called, it will return the value's string	repre-

       Tcl_SetObjResult	arranges for objPtr to be the result for  interp,  re-
       placing	any existing result.  The result is left pointing to the value
       referenced by objPtr.  objPtr's reference count	is  incremented	 since
       there  is  now  a new reference to it from interp.  The reference count
       for any old result value	is decremented and the	old  result  value  is
       freed if	no references to it remain.

       Tcl_GetObjResult	returns	the result for interp as a value.  The value's
       reference count is not incremented; if the caller  needs	 to  retain  a
       long-term  pointer to the value they should use Tcl_IncrRefCount	to in-
       crement its reference count in order to keep it from  being  freed  too
       early or	accidentally changed.

       Tcl_SetResult  arranges for result to be	the result for the current Tcl
       command in interp, replacing any	existing result.  The  freeProc	 argu-
       ment specifies how to manage the	storage	for the	result argument; it is
       discussed in the	section	THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT be-
       low.  If	result is NULL,	then freeProc is ignored and Tcl_SetResult re-
       initializes interp's result to point to an empty	string.

       Tcl_GetStringResult returns the result for interp as a string.  If  the
       result  was  set	 to a value by a Tcl_SetObjResult call,	the value form
       will be converted to a string and returned.  If the value's string rep-
       resentation contains null bytes,	this conversion	will lose information.
       For this	reason,	programmers are	encouraged to write their code to  use
       the new value API procedures and	to call	Tcl_GetObjResult instead.

       Tcl_ResetResult	clears	the result for interp and leaves the result in
       its normal empty	initialized state.  If the result is a value, its ref-
       erence  count  is decremented and the result is left pointing to	an un-
       shared value representing an empty string.  If the result is a  dynami-
       cally  allocated	string,	its memory is free*d and the result is left as
       a empty string.	Tcl_ResetResult	also clears the	error state managed by
       Tcl_AddErrorInfo, Tcl_AddObjErrorInfo, and Tcl_SetErrorCode.

       Tcl_AppendResult	 makes	it easy	to build up Tcl	results	in pieces.  It
       takes each of its result	arguments and appends them  in	order  to  the
       current	result	associated  with interp.  If the result	is in its ini-
       tialized	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 result 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	 asso-
       ciated  with  managing interp's result, such as allocating a larger re-
       sult area if necessary.	It also	manages	conversion to and from the re-
       sult  field  of	the interp so as to handle backward-compatibility with
       old-style extensions.  Any number of result arguments may be passed  in
       a single	call; the last argument	in the list must be a NULL pointer.

       Tcl_AppendResultVA  is the same as Tcl_AppendResult except that instead
       of taking a variable number of arguments	it takes an argument list.

       Tcl_TransferResult moves	a result from one interpreter to another,  op- |
       tionally	(dependent on the result parameter) including the error	infor- |
       mation dictionary as well. The interpreters must	be in the same thread. |
       The source interpreter will have	its result reset by this operation.

       Use of the following procedures is deprecated since they	manipulate the
       Tcl result as a string.	Procedures such	as Tcl_SetObjResult  that  ma-
       nipulate	the result as a	value can be significantly more	efficient.

       Tcl_AppendElement  is similar to	Tcl_AppendResult in that it allows re-
       sults to	be built up in pieces.	However, Tcl_AppendElement takes  only
       a  single  element argument and it appends that argument	to the current
       result as a proper Tcl  list  element.	Tcl_AppendElement  adds	 back-
       slashes	or  braces  if necessary to ensure that	interp's result	can be
       parsed as a list	and that element will be extracted as  a  single  ele-
       ment.   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.  How-
       ever 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_FreeResult performs part of the work	of Tcl_ResetResult.  It	 frees
       up  the	memory	associated  with  interp's  result.   It also sets in-
       terp-_freeProc to zero, but does	not change interp-_result or clear er-
       ror  state.   Tcl_FreeResult  is	most commonly used when	a procedure is
       about to	replace	one result value with another.

       It used to be legal for programs	to directly read and write interp-_re-
       sult  to	 manipulate the	interpreter result.  The Tcl headers no	longer
       permit this access by default, and C code still doing this must be  up-
       dated  to use supported routines	Tcl_GetObjResult, Tcl_GetStringResult,
       Tcl_SetObjResult, and Tcl_SetResult.  As	a migration aid, access	can be
       restored	with the compiler directive
	      #define USE_INTERP_RESULT
       but this	is meant only to offer life support to otherwise dead code.

       Tcl_SetResult's	freeProc  argument  specifies how the Tcl system is to
       manage the storage  for	the  result  argument.	 If  Tcl_SetResult  or
       Tcl_SetObjResult	 are  called  at a time	when interp holds a string re-
       sult, they do whatever is necessary to dispose of the old string	result
       (see the	Tcl_Interp manual entry	for details on this).

       If  freeProc  is	 TCL_STATIC  it	means that result 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	result
       was allocated with a call to Tcl_Alloc and is now the property  of  the
       Tcl  system.  Tcl_SetResult will	arrange	for the	string's storage to be
       released	by calling Tcl_Free when it is no longer needed.  If  freeProc
       is  TCL_VOLATILE	 it means that result 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 result for the current Tcl command.

       If  freeProc  is	 not  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 allocators.  When Tcl no	 longer	 needs	the  storage  for  the
       string,	it  will call freeProc.	FreeProc should	have arguments and re-
       sult 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  re-
       sult passed to Tcl_SetResult.

       Tcl_AddErrorInfo, Tcl_CreateObjCommand, Tcl_SetErrorCode, Tcl_Interp

       append,	command,  element,  list,  value, result, return value,	inter-

Tcl				      8.0		      Tcl_SetResult(3)


Want to link to this manual page? Use this URL:

home | help