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_AppendElement,  Tcl_ResetResult, Tcl_TransferRe-
       sult - 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_ResetResult(interp)

       Tcl_TransferResult(sourceInterp,	code, targetInterp)

       Tcl_AppendElement(interp, element)

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

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

       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
					       TCL_VOLATILE.

       Tcl_Interp *sourceInterp	(in)	       Interpreter that	the result and
					       return options should be	trans-
					       ferred from.

       Tcl_Interp *targetInterp	(in)	       Interpreter that	the result and
					       return options should be	trans-
					       ferred to.

       int code	(in)			       Return code value that controls
					       transfer	of return options.
______________________________________________________________________________

DESCRIPTION
       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-
       sentation.

       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 (char *)NULL.

       Tcl_TransferResult transfers interpreter	 state	from  sourceInterp  to
       targetInterp.  The  two interpreters must have been created in the same
       thread.	If sourceInterp	and targetInterp  are  the  same,  nothing  is
       done.  Otherwise, Tcl_TransferResult moves the result from sourceInterp
       to targetInterp,	and resets the result in sourceInterp. It  also	 moves
       the  return  options  dictionary	as controlled by the return code value
       code in the same	manner as Tcl_GetReturnOptions.

DEPRECATED INTERFACES
   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  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.

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(
		      void *blockPtr);

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

REFERENCE COUNT	MANAGEMENT
       The  interpreter	 result	is one of the main places that owns references
       to values, along	with the bytecode  execution  stack,  argument	lists,
       variables, and the list and dictionary collection values.

       Tcl_SetObjResult	 takes	a  value  with	an  arbitrary  reference count
       (specifically including zero) and guarantees to increment the reference
       count. If code wishes to	continue using the value after setting	it  as
       the  result,  it	 should	 add its own reference to it with Tcl_IncrRef-
       Count.

       Tcl_GetObjResult	returns	the current  interpreter  result  value.  This
       will have a reference count of at least 1. If the caller	wishes to keep
       the interpreter result value, it	should increment its reference count.

       Tcl_GetStringResult  does  not  manipulate  reference  counts,  but the
       string it returns is owned by (and has a	lifetime  controlled  by)  the
       current	interpreter result value; it should be copied instead of being
       relied upon to persist after the	next Tcl API call, as most Tcl	opera-
       tions can modify	the interpreter	result.

       Tcl_SetResult, Tcl_AppendResult,	Tcl_AppendElement, and Tcl_ResetResult
       all  modify  the	interpreter result. They may cause the old interpreter
       result to have its reference count decremented and  a  new  interpreter
       result  to  be  allocated.  After  they have been called, the reference
       count of	the interpreter	result is guaranteed to	be 1.

SEE ALSO
       Tcl_AddErrorInfo, Tcl_CreateObjCommand,	Tcl_SetErrorCode,  Tcl_Interp,
       Tcl_GetReturnOptions

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

Tcl				      9.0		      Tcl_SetResult(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=Tcl_GetStringResult.tcl90&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help