.TH cdbmake 1
.SH NAME
cdbmake \- create a constant database
.SH SYNOPSIS
.B cdbmake
.I cdb
.I cdb.tmp
.SH DESCRIPTION
.B cdbmake
reads a series of encoded records from its standard input and writes a
constant database to
.IR cdb .
.P
.B cdbmake
ensures that
.I cdb
is updated atomically, so programs reading
.I cdb
never have to wait for
.B cdbmake
to finish.
It does this by first writing the database to
.I cdb.tmp
and then moving
.I cdb.tmp
on top of
.IR cdb .
If
.I cdb.tmp
already exists, it is destroyed.
The directories containing
.I cdb.tmp
and
.I cdb
must be writable to
.BR cdbmake ;
they must also be on the same filesystem.
.P
.B cdbmake
always makes sure that
.I cdb.tmp
is safely written to disk before it replaces
.IR cdb .
If the input is in a bad format or if
.B cdbmake
has any trouble writing
.I cdb.tmp
to disk,
.B cdbmake
complains and leaves
.I cdb
alone.
.SS RECORD FORMAT
Records are indexed by keys.
A key is a string.
.I cdb
is structured so that another program, starting from a key, can quickly find
the relevant record.
.B cdbmake
allows several records with the same key, although most readers take only
the first record, and
.B cdbmake
slows down somewhat if there are many records with the same key.
.P
.B cdbmake
and
.BR cdbdump (1)
preserve the order of records.
.P
A record is encoded for
.B cdbmake
as +\fIklen\fR,\fIdlen\fR:\fIkey\fR->\fIdata\fR followed by a newline.
Here
.I klen
is the number of bytes in
.I key
and
.I dlen
is the number of bytes in
.IR data .
The end of
.I data
is indicated by an extra newline.
For example:
.P
  +3,5:one->Hello
  +3,7:two->Goodbye
.P
.I key
and
.I data
may contain any characters, including colons, dashes, newlines, and nulls.
.P
Keys and data do not have to fit into memory.
A database cannot exceed 4 gigabytes.
.P
.I cdb
is portable across machines.
.SH SEE ALSO
cdbdump(1),
cdbget(1),
cdbstats(1)