.\"
.\" Copyright (c) 2011, Secure Endpoints Inc.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" - Redistributions of source code must retain the above copyright
.\"   notice, this list of conditions and the following disclaimer.
.\"
.\" - Redistributions in binary form must reproduce the above copyright
.\"   notice, this list of conditions and the following disclaimer in
.\"   the documentation and/or other materials provided with the
.\"   distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
.\" COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
.\" OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd November 30, 2011
.Dt BSEARCH 1
.Os KTH-KRB
.Sh NAME
.Nm bsearch
.Nd manages one-time passwords
.Sh SYNOPSIS
.Nm bsearch
.Op Fl KVvh
.Op Fl b Ar block-size
.Op Fl m Ar max-cache-size
.Ar file
.Ar [key ...]
.Sh DESCRIPTION
The
.Nm
program performs binary searches of
.Ar file
which must be a sorted flat text file.
.Pp
Each line is a record.  Each record starts with a key
that is optionally followed by whitespace and a value.
Whitespace may be quoted with a backslash, but newline
and carriage-return characters must be quoted in some
other manner (e.g., as backslash-n and backslash-r).
Escapes are not interpreted nor removed.
.Pp
If no key arguments are given on the comman-line, then
keys will be read from standard input.
.Pp
By default only values are printed to standard output.
Use the -K option to also print keys.  The exit status
will be non-zero if any key lookups fail.
.Pp
Options are:
.Bl -tag -width Ds
.It Fl K
Print keys.
.It Fl V
Don't print values.
.It Fl h
Print usage and exit.
.It Fl v
Print statistic and debug information to standard
error.
.Ar file
A sorted flat text file.  NOTE: use the "C" locale for
sorting this file, as in "LC_ALL=C sort -u -o file
file".
.It Fl h
For getting a help message.
.It Fl m
Set
.Ar max-cache-size
as the maximum cache size.  If the
.Ar file
is smaller than this size then the whole file will be
read into memory, else the program will read blocks.
Defaults to 1MB.
.It Fl b
Set
.Ar block-size
as the block size for block-wise I/O.  This must be a
power of 2, must be no smaller than 512 and no larger
than 1MB.  Defaults to the
.Ar file's
filesystem's preferred blocksize.
.El
.Sh EXAMPLES
.Bd -literal -offset indent
$ env LC_ALL=C sort -o /tmp/words /usr/share/dict/words
$ bsearch -Kv /tmp/words day
Using whole-file method
Key day found at offset 327695 in 12 loops and 0 reads
day
$ 
.Ed
.Sh NOTES
.Pp
Records must not be longer than one block's size.
.Pp
Flat text files must be sorted in the "C" locale.  In
some systems the default locale may result in
case-insensitive sorting by the sort command.
.Sh SEE ALSO
.Xr sort 1