Source
/* ========================================================================== */
// SPDX-License-Identifier: GPL-2.0-or-later
/*
* lib/textsearch.c Generic text search interface
*
* Authors: Thomas Graf <tgraf@suug.ch>
* Pablo Neira Ayuso <pablo@netfilter.org>
*
* ==========================================================================
*/
​
/**
* DOC: ts_intro
* INTRODUCTION
*
* The textsearch infrastructure provides text searching facilities for
* both linear and non-linear data. Individual search algorithms are
* implemented in modules and chosen by the user.
*
* ARCHITECTURE
*
* .. code-block:: none
*
* 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 in 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. But it might slow down
* performance of algorithm, so you should use it at own your risk.
* The returned configuration may then be used for an arbitrary
* amount of times and even in parallel as long as a separate struct