BSEARCH(1)

NAME

SYNOPSIS

DESCRIPTION

bsearch searches the sorted data file inputfile for a line or lines matching key. Binary search is used, performing random-access seeks within the file, not all of which therefore needs to be read. Binary searches, even on huge files, can be quite efficient.

By default, the search is for a line which contains key in its first (whitespace-separated) column. A few other variants on this basic search strategy are also supported, selected by option flags as described below.

The input data file must obviously be sorted, and moreover, bsearch must know how it was sorted. bsearch therefore accepts many of the same option flags as does sort(1), indicating whether the data file being searched was sorted numerically, or caselessly, or on a particular column. In general, bsearch should be given more or less the same option flags when searching as sort(1) was when generating the file being searched.

OPTIONS

+n

Search the n'th whitespace-separated column, where the leftmost column is column 0.

-a

Use alternate dictionary (``look'' only).

-br

If a line or lines matching the key cannot be found, ``bracket'' the position where it would have been found by printing the immediately preceding and following lines. The preceding line is prefixed with a `<' character and the following line is prefixed with `>'.

-D

Assume the data was sorted by date and time. (Experimental; not enabled in all versions of the program.)

-f

Fold upper/lower case (i.e. assume input sorted caselessly).

-k n

Search the n'th whitespace-separated column, where the leftmost column is column 1.

-m

Find and print multiple values, if the input happens to contain them; do not assume that the input contains at most one matching value.

-n

Input is sorted numerically.

-off

Precede each line with its lseek offset in the file. (For compatibility with the GNU version of grep(1), the option --byte-offset is also accepted.)

-p

Prefix match; match any line whose selected column merely begins with key. (Recommend using -m along with this option.)

-r

Input is sorted in reverse order.

-range

Range match; print all lines whose selected column lies between key1 and key2, inclusive. (When -range is used, two key arguments are accepted on the command line, with the filename therefore being the third argument.)

-s

Do not print; exit status only.

-tc

Tab character separating columns is c.

-version

Print program's version number.

-w

``Word'' match, that is, of key against entire selected column. (Default.)

-x

Exact match: match key against entire line.

-?,-h

Print a brief help message.

A few combinations of options make no sense and are disallowed. Only one of -p, -w, and -x should appear. Only one of -br, -m, and -range should appear. Option -x precludes use of -k or +n to select a search column. Option -p may not be used with -n.

If the program is invoked via a link named look, the -m and -p options are assumed, the -w option becomes useful to override the implicit -p, the file /usr/dict/words is assumed if the filename parameter is omitted, and the -a option selects the alternate default dictionary file /usr/dict/web2 instead.

EXIT STATUS

The exit status is zero if a match is found, 1 if no match is found (including when merely bracketing lines are printed using -br), and 2 for errors.

BUGS

The numeric search (-n) works on integers only, not floating-point.

Not all of sort(1)'s options are accepted.

The handling of column specifiers is incomplete, at least as far as compatibility with sort(1) is concerned. The m.n notation for selecting a character position within a field is not supported. Only one search column may be specified. (A field-end specifier is ignored.)

bsearch essentially acts as if sort(1)'s -b flag is always in effect.

At most one column specifier is supported; it is not possible to specify addditional key(s) to search for in secondary (or tertiary...) sort columns.

SEE ALSO

See http://www.eskimo.com/~scs/src/#bsearch for possible updates.

AUTHOR

Steve Summit, scs@eskimo.com