---
name: "tst"
section: "3"
platform: "linux"
package: "inn2-dev"
version: "2.6.4-2"
release: "Debian 11 (Bullseye)"
platforms: ["linux"]
url: "https://new.carta.tech/tst"
---

# tst(3)

ternary search trie functions

## NAME

tst - ternary search trie functions

## SYNOPSIS

```
    #include <inn/tst.h>
    struct tst;
    struct tst *tst_init(int node_line_width);
    void tst_cleanup(struct tst *tst);
    int tst_insert(struct tst *tst, const unsigned char *key, void *data, int option, void **exist_ptr);
    void *tst_search(struct tst *tst, const unsigned char *key);
    void *tst_delete(struct tst *tst, const unsigned char *key);
```

## DESCRIPTION

**tst\_init** allocates memory for members of *struct tst*, and allocates the first *node\_line\_width* nodes. A NULL pointer is returned by **tst\_init** if any part of the memory allocation fails. On success, a pointer to a *struct tst* is returned.

The value for *node\_line\_width* must be chosen very carefully. One node is required for every character in the tree. If you choose a value that is too small, your application will spend too much time calling [**malloc**(3)](/malloc/3.md) and your node space will be too spread out. Too large a value is just a waste of space.

**tst\_cleanup** frees all memory allocated to nodes, internal structures, as well as *tst* itself.

**tst\_insert** inserts the string *key* into the tree. Behavior when a duplicate key is inserted is controlled by *option*. If *key* is already in the tree then **TST\_DUPLICATE\_KEY** is returned, and the data pointer for the existing key is placed in *exist\_ptr*.  If *option* is set to **TST\_REPLACE** then the existing data pointer for the existing key is replaced by *data*.  Note that the old data pointer will still be placed in *exist\_ptr*.

If a duplicate key is encountered and *option* is not set to **TST\_REPLACE** then **TST\_DUPLICATE\_KEY** is returned. If *key* is zero length then **TST\_NULL\_KEY** is returned. A successful insert or replace returns **TST\_OK**. A return value of **TST\_ERROR** indicates that a memory allocation error occurred while trying to grow the node free.

Note that the *data* argument must never be **NULL**. If it is, then calls to **tst\_search** will fail for a key that exists because the data value was set to **NULL**, which is what **tst\_search** returns. If you just want a simple existence tree, use the **tst** pointer as the data pointer.

**tst\_search** finds the string *key* in the tree if it exists and returns the data pointer associated with that key.

If *key* is not found then **NULL** is returned, otherwise the data pointer associated with *key* is returned.

**tst\_delete** deletes the string *key* from the tree if it exists and returns the data pointer assocaited with that key.

If *key* is not found then **NULL** is returned, otherwise the data pointer associated with *key* is returned.

## HISTORY

Converted to POD from Peter A. Friend's ternary search trie documentation by Alex Kiernan \<alex.kiernan@thus.net\> for InterNetNews 2.4.0.

`$Id:` tst.pod 9073 2010-05-31 19:00:23Z iulius $