.\" 	$NetBSD: db.1,v 1.27 2012/02/17 11:43:24 wiz Exp $
.\"
.\" Copyright (c) 2002-2009,2012 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Luke Mewburn of Wasabi Systems.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 February 17, 2012
.Dt DB 1
.Os
.
.Sh NAME
.Nm db
.Nd
manipulate
.Xr db 3 Ns 's
.Xr btree 3
and
.Xr hash 3
databases
.
.Sh SYNOPSIS
.Nm
.Op Fl DKiNqV
.Op Fl E Ar endian
.Op Fl f Ar infile
.Op Fl O Ar outsep
.Op Fl S Ar visitem
.Op Fl T Ar visspec
.Op Fl U Ar unvisitem
.Op Fl X Ar extravis
.Ar type
.Ar dbfile
.Op Ar key Op Ar \&.\&.\&.
.
.Nm
.Fl d
.Op Fl iNq
.Op Fl E Ar endian
.Op Fl f Ar infile
.Op Fl T Ar visspec
.Op Fl U Ar unvisitem
.Ar type
.Ar dbfile
.Op Ar key Op Ar \&.\&.\&.
.
.Nm
.Fl w
.Op Fl CDiNqR
.Op Fl E Ar endian
.Op Fl F Ar insep
.Op Fl f Ar infile
.Op Fl m Ar mode
.Op Fl P Ar pagesize
.Op Fl T Ar visspec
.Op Fl U Ar unvisitem
.Ar type
.Ar dbfile
.Op Ar key Ar value Op Ar \&.\&.\&.
.
.Sh DESCRIPTION
.Nm
allows manipulation of
.Xr btree 3
and
.Xr hash 3
.Pq Xr db 3
databases.
.Pp
.Nm
has three modes of operation to perform upon
.Ar dbfile :
.Bl -tag -width "delete" -offset indent
.It read
Displays the given
.Ar key Ns s ,
and keys described in
.Ar infile .
If no keys and no
.Ar infile
is specified, the entire database is displayed.
This is the default mode of operation.
.It delete
Enabled with
.Fl d .
Deletes the given
.Ar key Ns s ,
and keys described in
.Ar infile .
.It write
Enabled with
.Fl w .
Writes the given
.Ar key Ns s
and
.Ar value Ns s ,
and keys and values described in
.Ar infile
(in the latter case, entries are separated by
.Ar insep ) .
.El
.Pp
There are two mandatory arguments:
.Ar type
is the database type; either
.Sq Sy btree
or
.Sq Sy hash ,
and
.Ar dbfile
is the database file to manipulate.
.Pp
Options valid for all modes are:
.Bl -tag -width Fl -offset indent
.
.It Fl E Ar endian
Set the endianness of the database.
.Ar endian
may be one of:
.Bl -tag -width 1n -offset indent -compact
.It Sy B
Big endian
.It Sy H
Host endian
.It Sy L
Little endian
.El
Defaults to
.Sq H
(host endian).
.
.It Fl f Ar infile
Contains a list of keys
(for read and delete), or
.Ar insep
separated keys and values (for write)
to be used as arguments to the given mode.
If
.Ar infile
is
.Sq Sy - ,
.Dv stdin
is used.
.
.It Fl i
Keys are converted to lower case before manipulation.
.
.It Fl N
Include the NUL byte at the end of the key or value.
.Pp
By convention, each key and value in the underlying database is
terminated with a NUL byte, although it is possible to have keys
or values that are not so terminated.
Without the
.Fl N
option,
.Nm
adds a NUL terminator to any keys and values specified on the
command line or in the input file,
before searching or modifying the underlying database,
and removes the last byte (which is usually a NUL terminator)
before printing any keys and values retrieved from the
underlying database.
With the
.Fl N
option,
.Nm
does not add or remove a terminating byte.
The
.Fl S , Fl T ,
and
.Fl U
options may be useful to encode the NUL terminator in a readable form.
.
.It Fl q
Quiet operation.
In read mode, missing keys are not considered to be an error.
In delete
.Pq Fl d
and write
.Pq Fl w
modes,
the result of various operations is suppressed.
.
.It Fl T Ar visspec
Control how the items specified by the
.Fl S
option are encoded
and
.Fl U
option are decoded.
The
.Ar visspec
option-argument is a string specifying
.Xr strsvisx 3
flags.
The string consists of one or more characters:
.Bl -tag -width 2n -offset indent -compact
.It Sy b
.Dv VIS_NOSLASH
.It Sy c
.Dv VIS_CSTYLE .
Overrides
.Sy h
and
.Sy o .
.It Sy h
.Dv VIS_HTTPSTYLE .
Overrides
.Sy c
and
.Sy o .
.It Sy o
.Dv VIS_OCTAL .
Overrides
.Sy c
and
.Sy h .
.It Sy s
.Dv VIS_SAFE
.It Sy t
.Dv VIS_TAB
.It Sy w
.Dv VIS_WHITE
.El
.Pp
.Fl U
only supports
.Fl T
.Sy h .
.Pp
See
.Xr vis 1 Ns 's
corresponding options for the meaning of these characters,
and
.Xr strsvisx 3
for more detail on the flags.
.
.It Fl U Ar unvisitem
Specify items to
.Xr strunvisx 3
decode.
The
.Ar unvisitem
option-argument is a character specifying if the key
.Pq Ar k ,
the value
.Pq Ar v
or both
.Pq Ar b
should be decoded.
.
.El
.
.Pp
Read mode specific options are:
.
.Bl -tag -width Fl -offset indent
.
.It Fl D
Display duplicate entries in
.Sy btree
databases.
.
.It Fl K
Display key.
.
.It Fl O Ar outsep
Field separator string between key and value.
Defaults to a single tab
.Pq Sq \et .
.
.It Fl S Ar visitem
Specify items to
.Xr strsvisx 3
encode.
The
.Ar visitem
option-argument is a character specifying if the key
.Pq Ar k ,
the value
.Pq Ar v
or both
.Pq Ar b
should be encoded.
.
.It Fl V
Display value.
.
.It Fl X Ar extravis
When encoding items with
.Fl S
option also encode characters in
.Ar extravis ,
per
.Xr strsvisx 3 .
.
.El
.Pp
.Bd -ragged -offset indent
(If neither of
.Fl K
or
.Fl V
is given, both options are enabled.)
.Ed
.
.Pp
Write mode specific options are:
.Bl -tag -width Fl -offset indent
.
.It Fl C
Create new database, and truncate existing databases.
.
.It Fl D
Allow duplicate entries in
.Sy btree
databases.
(Requires
.Fl R
to be useful.)
.
.It Fl F Ar insep
Input field separator string between key and value used when parsing
.Ar infile .
Defaults to a single space
.Pq Sq \  .
.
.It Fl m Ar mode
Octal mode of created database.
Defaults to
.Sq 0644 .
.
.It Fl P Ar pagesize
Set the page size of the table to
.Ar pagesize
bytes.
If set to
.Sq 0 ,
a database-specific default is determined,
based on the block-size of the underlying file-system.
Defaults to
.Sq 4096 .
.
.It Fl R
Overwrite existing entries.
If not specified, writing to an existing entry raises an error.
.
.El
.
.Sh SEE ALSO
.Xr vis 1 ,
.Xr btree 3 ,
.Xr db 3 ,
.Xr hash 3 ,
.Xr strsvisx 3 ,
.Xr strunvisx 3
.\" .Xr makemap 8
.
.Sh HISTORY
The
.Nm
command appeared in
.Nx 2.0 .
.
.Sh AUTHORS
.An Luke Mewburn
.Aq lukem@NetBSD.org .