| blob | 07c788b729f7fe2ba9f5ec4709bcde37b1754d7f |
1 .\"
2 .\" Copyright (c) 2011, Secure Endpoints Inc.
3 .\" All rights reserved.
4 .\"
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
7 .\" are met:
8 .\"
9 .\" - Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\"
12 .\" - Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in
14 .\" the documentation and/or other materials provided with the
15 .\" distribution.
16 .\"
17 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
18 .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
19 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
20 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
21 .\" COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
22 .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
23 .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
24 .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
26 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
28 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
29 .\"
30 .Dd November 30, 2011
31 .Dt BSEARCH 1
32 .Os KTH-KRB
33 .Sh NAME
34 .Nm bsearch
35 .Nd manages one-time passwords
36 .Sh SYNOPSIS
37 .Nm bsearch
38 .Op Fl KVvh
39 .Op Fl b Ar block-size
40 .Op Fl m Ar max-cache-size
41 .Ar file
42 .Ar [key ...]
43 .Sh DESCRIPTION
44 The
45 .Nm
46 program performs binary searches of
47 .Ar file
48 which must be a sorted flat text file.
49 .Pp
50 Each line is a record. Each record starts with a key
51 that is optionally followed by whitespace and a value.
52 Whitespace may be quoted with a backslash, but newline
53 and carriage-return characters must be quoted in some
54 other manner (e.g., as backslash-n and backslash-r).
55 Escapes are not interpreted nor removed.
56 .Pp
57 If no key arguments are given on the comman-line, then
58 keys will be read from standard input.
59 .Pp
60 By default only values are printed to standard output.
61 Use the -K option to also print keys. The exit status
62 will be non-zero if any key lookups fail.
63 .Pp
64 Options are:
65 .Bl -tag -width Ds
66 .It Fl K
67 Print keys.
68 .It Fl V
69 Don't print values.
70 .It Fl h
71 Print usage and exit.
72 .It Fl v
73 Print statistic and debug information to standard
74 error.
75 .Ar file
76 A sorted flat text file. NOTE: use the "C" locale for
77 sorting this file, as in "LC_ALL=C sort -u -o file
78 file".
79 .It Fl h
80 For getting a help message.
81 .It Fl m
82 Set
83 .Ar max-cache-size
84 as the maximum cache size. If the
85 .Ar file
86 is smaller than this size then the whole file will be
87 read into memory, else the program will read blocks.
88 Defaults to 1MB.
89 .It Fl b
90 Set
91 .Ar block-size
92 as the block size for block-wise I/O. This must be a
93 power of 2, must be no smaller than 512 and no larger
94 than 1MB. Defaults to the
95 .Ar file's
96 filesystem's preferred blocksize.
97 .El
98 .Sh EXAMPLES
99 .Bd -literal -offset indent
100 $ env LC_ALL=C sort -o /tmp/words /usr/share/dict/words
101 $ bsearch -Kv /tmp/words day
102 Using whole-file method
103 Key day found at offset 327695 in 12 loops and 0 reads
104 day
105 $
106 .Sh NOTES
107 .Pp
108 Records must not be longer than one block's size.
109 .Pp
110 Flat text files must be sorted in the "C" locale. In
111 some systems the default locale may result in
112 case-insensitive sorting by the sort command.
113 .Sh SEE ALSO
114 .Xr sort 1