Tcl_ResetResult man page on BSDOS

Man page or keyword search:  
man Server   6284 pages
apropos Keyword Search (all sections)
Output format
BSDOS logo
[printable version]



Tcl_SetResult(3)      Tcl Library Procedures	 Tcl_SetResult(3)

_________________________________________________________________

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

SYNOPSIS
       #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
       Tcl_Interp     *interp	 (out)	   Interpreter	    whose
					   result  is to be modi-
					   fied.

       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
       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 guaran-
       teed  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 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  string points to an area of
       memory that is likely to be overwritten when Tcl_SetResult

Tcl			       7.5				1

Tcl_SetResult(3)      Tcl Library Procedures	 Tcl_SetResult(3)

       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 alloca-
       tors.  When Tcl	no  longer  needs  the	storage	 for  the
       string, it will call freeProc.  FreeProc should have argu-
       ments 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_SetRe-
       sult re-initializes 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 dis-
       pose 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_ResetRe-
       sult 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_AppendEle-
       ment will add a space character to  interp's  result  just
       before  adding the new list element, so that the list ele-
       ments 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

Tcl			       7.5				2

Tcl_SetResult(3)      Tcl Library Procedures	 Tcl_SetResult(3)

       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 dynam-
       ically allocated.  It leaves the result in its normal ini-
       tialized	 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_SetError-
       Code.

       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 or clear error state.
       Tcl_FreeResult  is  most commonly used when a procedure is
       about to replace one result value with another.

SEE ALSO
       Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_Interp

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

Tcl			       7.5				3

[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server BSDOS

List of man pages available for BSDOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net