---
name: "Keylist"
section: "3tclx"
platform: "linux"
package: "tclx8.4-doc"
version: "8.4.1-5"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Keylist/3tclx"
---

# Keylist(3tclx)

Keyed list management routines.

## NAME

TclX\_NewKeyedListObj, TclX\_KeyedListGet, TclX\_KeyedListSet, TclX\_KeyedListDelete, TclX\_KeyedListGetKeys - Keyed list management routines.

## SYNOPSIS

```
#include <tclExtend.h>
Tcl_Obj *
TclX_NewKeyedListObj (void);
int
TclX_KeyedListGet (Tcl_Interp *interp,
                   Tcl_Obj    *keylPtr,
                   char       *key,
                   Tcl_Obj   **valuePtrPtr);
int
TclX_KeyedListSet (Tcl_Interp *interp,
                   Tcl_Obj    *keylPtr,
                   char       *key,
                   Tcl_Obj    *valuePtr);
int
TclX_KeyedListDelete (Tcl_Interp *interp,
                      Tcl_Obj    *keylPtr,
                      char       *key);
int
TclX_KeyedListGetKeys (Tcl_Interp *interp,
                       Tcl_Obj    *keylPtr,
                       char       *key,
                       Tcl_Obj   **listObjPtrPtr);
```

## DESCRIPTION

These routines perform operations on keyed lists.  See the *Extended Tcl*  man page for a description of keyed lists.

### TclX\_NewKeyedListObj

Create and initialize a new keyed list object.

Returns:

A pointer to the object.

### TclX\_KeyedListGet

  Retrieve a key value from a keyed list.

Parameters:

**o** *interp* - Error message will be return in result if there is an error.\
 **o** *keylPtr* - Keyed list object to get key from.\
 **o** *key* - The name of the key to extract.  Will recusively process sub-keys separated by \`.'.\
 **o** *valueObjPtrPtr* - If the key is found, a pointer to the key object\
     is returned here.  NULL is returned if the key is not present.\

Returns:

**o TCL\_OK** - If the key value was returned.\
 **o TCL\_BREAK** - If the key was not found.\
 **o TCL\_ERROR** - If an error occurred.\

### TclX\_KeyedListSet

  Set a key value in keyed list object.

Parameters:

**o** *interp* - Error message will be return in result object.\
 **o** *keylPtr* - Keyed list object to update.\
 **o** *key* - The name of the key to extract.  Will recusively process sub-key separated by \`.'.\
 **o** *valueObjPtr* - The value to set for the key.\

Returns:

  TCL\_OK or TCL\_ERROR.

### TclX\_KeyedListDelete

  Delete a key value from keyed list.

Parameters:

**o** *interp* - Error message will be return in result if there is an error.\
 **o** *keylPtr* - Keyed list object to update.\
 **o** *key* - The name of the key to extract.  Will recusively process sub-key separated by \`.'.\

Returns:

**o TCL\_OK** - If the key was deleted.\
 **o TCL\_BREAK** - If the key was not found.\
 **o TCL\_ERROR** - If an error occurred.\

### TclX\_KeyedListGetKeys

  Retrieve a list of keyed list keys.

Parameters:

**o** *interp* - Error message will be return in result if there is an error.\
 **o** *keylPtr* - Keyed list object to get key from.\
 **o** *key* - The name of the key to get the sub keys for.  NULL or empty to retrieve all top level keys.\
 **o** *listObjPtrPtr* - List object is returned here with key as values.

Returns:

**o TCL\_OK** - If the zero or more key where returned.\
 **o TCL\_BREAK** - If the key was not found.\
 **o TCL\_ERROR** - If an error occurred.\