Tcl Library Procedures


Tcl_SetObjResult, Tcl_GetObjResult, Tcl_ResetObjResult - manipulate Tcl result string


#include <tcl.h>

Tcl_SetObjResult(interp, objPtr)




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.


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.


Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_Interp, Tcl_Obj


append, command, object, result, return value

Last change: 8.0

[ tcl8.0a1 | tk8.0a1 | X-ref ]

Copyright © 1989-1994 The Regents of the University of California.
Copyright © 1994-1996 Sun Microsystems, Inc.