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