Tcl_NewDictObj, Tcl_DictObjPut, Tcl_DictObjGet, Tcl_DictObjRemove, Tcl_DictObjSize, Tcl_DictObjFirst, Tcl_DictObjNext, Tcl_DictObjDone, Tcl_DictObjPutKeyList, Tcl_DictObjRemoveKeyList − manipulate Tcl objects as dictionaries


#include <tcl.h>

Tcl_Obj *

(interp, dictPtr, keyPtr, valuePtrPtr)

(interp, dictPtr, keyPtr, valuePtr)

(interp, dictPtr, keyPtr)

(interp, dictPtr, sizePtr)

(interp, dictPtr, searchPtr,
keyPtrPtr, valuePtrPtr, donePtr

(searchPtr, keyPtrPtr, valuePtrPtr, donePtr)


(interp, dictPtr, keyc, keyv, valuePtr)

(interp, dictPtr, keyc, keyv)


Tcl_Interp *interp (in)

If an error occurs while converting an object to be a dictionary object, an error message is left in the interpreter’s result object unless interp is NULL.

Tcl_Obj *dictPtr (in/out)

Points to the dictionary object to be manipulated. If dictPtr does not already point to a dictionary object, an attempt will be made to convert it to one.

Tcl_Obj *keyPtr (in)

Points to the key for the key/value pair being manipulated within the dictionary object.

Tcl_Obj **keyPtrPtr (out)

Points to a variable that will have the key from a key/value pair placed within it. May be NULL to indicate that the caller is not interested in the key.

Tcl_Obj *valuePtr (in)

Points to the value for the key/value pair being manipulate within the dictionary object (or sub-object, in the case of Tcl_DictObjPutKeyList.)

Tcl_Obj **valuePtrPtr (out)

Points to a variable that will have the value from a key/value pair placed within it. For Tcl_DictObjFirst and Tcl_DictObjNext, this may be NULL to indicate that the caller is not interested in the value.

int *sizePtr (out)

Points to a variable that will have the number of key/value pairs contained within the dictionary placed within it.

Tcl_DictSearch *searchPtr (in/out)

Pointer to record to use to keep track of progress in enumerating all key/value pairs in a dictionary. The contents of the record will be initialized by the call to Tcl_DictObjFirst. If the enumerating is to be terminated before all values in the dictionary have been returned, the search record must be passed to Tcl_DictObjDone to enable the internal locks to be released.

int *donePtr (out)

Points to a variable that will have a non-zero value written into it when the enumeration of the key/value pairs in a dictionary has completed, and a zero otherwise.

int keyc (in)

Indicates the number of keys that will be supplied in the keyv array.

Tcl_Obj *const *keyv (in)

Array of keyc pointers to objects that Tcl_DictObjPutKeyList and Tcl_DictObjRemoveKeyList will use to locate the key/value pair to manipulate within the sub-dictionaries of the main dictionary object passed to them.



Tcl dictionary objects have an internal representation that supports efficient mapping from keys to values and which guarantees that the particular ordering of keys within the dictionary remains the same modulo any keys being deleted (which removes them from the order) or added (which adds them to the end of the order). If reinterpreted as a list, the values at the even-valued indices in the list will be the keys of the dictionary, and each will be followed (in the odd-valued index) by the value associated with that key.

The procedures described in this man page are used to create, modify, index, and iterate over dictionary objects from C code.

Tcl_NewDictObj creates a new, empty dictionary object. The string representation of the object will be invalid, and the reference count of the object will be zero.

Tcl_DictObjGet looks up the given key within the given dictionary and writes a pointer to the value associated with that key into the variable pointed to by valuePtrPtr, or a NULL if the key has no mapping within the dictionary. The result of this procedure is TCL_OK, or TCL_ERROR if the dictPtr cannot be converted to a dictionary.

Tcl_DictObjPut updates the given dictionary so that the given key maps to the given value; any key may exist at most once in any particular dictionary. The dictionary must not be shared, but the key and value may be. This procedure may increase the reference count of both key and value if it proves necessary to store them. Neither key nor value should be NULL. The result of this procedure is TCL_OK, or TCL_ERROR if the dictPtr cannot be converted to a dictionary.

Tcl_DictObjRemove updates the given dictionary so that the given key has no mapping to any value. The dictionary must not be shared, but the key may be. The key actually stored in the dictionary will have its reference count decremented if it was present. It is not an error if the key did not previously exist. The result of this procedure is TCL_OK, or TCL_ERROR if the dictPtr cannot be converted to a dictionary.

Tcl_DictObjSize updates the given variable with the number of key/value pairs currently in the given dictionary. The result of this procedure is TCL_OK, or TCL_ERROR if the dictPtr cannot be converted to a dictionary.

Tcl_DictObjFirst commences an iteration across all the key/value pairs in the given dictionary, placing the key and value in the variables pointed to by the keyPtrPtr and valuePtrPtr arguments (which may be NULL to indicate that the caller is uninterested in they key or variable respectively.) The next key/value pair in the dictionary may be retrieved with Tcl_DictObjNext. Concurrent updates of the dictionary’s internal representation will not modify the iteration processing unless the dictionary is unshared, when this will trigger premature termination of the iteration instead (which Tcl scripts cannot trigger via the dict command.) The searchPtr argument points to a piece of context that is used to identify which particular iteration is being performed, and is initialized by the call to Tcl_DictObjFirst. The donePtr argument points to a variable that is updated to be zero of there are further key/value pairs to be iterated over, or non-zero if the iteration is complete. The order of iteration is implementation-defined. If the dictPtr argument cannot be converted to a dictionary, Tcl_DictObjFirst returns TCL_ERROR and the iteration is not commenced, and otherwise it returns TCL_OK.

When Tcl_DictObjFirst is called upon a dictionary, a lock is placed on the dictionary to enable that dictionary to be iterated over safely without regard for whether the dictionary is modified during the iteration. Because of this, once the iteration over a dictionary’s keys has finished (whether because all values have been iterated over as indicated by the variable indicated by the donePtr argument being set to one, or because no further values are required) the Tcl_DictObjDone function must be called with the same searchPtr as was passed to Tcl_DictObjFirst so that the internal locks can be released. Once a particular searchPtr is passed to Tcl_DictObjDone, passing it to Tcl_DictObjNext (without first initializing it with Tcl_DictObjFirst) will result in no values being produced and the variable pointed to by donePtr being set to one. It is safe to call Tcl_DictObjDone multiple times on the same searchPtr for each call to Tcl_DictObjFirst.

The procedures Tcl_DictObjPutKeyList and Tcl_DictObjRemoveKeyList are the close analogues of Tcl_DictObjPut and Tcl_DictObjRemove respectively, except that instead of working with a single dictionary, they are designed to operate on a nested tree of dictionaries, with inner dictionaries stored as values inside outer dictionaries. The keyc and keyv arguments specify a list of keys (with outermost keys first) that acts as a path to the key/value pair to be affected. Note that there is no corresponding operation for reading a value for a path as this is easy to construct from repeated use of Tcl_DictObjGet. With Tcl_DictObjPutKeyList, nested dictionaries are created for non-terminal keys where they do not already exist. With Tcl_DictObjRemoveKeyList, all non-terminal keys must exist and have dictionaries as their values.


Using the dictionary iteration interface to search determine if there is a key that maps to itself:

Tcl_DictSearch search;
Tcl_Obj *key, *value;
int done;

* Assume interp and objPtr are parameters. This is the
* idiomatic way to start an iteration over the dictionary; it
* sets a lock on the internal representation that ensures that
* there are no concurrent modification issues when normal
* reference count management is also used. The lock is
* released automatically when the loop is finished, but must
* be released manually when an exceptional exit from the loop
* is performed. However it is safe to try to release the lock
* even if we’ve finished iterating over the loop.
if (Tcl_DictObjFirst(interp, objPtr, &search,
&key, &value, &done) != TCL_OK) {
return TCL_ERROR;
for (; !done ; Tcl_DictObjNext(&search, &key, &value, &done)) {
* Note that strcmp() is not a good way of comparing
* objects and is just used here for demonstration
* purposes.
if (!strcmp(Tcl_GetString(key), Tcl_GetString(value))) {
Tcl_SetObjResult(interp, Tcl_NewBooleanObj(!done));
return TCL_OK;


Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_InitObjHashTable


dict, dict object, dictionary, dictionary object, hash table, iteration, object

More Linux Commands

Tcl_UpVar2(3) - link one variable to another (Man Page).....
Tcl_UpVar and Tcl_UpVar2 provide the same functionality as the upvar command: they make a link from a source variable to a destination variable, so that referen

isblank(3) - character classification routines (Man Page)...
These functions check whether c, which must have the value of an unsigned char or EOF, falls into a certain character class according to the specified locale. T

git-name-rev(1) - Find symbolic names for given revs........
Finds symbolic names suitable for human digestion for revisions given in any format parsable by git rev-parse. OPTIONS --tags Do not use branch names, but only

remquof(3) - remainder and part of quotient - Linux man page
These functions compute the remainder and part of the quotient upon division of x by y. A few bits of the quotient are stored via the quo pointer. The remainder

timegm(3) - inverses of gmtime and localtime (Man Page).....
The functions timelocal() and timegm() are the inverses of localtime(3) and gmtime(3). CONFORMING TO These functions are nonstandard GNU extensions that are als

XErrorEvent(3) - X error event structure - Linux man page...
The XErrorEvent structure contains: typedef struct { int type; Display *display; /* Display the event was read from */ unsigned long serial;/* serial number of

zshzle(1) - zsh command line editor - Linux manual page.....
If the ZLE option is set (which it is by default in interactive shells) and the shell input is attached to the terminal, the user is able to edit command lines.

gdbtui(1) - The GNU Debugger (Commands - Linux man page)....
The purpose of a debugger such as GDB is to allow you to see what is going on inside another program while it executes-or what another program was doing at the

set_form_userptr(3form) - associate application data with a
set_form_userptr.3form - Every form and every form item has a field that can be used to hold application-specific data (that is, the form-driver code leaves it

pthread_attr_getdetachstate(3) - set/get detach state attrib
The pthread_attr_setdetachstate() function sets the detach state attribute of the thread attributes object referred to by attr to the value specified in detachs

XrmPutStringResource(3) - store database resources (ManPage)
If database contains NULL, XrmPutResource creates a new database and returns a pointer to it. XrmPutResource is a convenience function that calls XrmStringToBin

XkbUpdateMapFromCore(3) - Update a local Xkb keyboard map to
Xkb provides several functions that make it easier to apply the compatibility map to configure a client-side Xkb keyboard mapping, given a core protocol represe

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