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

FreeBSD Manual Pages

  
 
  

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

______________________________________________________________________________

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

SYNOPSIS
       #include	<tcl.h>

       Tcl_SetObjResult(interp,	objPtr)

       Tcl_Obj *
       Tcl_GetObjResult(interp)

       Tcl_SetResult(interp, result, freeProc)

       const char *
       Tcl_GetStringResult(interp)

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

       Tcl_AppendResultVA(interp, argList)

       Tcl_AppendElement(interp, element)

       Tcl_ResetResult(interp)

       Tcl_FreeResult(interp)

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

       Tcl_Obj *objPtr (in)		   Object value	to become  result  for
					   interp.

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

       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 re-
					   lease   storage   at	  result,   or
					   TCL_STATIC,	   TCL_DYNAMIC,	    or
					   TCL_VOLATILE.

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

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

       Tcl_SetObjResult	 arranges  for objPtr to be the	result for interp, re-
       placing any existing result.  The result	is left	pointing to the	object
       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 object is decremented and the old result object is
       freed if	no references to it remain.

       Tcl_GetObjResult	returns	the result for interp as an object.   The  ob-
       ject's  reference  count	is not incremented; if the caller needs	to re-
       tain a long-term	pointer	to the object they should use Tcl_IncrRefCount
       to  increment  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 an object by a	Tcl_SetObjResult call, the object form
       will  be	 converted  to	a string and returned.	If the object's	string
       representation contains null bytes, this	conversion will	lose  informa-
       tion.   For this	reason,	programmers are	encouraged to write their code
       to use the new object API procedures and	to call	 Tcl_GetObjResult  in-
       stead.

       Tcl_ResetResult	clears	the result for interp and leaves the result in
       its normal empty	initialized state.  If the result is  an  object,  its
       reference  count	 is  decremented and the result	is left	pointing to an
       unshared	object representing an empty string.  If the result is	a  dy-
       namically 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.

OLD STRING PROCEDURES
       Use of the following procedures (is deprecated  since  they  manipulate
       the  Tcl	 result	as a string.  Procedures such as Tcl_SetObjResult that
       manipulate the result as	an object 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.

DIRECT ACCESS TO INTERP->RESULT	IS DEPRECATED
       It used to be legal for programs	to directly read and write interp-_re-
       sult to manipulate  the	interpreter  result.   Direct  access  to  in-
       terp-_result  is	 now  strongly	deprecated because it can make the re-
       sult's string and object	forms inconsistent.   Programs	should	always
       read  the  result  using	 the  procedures  Tcl_GetObjResult or Tcl_Get-
       StringResult, and write the result using	Tcl_SetObjResult or Tcl_SetRe-
       sult.

THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT
       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.

SEE ALSO
       Tcl_AddErrorInfo, Tcl_CreateObjCommand, Tcl_SetErrorCode, Tcl_Interp

KEYWORDS
       append,	command,  element,  list, object, result, return value,	inter-
       preter

Tcl				      8.0		      Tcl_SetResult(3)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | OLD STRING PROCEDURES | DIRECT ACCESS TO INTERP->RESULT IS DEPRECATED | THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tcl_AppendElement.tcl85&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help