BMGSUBS(3L)

NAME
(bmgsubs) bmg_setup, bmg_search, bmg_fsearch - Boyer-Moore-Gosper string search routines

SYNOPSIS
bmg_setup(search_string, case_fold_flag)
char *search_string;
int case_fold_flag;

bmg_fsearch(file_des, action_func)
int file_des;
int (*action_func)();

bmg_search(buffer_base, buffer_length, action_func)
char *buffer_base;
int buffer_length;
int (*action_func)();

DESCRIPTION
These routines perform fast searches for strings, using the Boyer-Moore-Gosper algorithm. No meta-characters (such as `*' or `.') are interpreted, and the search string cannot contain newlines.

Bmg_setup must be called as the first step in performing a search. The search_string parameter is the string to be searched for. Case_fold_flag should be false (zero) if characters should match exactly, and true (non-zero) if case should be ignored when checking for matches.

Once a search string has been specified using bmg_setup, one or more searches for that string may be performed.

Bmg_fsearch searches a file, open for reading on file descriptor file_des (this is not a stdio file.) For each line that contains the search string, bmg_fsearch will call the action_func function specified by the caller as action_func(matching_line, byte_offset). The matching_line parameter is a (char *) pointer to a temporary copy of the line; byte_offset is the offset from the beginning of the file to the first occurence of the search string in that line. Action_func should return true (non-zero) if the search should continue, or false (zero) if the search should terminate at this point.

Bmg_search is like bmg_fsearch, except that instead of searching a file, it searches the buffer pointed to by buffer_base; buffer_length specifies the number of bytes in the buffer. The byte_offset parameter to action_func gives the offset from the beginning of the buffer.

If the user merely wants the matching lines printed on the standard output, the action_func parameter to bmg_fsearch or bmg_search can be NULL.

AUTHOR
Jeffrey Mogul (Stanford University), based on code written by James A. Woods (NASA Ames)

BUGS
Might be nice to have a version of this that handles regular expressions.

There are large, but finite, limits on the length of both pattern strings and text lines. When these limits are exceeded, all bets are off.

The string pointer passed to action_func points to a temporary copy of the matching line, and must be copied elsewhere before action_func returns.

Bmg_search does not permanently modify the buffer in any way, but during its execution (and therefore when action_func is called), the last byte of the buffer may be temporarily changed.

The Boyer-Moore algorithm cannot find lines that do not contain a given pattern (like "grep -v") or count lines ("grep -n"). Although it is fast even for short search strings, it gets faster as the search string length increases.