NetBSD/usr.bin/db/db.1

.\" 	$NetBSD: db.1,v 1.17 2005/06/20 02:53:38 lukem Exp $
.\"
.\" Copyright (c) 2002-2005 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.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the NetBSD
.\"	Foundation, Inc. and its contributors.
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific prior written permission.
.\"
.\" 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 June 20, 2005
.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 KiNqV
.Bk -words
.Op Fl E Ar endian
.Ek
.Bk -words
.Op Fl f Ar infile
.Ek
.Bk -words
.Op Fl O Ar outsep
.Ek
.Bk -words
.Op Fl S Ar visitem
.Ek
.Bk -words
.Op Fl T Ar visspec
.Ek
.Bk -words
.Op Fl X Ar extravis
.Ek
.Ar type
.Ar dbfile
.Bk -words
.Op Ar key Op Ar \&.\&.\&.
.Ek
.
.Nm
.Fl d
.Op Fl iNq
.Bk -words
.Op Fl E Ar endian
.Ek
.Bk -words
.Op Fl f Ar infile
.Ek
.Bk -words
.Op Fl U Ar unvisitem
.Ek
.Ar type
.Ar dbfile
.Bk -words
.Op Ar key Op Ar \&.\&.\&.
.Ek
.
.Nm
.Fl w
.Op Fl CDiNqR
.Bk -words
.Op Fl E Ar endian
.Ek
.Bk -words
.Op Fl F Ar insep
.Ek
.Bk -words
.Op Fl f Ar infile
.Ek
.Bk -words
.Op Fl m Ar mode
.Ek
.Bk -words
.Op Fl U Ar unvisitem
.Ek
.Ar type
.Ar dbfile
.Bk -words
.Op Ar key Ar value Op Ar \&.\&.\&.
.Ek
.
.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
Do not include the NUL byte at the end of the key or value.
.
.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.
.
.El
.
.Pp
Read mode specific options are:
.
.Bl -tag -width Fl -offset indent
.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 strvis 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 T Ar visspec
Control how the items specified by the
.Fl S
option are encoded.
The
.Ar visspec
option-argument is a string specifying
.Xr strvis 3
options.
The string consists of the specification characters
.Cm b , c , o ,
.Cm s , t ,
and
.Cm w .
See
.Xr vis 1 Ns 's
corresponding options for the meaning of these characters.
.
.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 svis 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.
(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 R
Overwrite existing entries.
If not specified, writing to an existing entry raises an error.
.
.El
.Pp
Write and delete mode specific options are:
.Bl -tag -width Fl -offset indent
.
.It Fl U Ar unvisitem
Specify items to
.Xr strunvis 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
.
.Sh SEE ALSO
.Xr vis 1 ,
.Xr btree 3 ,
.Xr db 3 ,
.Xr hash 3 ,
.Xr strunvis 3 ,
.Xr strvis 3 ,
.Xr svis 3 ,
.Xr makemap 8
.
.Sh HISTORY
The
.Nm
command appeared in
.Nx 2.0 .
.
.Sh AUTHORS
.An Luke Mewburn
.Aq lukem@NetBSD.org .