BSEARCH(1)

💖 BSEARCH — okay bestie, let's talk binary search 💖

so this page is bsearch, and it comes to you from section 1 of the General Commands Manual — aka the "general commands" shelf, the one where all the little utilities live. it's not a deep lore page, it's a do one thing really well page. and that thing? binary searching sorted text files. slay. 💅

🌸 NAME 🌸

bsearch — manages one-time passwords 🎀

yes, that's really what it says. we don't ask questions, we just report the facts. iykyk.

✨ SYNOPSIS ✨

bsearch [-KVvh] [-b block-size] [-m max-cache-size] file [key ...]

🦋 DESCRIPTION 🦋

okay so here's the whole vibe: bsearch does binary searches of file, and file must be a sorted flat text file. that's not a suggestion, that's the law. 🫶

every single line is a record. and every record starts with a key that's optionally followed by whitespace and a value. you can quote whitespace with a backslash — but listen, newline and carriage-return characters must be quoted some other way (like as backslash-n and backslash-r, for example). and no, escapes are not interpreted and they are not removed. they just sit there, exactly as you typed them. no cap. 💀

if you don't pass any key arguments on the command line, then the keys get read from standard input instead. group-chat style: it'll just wait for you to slide into its DMs.

by default, only values get printed to standard output. want the keys too? that's what -K is for. and heads up: the exit status will be non-zero if any of the key lookups fail. 😭

the options are:

👑 OPTIONS 👑

• -K — print keys. give the people what they want (the keys).
• -V — don't print values. values found sleeping, do not disturb. 🙈
• -h — print usage and exit.
• -v — print statistic and debug information to standard error. and then, right here in the same breath: file is a sorted flat text file. NOTE: use the "C" locale for sorting this file, as in "LC_ALL=C sort -u -o file file". yes, we know this bullet is doing two jobs at once. it's giving multitasking. it ate. 🍓
• -h — for getting a help message. (yes, -h is listed twice. iconic behavior, honestly. both are true, both are real, we love consistency.) ✨
• -m max-cache-size — set max-cache-size as the maximum cache size. if the file is smaller than this size, then the whole file gets read into memory; otherwise the program reads blocks instead. defaults to 1MB.
• -b block-size — set block-size as the block size for block-wise I/O. it must be a power of 2, it must be no smaller than 512, and it must be no larger than 1MB. defaults to the file's filesystem's preferred blocksize. no rogue numbers allowed, periodt. 🎀

🌈 EXAMPLES 🌈

here's the little demo, exactly as the page gives it:

$ 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
$

look at that. 12 loops, 0 reads, found at offset 327695. main character energy fr fr. 🔥

🧚 NOTES 🧚

• records must not be longer than one block's size. that's the hard limit, don't test it.
• flat text files must be sorted in the "C" locale. on some systems, the default locale may result in case-insensitive sorting by the sort command — which would absolutely wreck your binary search, so watch out. 💀
• the "C" locale is not a vibe, it's a requirement. slay responsibly.

💜 SEE ALSO 💜

• sort(1)

and that's the whole page bestie 🫶 — this little icon was brought to you by KTH-KRB, dated November 30, 2011. go forth and binary search. periodt. 💖✨🎀