Tcl - Tcl_SetObjResult (3)

Tcl Library Procedures

NAME

Tcl_SetObjResult, Tcl_GetObjResult, Tcl_ResetObjResult - manipulate Tcl result string

SYNOPSIS

#include <tcl.h>

Tcl_SetObjResult(interp, objPtr)

Tcl_GetObjResult(interp)

Tcl_ResetObjResult(interp)

ARGUMENTS

Tcl_Interp *interp (out): Interpreter whose object result is to be modified.
Tcl_Obj *objPtr (in): The object value to become the object result for interp.

DESCRIPTION

The procedures described here are utilities for setting the result/error object in a Tcl interpreter.

Tcl_SetObjResult arranges for objPtr to be the return object for the current Tcl command in interp, replacing any existing result object. If objPtr is NULL, interp->objResult is set to a new Tcl object containing an empty string. Otherwise, interp->objResult 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 interp->objResult value is decremented and the old object result is freed if no references to it remain. This result object can be retrieved using Tcl_GetObjResult.

A Tcl interpreter structure now contains two separate result members: the interp->objResult object result and the old interp->result string result. Extension writers need to observe two simple rules to return a result from a command procedure. Object-based Tcl command procedures (i.e., those registered using Tcl_CreateObjCommand) must use Tcl_SetObjResult to return an object result. They should not set the interp->result string result. On the other hand, string-based Tcl command procedures (those registered using Tcl_CreateCommand) must continue to set the interp->result string result.

Tcl_GetObjResult returns the Tcl object result value for interp. The object's reference count is not incremented; if the caller needs to retain a pointer to object they should use Tcl_IncrRefCount to increment its reference count in order to keep it from being freed too early or accidently changed.

Tcl_ResetObjResult clears the object result for interp. It sets interp->objResult to an object containing an empty string after decrementing the reference count for any old result object. Tcl_ResetObjResult also clears the error state managed by Tcl_AddObjErrorInfo and Tcl_AddErrorInfo and Tcl_SetErrorCode.

KEYWORDS

append, command, object, result, return value

Last change: 8.0