1.\"	$MirOS: src/usr.bin/db/db.1,v 1.2 2008/04/07 05:16:43 tg Exp $
2.\" 	$NetBSD: db.1,v 1.18 2007/12/27 12:56:49 wiz Exp $
3.\"
4.\" Copyright (c) 2002-2005 The NetBSD Foundation, Inc.
5.\" All rights reserved.
6.\"
7.\" This code is derived from software contributed to The NetBSD Foundation
8.\" by Luke Mewburn of Wasabi Systems.
9.\"
10.\" Redistribution and use in source and binary forms, with or without
11.\" modification, are permitted provided that the following conditions
12.\" are met:
13.\" 1. Redistributions of source code must retain the above copyright
14.\"    notice, this list of conditions and the following disclaimer.
15.\" 2. Redistributions in binary form must reproduce the above copyright
16.\"    notice, this list of conditions and the following disclaimer in the
17.\"    documentation and/or other materials provided with the distribution.
18.\" 3. All advertising materials mentioning features or use of this software
19.\"    must display the following acknowledgement:
20.\"	This product includes software developed by the NetBSD
21.\"	Foundation, Inc. and its contributors.
22.\" 4. Neither the name of The NetBSD Foundation nor the names of its
23.\"    contributors may be used to endorse or promote products derived
24.\"    from this software without specific prior written permission.
25.\"
26.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
27.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
28.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
29.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
30.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
31.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
32.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
33.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
34.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
35.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
36.\" POSSIBILITY OF SUCH DAMAGE.
37.\"
38.Dd June 20, 2005
39.Dt DB 1
40.Os
41.
42.Sh NAME
43.Nm db
44.Nd
45manipulate
46.Xr db 3 Ns 's
47.Xr btree 3
48and
49.Xr hash 3
50databases
51.
52.Sh SYNOPSIS
53.Nm
54.Op Fl KiNqV
55.Bk -words
56.Op Fl E Ar endian
57.Ek
58.Bk -words
59.Op Fl f Ar infile
60.Ek
61.Bk -words
62.Op Fl O Ar outsep
63.Ek
64.Bk -words
65.Op Fl S Ar visitem
66.Ek
67.Bk -words
68.Op Fl T Ar visspec
69.Ek
70.Bk -words
71.Op Fl X Ar extravis
72.Ek
73.Ar type
74.Ar dbfile
75.Bk -words
76.Op Ar key Op Ar \&.\&.\&.
77.Ek
78.
79.Nm
80.Fl d
81.Op Fl iNq
82.Bk -words
83.Op Fl E Ar endian
84.Ek
85.Bk -words
86.Op Fl f Ar infile
87.Ek
88.Bk -words
89.Op Fl U Ar unvisitem
90.Ek
91.Ar type
92.Ar dbfile
93.Bk -words
94.Op Ar key Op Ar \&.\&.\&.
95.Ek
96.
97.Nm
98.Fl w
99.Op Fl CDiNqR
100.Bk -words
101.Op Fl E Ar endian
102.Ek
103.Bk -words
104.Op Fl F Ar insep
105.Ek
106.Bk -words
107.Op Fl f Ar infile
108.Ek
109.Bk -words
110.Op Fl m Ar mode
111.Ek
112.Bk -words
113.Op Fl U Ar unvisitem
114.Ek
115.Ar type
116.Ar dbfile
117.Bk -words
118.Op Ar key Ar value Op Ar \&.\&.\&.
119.Ek
120.
121.Sh DESCRIPTION
122.Nm
123allows manipulation of
124.Xr btree 3
125and
126.Xr hash 3
127.Pq Xr db 3
128databases.
129.Pp
130.Nm
131has three modes of operation to perform upon
132.Ar dbfile :
133.Bl -tag -width "delete" -offset indent
134.It read
135Displays the given
136.Ar key Ns s ,
137and keys described in
138.Ar infile .
139If no keys and no
140.Ar infile
141is specified, the entire database is displayed.
142This is the default mode of operation.
143.It delete
144Enabled with
145.Fl d .
146Deletes the given
147.Ar key Ns s ,
148and keys described in
149.Ar infile .
150.It write
151Enabled with
152.Fl w .
153Writes the given
154.Ar key Ns s
155and
156.Ar value Ns s ,
157and keys and values described in
158.Ar infile
159(in the latter case, entries are separated by
160.Ar insep ) .
161.El
162.Pp
163There are two mandatory arguments:
164.Ar type
165is the database type; either
166.Sq Sy btree
167or
168.Sq Sy hash ,
169and
170.Ar dbfile
171is the database file to manipulate.
172.Pp
173Options valid for all modes are:
174.Bl -tag -width Fl -offset indent
175.
176.It Fl E Ar endian
177Set the endianness of the database.
178.Ar endian
179may be one of:
180.Bl -tag -width 1n -offset indent -compact
181.It Sy B
182Big endian
183.It Sy H
184Host endian
185.It Sy L
186Little endian
187.El
188Defaults to
189.Sq H
190(host endian).
191.
192.It Fl f Ar infile
193Contains a list of keys
194(for read and delete), or
195.Ar insep
196separated keys and values (for write)
197to be used as arguments to the given mode.
198If
199.Ar infile
200is
201.Sq Sy - ,
202.Dv stdin
203is used.
204.
205.It Fl i
206Keys are converted to lower case before manipulation.
207.
208.It Fl N
209Do not include the NUL byte at the end of the key or value.
210.
211.It Fl q
212Quiet operation.
213In read mode, missing keys are not considered to be an error.
214In delete
215.Pq Fl d
216and write
217.Pq Fl w
218modes,
219the result of various operations is suppressed.
220.
221.El
222.
223.Pp
224Read mode specific options are:
225.
226.Bl -tag -width Fl -offset indent
227.It Fl K
228Display key.
229.
230.It Fl O Ar outsep
231Field separator string between key and value.
232Defaults to a single tab
233.Pq Sq \et .
234.
235.It Fl S Ar visitem
236Specify items to
237.Xr strvis 3
238encode.
239The
240.Ar visitem
241option-argument is a character specifying if the key
242.Pq Ar k ,
243the value
244.Pq Ar v
245or both
246.Pq Ar b
247should be encoded.
248.
249.It Fl T Ar visspec
250Control how the items specified by the
251.Fl S
252option are encoded.
253The
254.Ar visspec
255option-argument is a string specifying
256.Xr strvis 3
257options.
258The string consists of the specification characters
259.Cm b , c , o ,
260.Cm s , t ,
261and
262.Cm w .
263See
264.Xr vis 1 Ns 's
265corresponding options for the meaning of these characters.
266.
267.It Fl V
268Display value.
269.
270.It Fl X Ar extravis
271When encoding items with
272.Fl S
273option also encode characters in
274.Ar extravis ,
275per
276.Xr svis 3 .
277.
278.El
279.Pp
280.Bd -ragged -offset indent
281(If neither of
282.Fl K
283or
284.Fl V
285is given, both options are enabled.)
286.Ed
287.
288.Pp
289Write mode specific options are:
290.Bl -tag -width Fl -offset indent
291.
292.It Fl C
293Create new database, and truncate existing databases.
294.
295.It Fl D
296Allow duplicate entries.
297(Requires
298.Fl R
299to be useful.)
300.
301.It Fl F Ar insep
302Input field separator string between key and value used when parsing
303.Ar infile .
304Defaults to a single space
305.Pq Sq \  .
306.
307.It Fl m Ar mode
308Octal mode of created database.
309Defaults to
310.Sq 0644 .
311.
312.It Fl R
313Overwrite existing entries.
314If not specified, writing to an existing entry raises an error.
315.
316.El
317.Pp
318Write and delete mode specific options are:
319.Bl -tag -width Fl -offset indent
320.
321.It Fl U Ar unvisitem
322Specify items to
323.Xr strunvis 3
324decode.
325The
326.Ar unvisitem
327option-argument is a character specifying if the key
328.Pq Ar k ,
329the value
330.Pq Ar v
331or both
332.Pq Ar b
333should be decoded.
334.
335.El
336.
337.Sh SEE ALSO
338.Xr vis 1 ,
339.Xr btree 3 ,
340.Xr db 3 ,
341.Xr hash 3 ,
342.Xr strunvis 3 ,
343.Xr strvis 3 ,
344.Xr svis 3
345.\" .Xr makemap 8
346.
347.Sh HISTORY
348The
349.Nm
350command appeared in
351.Nx 2.0 .
352It was imported into
353.Mx 11 .
354.
355.Sh AUTHORS
356.An Luke Mewburn
357.Aq lukem@NetBSD.org .
358