-rw-r--r-- 2828 cdb-20251021/doc/man/cdbmake.1 raw
.\" Automatically generated by Pandoc 2.17.1.1
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "cdb" "1" "" "" ""
.hy
.SS NAME
.PP
cdbmake - create a constant database
.SS SYNOPSIS
.PP
\f[V]cdbmake\f[R] \f[I]f\f[R] \f[I]ftmp\f[R]
.SS DESCRIPTION
.PP
\f[V]cdbmake\f[R] reads a series of encoded records from its standard
input and writes a constant database to a file named \f[I]f\f[R],
replacing any previous contents of \f[I]f\f[R].
.PP
\f[V]cdbmake\f[R] ensures that \f[I]f\f[R] is updated atomically, so
programs reading \f[I]f\f[R] never have to wait for \f[V]cdbmake\f[R] to
finish.
It does this by first writing the database to \f[I]ftmp\f[R] and then
moving \f[I]ftmp\f[R] on top of \f[I]f\f[R].
If \f[I]ftmp\f[R] already exists, it is destroyed.
The directories containing \f[I]ftmp\f[R] and \f[I]f\f[R] must be
writable to \f[V]cdbmake\f[R]; they must also be on the same filesystem.
.PP
\f[V]cdbmake\f[R] always makes sure that \f[I]ftmp\f[R] is safely
written to disk before it replaces \f[I]f\f[R].
If the input is in a bad format or if \f[V]cdbmake\f[R] has any trouble
writing \f[I]ftmp\f[R] to disk, \f[V]cdbmake\f[R] complains and leaves f
alone.
.PP
There is also a \f[V]cdb64make\f[R] that uses cdb64 format instead of
cdb format.
.SS RECORD FORMAT
.PP
Records are indexed by keys.
A key is a string.
The file \f[I]f\f[R] is structured so that another program, starting
from a key, can quickly find the relevant record.
\f[V]cdbmake\f[R] allows several records with the same key, although
.IP \[bu] 2
most readers take only the first record, and
.IP \[bu] 2
\f[V]cdbmake\f[R] slows down somewhat if there are many records with the
same key.
.PP
\f[V]cdbmake\f[R] preserves the order of records.
.PP
For the input provided to \f[V]cdbmake\f[R], each record is encoded as
+\f[I]klen\f[R],\f[I]dlen\f[R]:\f[I]key\f[R]->\f[I]data\f[R] followed by
a newline.
Here \f[I]klen\f[R] is the number of bytes in \f[I]key\f[R] and
\f[I]dlen\f[R] is the number of bytes in \f[I]data\f[R].
The end of all records is indicated by an extra newline.
For example, here are two records:
.IP
.nf
\f[C]
+3,5:one->Hello
+3,7:two->Goodbye
\f[R]
.fi
.PP
\f[I]key\f[R] and \f[I]data\f[R] may contain any characters, including
colons, dashes, newlines, and nulls.
.PP
Keys and data do not have to fit into memory, but \f[V]cdbmake\f[R]
needs roughly 16 bytes of memory per record.
A database cannot exceed 4 gigabytes (or 1 exabyte for
\f[V]cdb64make\f[R]).
.PP
\f[I]f\f[R] is portable across machines.
.SS SEE ALSO
.PP
\f[B]cdbdump\f[R](1), \f[B]cdbget\f[R](1), \f[B]cdbmake-12\f[R](1),
\f[B]cdbmake-sv\f[R](1), \f[B]cdbstats\f[R](1)