NAME
Tcl_Return - set up a Tcl result string

SYNOPSIS
#include <tcl.h>

Tcl_Return(interp, string, status)

ARGUMENTS
Interpreter for which a return value is to be established. String value to be returned, or NULL. Indicates the nature of string. Must be either TCL_STATIC, TCL_DYNAMIC, or TCL_VOLATILE.

DESCRIPTION

Tcl_Return is a convenience routine used by several of the Tcl commands. It arranges for string to be the return string for the current Tcl command in interp. If status is TCL_STATIC it means that string refers to an area of static storage that is guaranteed to remain untouched until at least the next call to Tcl_Eval. If status is TCL_DYNAMIC it means that string was allocated with a call to malloc() and is now the property of the Tcl system. Tcl_Return will arrange for the string's storage to be released by calling free() when it is no longer needed. The third possibility is for status to be TCL_VOLATILE. This means that string points to an area of memory that is likely to be overwritten when Tcl_Return returns. In this case Tcl_Return makes a copy of the string and arranges for the copy to be the return string for the current Tcl command.

If string is NULL, then status is ignored and Tcl_Return re-initializes interp's result to point to the pre-allocated result area, with an empty string in the result area.

In any of the above cases, if interp holds a dynamically-allocated result at the time of the Tcl_Return call, the old result's storage is released by calling free().

KEYWORDS
command, result, return value, interpreter