ts_intro(9)

💖 INTRODUCTION 💖

okay bestie, welcome to ts_intro(9) — yes, from the Kernel API Manual — and it's literally the intro to the textsearch infrastructure. The textsearch infrastructure is the whole text-searching setup for linear and non-linear data alike. Each individual search algorithm lives in its own module, and you get to choose which one the user runs. slay. ✨

🦋 ARCHITECTURE 🦋

Here's the iconic architecture diagram, no cap — read it like a group chat of who calls whom:

           User
           +----------------+
           |        finish|<--------------(6)-----------------+
           |get_next_block|<--------------(5)---------------+ |
           |                |                     Algorithm   | |
           |                |                    +------------------------------+
           |                |                    |  init   find   destroy |
           |                |                    +------------------------------+
           |                |       Core API           ^       ^          ^
           |                |      +---------------+  (2)     (4)        (8)
           |             (1)|----->| prepare     |---+       |          |
           |             (3)|----->| find/next |-----------+          |
           |             (7)|----->| destroy     |----------------------+
           +----------------+      +---------------+

• (1) User configures a search by calling textsearch_prepare, specifying the search parameters such as the pattern and algorithm name.
• (2) Core requests the algorithm to allocate and initialize a search configuration according to the specified parameters.
• (3) User starts the search(es) by calling textsearch_find or textsearch_next to fetch subsequent occurrences. A state variable is provided to the algorithm to store persistent variables.
• (4) Core eventually resets the search offset and forwards the find request to the algorithm.
• (5) Algorithm calls get_next_block, provided by the user, continuously to fetch the data to be searched block by block.
• (6) Algorithm invokes finish after the last call to get_next_block to clean up any leftovers from get_next_block. (Optional)
• (7) User destroys the configuration by calling textsearch_destroy.
• (8) Core notifies the algorithm to destroy algorithm specific allocations. (Optional)

🌸 USAGE 🌸

Before a search can be performed, a configuration must be created by calling textsearch_prepare specifying the searching algorithm, the pattern to look for and flags. As a flag, you can set TS_IGNORECASE to perform case insensitive matching.

heads up bestie: it might slow down performance of the algorithm, so you should use it at your own risk. 🫶

The returned configuration may then be used for an arbitrary amount of times and even in parallel as long as a separate struct ts_state variable is provided to every instance.

The actual search is performed by either calling textsearch_find_continuous for linear data or by providing an own get_next_block implementation and calling textsearch_find. Both functions return the position of the first occurrence of the pattern or UINT_MAX if no match was found. Subsequent occurrences can be found by calling textsearch_next regardless of the linearity of the data.

Once you're done using a configuration it must be given back via textsearch_destroy.

🐣 EXAMPLE: 🐣

okay, here's the example — and yes, it's iconic:

int pos;
struct ts_config *conf;
struct ts_state state;
const char *pattern = "chicken";
const char *example = "We dance the funky chicken";

conf = textsearch_prepare("kmp", pattern, strlen(pattern),
                          GFP_KERNEL, TS_AUTOLOAD);
if (IS_ERR(conf)) {
    err = PTR_ERR(conf);
    goto errout;
}

pos = textsearch_find_continuous(conf, state, example, strlen(example));
if (pos != UINT_MAX)
    panic("Oh my god, dancing chickens at d0, pos);

textsearch_destroy(conf);

👀 SEE ALSO 👀

Kernel file ./lib/textsearch.c — also go peek at textsearch_register(9), textsearch_unregister(9), textsearch_find_continuous(9), textsearch_prepare(9), and textsearch_destroy(9). iykyk 💅

mwah 💋 — this page came from ./lib, dated October 2026, and it's literally ts_intro(9) from the Kernel API Manual. periodt. 🎀