---
name: "Tcl_GetKeyedListField"
section: "3tclx"
platform: "linux"
package: "tclx76-dev"
version: "7.6.0-3"
release: "Debian 2.1 (Slink)"
platforms: ["linux"]
url: "https://new.carta.tech/Tcl_GetKeyedListField"
---

# Tcl\_GetKeyedListField(3tclx)

Keyed list management routines.

## NAME

Tcl\_GetKeyedListKeys, Tcl\_GetKeyedListField, Tcl\_SetKeyedListField, Tcl\_DeleteKeyedListField - Keyed list management routines.

## SYNOPSIS

```
#include <tclExtend.h>
int
Tcl_GetKeyedListKeys (Tcl_Interp  *interp,
                      const char  *subFieldName,
                      const char  *keyedList,
                      int         *keysArgcPtr,
                      char      ***keysArgvPtr);
int
Tcl_GetKeyedListField (Tcl_Interp  *interp,
                       const char  *fieldName,
                       const char  *keyedList,
                       char       **fieldValuePtr);
char *
Tcl_SetKeyedListField (Tcl_Interp  *interp,
                       const char  *fieldName,
                       const char  *fieldvalue,
                       const char  *keyedList);
char *
Tcl_DeleteKeyedListField (Tcl_Interp  *interp,
                          const char  *fieldName,
                          const char  *keyedList);
```

## DESCRIPTION

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

### Tcl\_GetKeyedListKeys

Retrieve a list of keys from a keyed list.  The list is walked rather than converted to a argv for increased performance.

Parameters:

**o** *interp* - Error message will be return in result if there is an error.\
 **o subFieldName** - If "" or NULL, then the keys are retrieved for the top level of the list.  If specified, it is name of the field who's subfield keys are to be retrieve.\
 **o** *keyedList* - The list to search for the field.\
 **o** *keysArgcPtr* - The number of keys in the keyed list is returned here.\
 **o** *keysArgvPtr* - An argv containing the key names.  It is dynamically allocated, containing both the array and the strings. A single call to ckfree will release it.

Returns:

TCL\_OK if a list of keys is returned, TCL\_BREAK if the field was not found, or TCL\_ERROR if an error occurred.

### Tcl\_GetKeyedListField

Retrieve a field value from a keyed list.  The list is walked rather than converted to a argv for increased performance.  This if the name contains sub-fields, this function recursive.

Parameters:

**o** *interp* - Error message will be return in result if there is an error.\
 **o** *fieldName* - The name of the field to extract.  Will recursively process sub-field names separated by \`.'.\
 **o** *keyedList* - The list to search for the field.\
 **o** *fieldValuePtr* - If the field is found, a pointer to a dynamicly allocated string containing the value is returned here.  If NULL is specified, then only the presence of the field is validated, the value is not returned.

Returns:

TCL\_OK if the field was found,  TCL\_BREAK if the field was not found or TCL\_ERROR if an error occurred.

### Tcl\_SetKeyedListField

Set a field value in keyed list.

Parameters:

**o** *interp* - Error message will be return in result if there is an error.\
 **o** *fieldName* - The name of the field to extract.  Will recusively process sub-field names separated by \`.'.\
 **o** *fieldValue* - The value to set for the field.\
 **o** *keyedList* - The keyed list to set a field value in, may be an NULL or an empty list to create a new keyed list.

Returns:

A pointer to a dynamically allocated string, or NULL if an error occurred.

### Tcl\_DeleteKeyedListField

Delete a field value in keyed list.

Parameters:

**o** *interp* - Error message will be return in result if there is an error.\
 **o** *fieldName* - The name of the field to extract.  Will recursively process sub-field names separated by \`.'.\
 **o** *fieldValue* - The value to set for the field.\
 **o** *keyedList* - The keyed list to delete the field from.

Returns:

A pointer to a dynamically allocated string containing the new list, or NULL if an error occurred.