home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / src / Tools / vtcl / doc / SetResult.3 < prev    next >
Encoding:
Text File  |  1995-07-10  |  7.1 KB  |  170 lines
  1. '\"
  2. '\" Copyright (c) 1989-1993 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/tcl/man/RCS/SetResult.3,v 1.12 93/04/03 15:05:59 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. '\"----------------------------------------------------------------------------
  24. '\"    @(#) SetResult.3 26.1 93/10/22 SCOINC
  25. '\"
  26. '\"     Copyright (C) The Santa Cruz Operation, 1992-1993.
  27. '\"     This Module contains Proprietary Information of
  28. '\"    The Santa Cruz Operation, and should be treated as Confidential.
  29. '\"----------------------------------------------------------------------------
  30. .so ../man.macros
  31. .HS Tcl_SetResult tclc 7.0
  32. .BS
  33. .SH NAME
  34. Tcl_SetResult, Tcl_AppendResult, Tcl_AppendElement, Tcl_ResetResult \- manipulate Tcl result string
  35. .SH SYNOPSIS
  36. .nf
  37. \fB#include <tcl.h>\fR
  38. .sp
  39. \fBTcl_SetResult\fR(\fIinterp, string, freeProc\fR)
  40. .sp
  41. \fBTcl_AppendResult(\fIinterp, string, string, ... , \fB(char *) NULL\fR)
  42. .sp
  43. .VS
  44. \fBTcl_AppendElement\fR(\fIinterp, string\fR)
  45. .VE
  46. .sp
  47. \fBTcl_ResetResult\fR(\fIinterp\fR)
  48. .sp
  49. \fBTcl_FreeResult\fR(\fIinterp\fR)
  50. .SH ARGUMENTS
  51. .AS Tcl_FreeProc freeProc
  52. .AP Tcl_Interp *interp out
  53. Interpreter whose result is to be modified.
  54. .AP char *string in
  55. String value to become result for \fIinterp\fR or to be
  56. appended to existing result.
  57. .AP Tcl_FreeProc freeProc in
  58. Address of procedure to call to release storage at
  59. \fIstring\fR, or \fBTCL_STATIC\fR, \fBTCL_DYNAMIC\fR, or
  60. \fBTCL_VOLATILE\fR.
  61. .BE
  62.  
  63. .SH DESCRIPTION
  64. .PP
  65. The procedures described here are utilities for setting the
  66. result/error string in a Tcl interpreter.
  67. .PP
  68. \fBTcl_SetResult\fR
  69. arranges for \fIstring\fR to be the return string for the current Tcl
  70. command in \fIinterp\fR, replacing any existing result.
  71. If \fIfreeProc\fR is \fBTCL_STATIC\fR it means that \fIstring\fR
  72. refers to an area of static storage that is guaranteed not to be
  73. modified until at least the next call to \fBTcl_Eval\fR.
  74. If \fIfreeProc\fR
  75. is \fBTCL_DYNAMIC\fR it means that \fIstring\fR was allocated with a call
  76. to \fBmalloc()\fR and is now the property of the Tcl system.
  77. \fBTcl_SetResult\fR will arrange for the string's storage to be
  78. released by calling \fBfree()\fR when it is no longer needed.
  79. If \fIfreeProc\fR is \fBTCL_VOLATILE\fR it means that \fIstring\fR
  80. points to an area of memory that is likely to be overwritten when
  81. \fBTcl_SetResult\fR returns (e.g. it points to something in a stack frame).
  82. In this case \fBTcl_SetResult\fR will make a copy of the string in
  83. dynamically allocated storage and arrange for the copy to be the
  84. return string for the current Tcl command.
  85. .PP
  86. If \fIfreeProc\fR isn't one of the values \fBTCL_STATIC\fR,
  87. \fBTCL_DYNAMIC\fR, and \fBTCL_VOLATILE\fR, then it is the address
  88. of a procedure that Tcl should call to free the string.
  89. This allows applications to use non-standard storage allocators.
  90. When Tcl no longer needs the storage for the string, it will
  91. call \fIfreeProc\fR.  \fIFreeProc\fR should have arguments and
  92. result that match the type \fBTcl_FreeProc\fR:
  93. .nf
  94. .RS
  95.  
  96. typedef void Tcl_FreeProc(char *\fIblockPtr\fR);
  97.  
  98. .RE
  99. .fi
  100. When \fIfreeProc\fR is called, its \fIblockPtr\fR will be set to
  101. the value of \fIstring\fR passed to \fBTcl_SetResult\fR.
  102. .PP
  103. If \fIstring\fR is \fBNULL\fR, then \fIfreeProc\fR is ignored
  104. and \fBTcl_SetResult\fR
  105. re-initializes \fIinterp\fR's result to point to the pre-allocated result
  106. area, with an empty string in the result area.
  107. .PP
  108. If \fBTcl_SetResult\fR is called at a time when \fIinterp\fR holds a
  109. result, \fBTcl_SetResult\fR does whatever is necessary to dispose
  110. of the old result (see the \fBTcl_Interp\fR manual entry for details
  111. on this).
  112. .PP
  113. \fBTcl_AppendResult\fR makes it easy to build up Tcl results in pieces.
  114. It takes each of its \fIstring\fR arguments and appends them in order
  115. to the current result associated with \fIinterp\fR.
  116. If the result is in its initialized empty state (e.g. a command procedure
  117. was just invoked or \fBTcl_ResetResult\fR was just called),
  118. then \fBTcl_AppendResult\fR sets the result to the concatenation of
  119. its \fIstring\fR arguments.
  120. \fBTcl_AppendResult\fR may be called repeatedly as additional pieces
  121. of the result are produced.
  122. \fBTcl_AppendResult\fR takes care of all the
  123. storage management issues associated with managing \fIinterp\fR's
  124. result, such as allocating a larger result area if necessary.
  125. Any number of \fIstring\fR arguments may be passed in a single
  126. call;  the last argument in the list must be a NULL pointer.
  127. .PP
  128. \fBTcl_AppendElement\fR is similar to \fBTcl_AppendResult\fR in
  129. that it allows results to be built up in pieces.
  130. However, \fBTcl_AppendElement\fR takes only a single \fIstring\fR
  131. argument and it appends that argument to the current result
  132. as a proper Tcl list element.
  133. \fBTcl_AppendElement\fR adds backslashes or braces if necessary
  134. to ensure that \fIinterp\fR's result can be parsed as a list and that
  135. \fIstring\fR will be extracted as a single element.
  136. Under normal conditions, \fBTcl_AppendElement\fR will add a space
  137. character to \fIinterp\fR's result just before adding the new
  138. list element, so that the list elements in the result are properly
  139. separated.
  140. .VS
  141. However if the new list element is the first in a list or sub-list
  142. (i.e. \fIinterp\fR's current result is empty, or consists of the
  143. single character ``{'', or ends in the characters `` {'') then no
  144. space is added.
  145. .VE
  146. .PP
  147. \fBTcl_ResetResult\fR clears the result for \fIinterp\fR,
  148. freeing the memory associated with it if the current result was
  149. dynamically allocated.
  150. It leaves the result in its normal initialized state with
  151. \fIinterp->result\fR pointing to a static buffer containing
  152. \fBTCL_RESULT_SIZE\fR characters, of which the first character
  153. is zero.
  154. \fBTcl_ResetResult\fR also clears the error state managed by
  155. \fBTcl_AddErrorInfo\fR and \fBTcl_SetErrorCode\fR.
  156. .PP
  157. \fBTcl_FreeResult\fR is a macro that performs part of the work
  158. of \fBTcl_ResetResult\fR.
  159. It frees up the memory associated with \fIinterp\fR's result
  160. and sets \fIinterp->freeProc\fR to zero, but it doesn't
  161. change \fIinterp->result\fR or clear error state.
  162. \fBTcl_FreeResult\fR is most commonly used when a procedure
  163. is about to replace one result value with another.
  164.  
  165. .SH "SEE ALSO"
  166. Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_Interp
  167.  
  168. .SH KEYWORDS
  169. append, command, element, list, result, return value, interpreter
  170.