---
name: "libinn_tst"
section: "3"
platform: "linux"
package: "inn"
version: "2.7.4-4"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/libinn_tst"
---

# libinn\_tst(3)

Ternary search trie functions

## NAME

tst - Ternary search trie functions

## SYNOPSIS

```
    #include <inn/tst.h>
    enum tst_constants {
        TST_OK,
        TST_NULL_KEY,
        TST_NULL_DATA,
        TST_DUPLICATE_KEY,
        TST_REPLACE
    };
    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 associated 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.

## SEE ALSO

[libinn(3)](/libinn/3.md).