Tcl_CreateInterp, Tcl_DeleteInterp, Tcl_InterpDeleted − create and delete Tcl command interpreters


#include <tcl.h>

Tcl_Interp *




Tcl_Interp *interp (in)

Token for interpreter to be destroyed.



Tcl_CreateInterp creates a new interpreter structure and returns a token for it. The token is required in calls to most other Tcl procedures, such as Tcl_CreateCommand, Tcl_Eval, and Tcl_DeleteInterp. Clients are only allowed to access a few of the fields of Tcl_Interp structures; see the Tcl_Interp and Tcl_CreateCommand man pages for details. The new interpreter is initialized with the built-in Tcl commands and with the variables documented in tclvars(n). To bind in additional commands, call Tcl_CreateCommand.

Tcl_DeleteInterp marks an interpreter as deleted; the interpreter will eventually be deleted when all calls to Tcl_Preserve for it have been matched by calls to Tcl_Release. At that time, all of the resources associated with it, including variables, procedures, and application-specific command bindings, will be deleted. After Tcl_DeleteInterp returns any attempt to use Tcl_Eval on the interpreter will fail and return TCL_ERROR. After the call to Tcl_DeleteInterp it is safe to examine the interpreter’s result, query or set the values of variables, define, undefine or retrieve procedures, and examine the runtime evaluation stack. See below, in the section INTERPRETERS AND MEMORY MANAGEMENT for details.

Tcl_InterpDeleted returns nonzero if Tcl_DeleteInterp was called with interp as its argument; this indicates that the interpreter will eventually be deleted, when the last call to Tcl_Preserve for it is matched by a call to Tcl_Release. If nonzero is returned, further calls to Tcl_Eval in this interpreter will return TCL_ERROR.

Tcl_InterpDeleted is useful in deletion callbacks to distinguish between when only the memory the callback is responsible for is being deleted and when the whole interpreter is being deleted. In the former case the callback may recreate the data being deleted, but this would lead to an infinite loop if the interpreter were being deleted.


Tcl_DeleteInterp can be called at any time on an interpreter that may be used by nested evaluations and C code in various extensions. Tcl implements a simple mechanism that allows callers to use interpreters without worrying about the interpreter being deleted in a nested call, and without requiring special code to protect the interpreter, in most cases. This mechanism ensures that nested uses of an interpreter can safely continue using it even after Tcl_DeleteInterp is called.

The mechanism relies on matching up calls to Tcl_Preserve with calls to Tcl_Release. If Tcl_DeleteInterp has been called, only when the last call to Tcl_Preserve is matched by a call to Tcl_Release, will the interpreter be freed. See the manual entry for Tcl_Preserve for a description of these functions.

The rules for when the user of an interpreter must call Tcl_Preserve and Tcl_Release are simple:
Interpreters Passed As Arguments

Functions that are passed an interpreter as an argument can safely use the interpreter without any special protection. Thus, when you write an extension consisting of new Tcl commands, no special code is needed to protect interpreters received as arguments. This covers the majority of all uses.

Interpreter Creation And Deletion

When a new interpreter is created and used in a call to Tcl_Eval, Tcl_VarEval, Tcl_GlobalEval, Tcl_SetVar, or Tcl_GetVar, a pair of calls to Tcl_Preserve and Tcl_Release should be wrapped around all uses of the interpreter. Remember that it is unsafe to use the interpreter once Tcl_Release has been called. To ensure that the interpreter is properly deleted when it is no longer needed, call Tcl_InterpDeleted to test if some other code already called Tcl_DeleteInterp; if not, call Tcl_DeleteInterp before calling Tcl_Release in your own code.

Retrieving An Interpreter From A Data Structure

When an interpreter is retrieved from a data structure (e.g. the client data of a callback) for use in Tcl_Eval, Tcl_VarEval, Tcl_GlobalEval, Tcl_SetVar, or Tcl_GetVar, a pair of calls to Tcl_Preserve and Tcl_Release should be wrapped around all uses of the interpreter; it is unsafe to reuse the interpreter once Tcl_Release has been called. If an interpreter is stored inside a callback data structure, an appropriate deletion cleanup mechanism should be set up by the code that creates the data structure so that the interpreter is removed from the data structure (e.g. by setting the field to NULL) when the interpreter is deleted. Otherwise, you may be using an interpreter that has been freed and whose memory may already have been reused.

All uses of interpreters in Tcl and Tk have already been protected. Extension writers should ensure that their code also properly protects any additional interpreters used, as described above.


Tcl_Preserve(3), Tcl_Release(3)


command, create, delete, interpreter

More Linux Commands

fstrim(8) - discard unused blocks on a mounted filesystem...
fstrim is used on a mounted filesystem to discard (or trim) blocks which are not in use by the filesystem. This is useful for solid-state drives (SSDs) and thin

refchan(n) - Command handler API of reflected channels, vers
The Tcl-level handler for a reflected channel has to be a command with subcommands (termed an ensemble, as it is a command such as that created by namespace ens

xdr_u_long(3) - library routines for external data represent
These routines allow C programmers to describe arbitrary data structures in a machine-independent fashion. Data for remote procedure calls are transmitted using

erand48_r(3) - generate uniformly distributed pseudo-random
These functions are the reentrant analogs of the functions described in drand48(3). Instead of modifying the global random generator state, they use the supplie

armscii-8(7) - Armenian character set encoded in octal, deci
The Armenian Standard Code for Information Interchange, 8-bit coded character set. ArmSCII-8 characters The following table displays the characters in ArmSCII-8

glRasterPos4d(3gl) - specify the raster position for pixel o
The GL maintains a 3D position in window coordinates. This position, called the raster position, is used to position pixel and bitmap write operations. It is ma

lrange(n) - Return one or more adjacent elements from a list
List must be a valid Tcl list. This command will return a new list consisting of elements first through last, inclusive. The index values first and last are int

gnutls_certificate_set_openpgp_key_file(3) - API function...
This funtion is used to load OpenPGP keys into the GnuTLS credentials structure. The file should contain at least one valid non encrypted subkey. RETURNS On suc

File::stat(3pm) - by-name interface to Perl's built-in stat(
This modules default exports override the core stat() and lstat() functions, replacing them with versions that return File::stat objects. This object has method

icecream(7) - A distributed compile system - Linux man page
Icecream is a distributed compile system for C and C++. Icecream is created by SUSE and is based on ideas and code by distcc. Like distcc it takes compile jobs

dracut.modules(7) dracut modules (Misc - Linux man page)....
dracut uses a modular system to build and extend the initramfs image. All modules are located in /usr/lib/dracut/modules.d or in &lt;git-src&gt;/modules.d. The most b

setutxent(3) - access utmp file entries - Linux manual page
New applications should use the POSIX.1-specified utmpx versions of these functions; see CONFORMING TO. utmpname() sets the name of the utmp-format file for the

We can't live, work or learn in freedom unless the software we use is free.