1 .\" This file is part of GDBM. -*- nroff -*-
2 .\" Copyright (C) 2013 Free Software Foundation, Inc.
4 .\" GDBM is free software; you can redistribute it and/or modify
5 .\" it under the terms of the GNU General Public License as published by
6 .\" the Free Software Foundation; either version 3, or (at your option)
9 .\" GDBM is distributed in the hope that it will be useful,
10 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
11 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 .\" GNU General Public License for more details.
14 .\" You should have received a copy of the GNU General Public License
15 .\" along with GDBM. If not, see <http://www.gnu.org/licenses/>. */
16 .TH GDBM_DUMP 1 "May 17, 2013" "GDBM" "GDBM User Reference"
18 gdbmtool \- examine and modify a GDBM database
20 \fBgdbmtool\fR [\fB\-lmNnqrs\fR] [\fB\-b\fR \fISIZE\fR] [\fB\-c\fR \fISIZE\fR]\
21 [\fB\-f\fR \fIFILE\fR] [\fB\-\-block\-size\fR=\fISIZE\fR]
22 [\fB\-\-cache\-size\fR=\fISIZE\fR] [\fB\-\-file\fR \fIFILE\fR]\
23 [\fB\-\-newdb\fR] [\fB\-\-no\-lock\fR]
24 [\fB\-\-no\-mmap\fR] [\fB\-\-norc\fR]
25 [\fB\-\-quiet\fR] [\fB\-\-read\-only\fR] [\fB\-\-synchronize\fR]\
28 \fBgdbmtool\fR [\fB\-Vh\fR] ][\fB\-\-help\fR] [\fB\-\-usage\fR] [\fB\-\-version\fR]
32 utility allows you to view and modify an existing GDBM database or to
35 The \fIDBFILE\fR argument supplies the name of the database to open.
36 If not supplied, the default name
39 If the named database does not exist, it will be created. An existing
40 database can be cleared (i.e. all records removed from it) using the
41 \fB\-\-newdb\fR option (see below).
43 Unless the \fB\-N\fR (\fB\-\-norc\fR) option is given, after startup
47 first in the current working directory, and, if not found there, in
48 the home directory of the user who started the program. If found,
49 this file is read and interpreted as a list of
55 starts a loop, in which it reads
56 commands from the standard input, executes them and prints the results on the
57 standard output. If the standard input is attached to a console,
58 the program runs in interactive mode.
60 The program terminates when the
62 command is given, or end-of-file is detected on its standard input.
66 command consists of a command verb, optionally
67 followed by one or more arguments, separated by any amount of white
68 space. A command verb can be entered either in full or in an
69 abbreviated form, as long as that abbreviation does not match any other
72 Any sequence of non-whitespace characters appearing after the command
73 verb forms an argument. If the argument contains whitespace or
74 unprintable characters it must be enclosed in double quotes. Within
75 double quotes the usual escape sequences are understood, as
76 shown in the table below:
82 \\a Audible bell character (ASCII 7)
83 \\b Backspace character (ASCII 8)
84 \\f Form-feed character (ASCII 12)
85 \\n Newline character (ASCII 10)
86 \\r Carriage return character (ASCII 13)
87 \\t Horizontal tabulation character (ASCII 9)
88 \\v Vertical tabulation character (ASCII 11)
93 In addition, a backslash immediately followed by the end-of-line
94 character effectively removes that character, allowing to split long
95 arguments over several input lines.
98 \fB\-b\fR, \fB\-\-block\-size\fR=\fISIZE\fR
101 \fB\-c\fR, \fB\-\-cache\-size\fR=\fISIZE\fR
104 \fB\-f\fR, \fB\-\-file\fR=\fIFILE\fR
105 Read commands from \fIFILE\fR, instead of from the standard input.
107 \fB\-l\fR, \fB\-\-no\-lock\fR
108 Disable file locking.
110 \fB\-m\fR, \fB\-\-no\-mmap\fR
114 \fB\-n\fR, \fB\-\-newdb\fR
115 Create the database, truncating it if it already exists.
117 \fB\-q\fR, \fB\-\-quiet\fR
118 Don't print initial banner.
120 \fB\-r\fR, \fB\-\-read\-only\fR
121 Open database in read-only mode.
123 \fB\-s\fR, \fB\-\-synchronize\fR
124 Synchronize to disk after each write.
126 \fB\-h\fR, \fB\-\-help\fR
127 Print a short usage summary.
130 Print a list of available options.
132 \fB\-V\fR, \fB\-\-version\fR
133 Print program version
140 \fBbucket\fR \fINUM\fR
141 Print the bucket number \fINUM\fR and set is as the current one.
144 Print the bucket cache.
147 Close the currently open database.
150 Print the number of entries in the database.
153 Print the current bucket.
155 \fBdelete\fR \fIKEY\fR
156 Delete record with the given \fIKEY\fR.
159 Print hash directory.
161 \fBexport\fR, \fBe\fR \fIFILE\-NAME\fR [\fBtruncate\fR] [\fBbinary\fR|\fBascii\fR]
162 Export the database to the flat file \fIFILE\-NAME\fR. This is equivalent to
165 This command will not overwrite an existing file, unless the
167 parameter is also given. Another optional parameter determines the type of
168 the dump (*note Flat files::). By default, ASCII dump will be created.
170 \fBfetch\fR \fIKEY\fR
171 Fetch and display the record with the given \fIKEY\fR.
174 Fetch and display the first record in the database. Subsequent
175 records can be fetched using the
180 Compute and display the hash value for the given \fIKEY\fR.
186 Print a concise command summary, showing each command letter and
187 verb with its parameters and a short description of what it does.
188 Optional arguments are enclosed in square brackets.
190 \fBimport\fR \fIFILE\-NAME\fR [\fBreplace\fR] [\fBnometa\fR]
191 Import data from a flat dump file \fIFILE\-NAME\fR.
194 argument is given, any records with the same keys as the already
195 existing ones will replace them. The
197 argument turns off restoring meta-information from the dump file.
200 List the contents of the database.
202 \fBnext\fR [\fIKEY\fR]
203 Sequential access: fetch and display the next record. If the \fIKEY\fR is
204 given, the record following the one with this key will be fetched.
206 \fBopen\fR \fIFILE\fR
207 Open the database file \fIFILE\fR. If successful, any previously
208 open database is closed. Otherwise, if the operation fails, the
209 currently opened database remains unchanged.
211 This command takes additional information from the variables
218 for a detailed description of these.
221 Close the database and quit the utility.
224 Reorganize the database.
225 \fBset\fR [\fIVAR\fR=\fIVALUE\fR...]
226 Without arguments, lists variables and their values. If arguments are
227 specified, sets variables. Boolean variables can be set by specifying
228 variable name, optionally prefixed with \fBno\fR, to set it to \fBfalse\fR.
230 \fBsource\fR \fIFILE\fR
231 Read commands from the given \fIFILE\fR.
234 Print current program status.
236 \fBstore\fR \fIKEY\fR \fIDATA\fR
237 Store the \fIDATA\fR with the given \fIKEY\fR in the database. If the
238 \fIKEY\fR already exists, its data will be replaced.
240 \fBunset\fR \fIVARIABLE\fR...
241 Unsets listed variables.
246 .SH "DATA DEFINITIONS"
247 The \fBdefine\fR statement provides a mechanism for defining key or
248 content structures. It is similar to the \fBC\fR \fBstruct\fR
253 \fBdefine\fR \fBkey\fR|\fBcontent\fR \fB{\fR \fIdefnlist\fR \fB}\fR
257 The \fIdefnlist\fR is a comma-separated list of member declarations.
258 Within \fIdefnlist\fR the newline character looses its special meaning
259 as the command terminator, so each declaration can appear on a
260 separate line and arbitrary number of comments can be inserted to
261 document the definition.
263 Each declaration has one of the following formats
267 \fItype\fR \fIname\fR
268 \fItype\fR \fIname\fR \fB[\fIN\fB]\fR
272 where \fItype\fR is a data type and \fIname\fR is the member name.
273 The second format defines the member \fIname\fR as an array of \fIN\fR
274 elements of \fItype\fR.
276 The supported types are:
282 char single byte (signed)
283 short signed short integer
284 ushort unsigned short integer
286 unsigned unsigned integer
288 long signed long integer
289 ulong unsigned long integer
290 llong signed long long integer
291 ullong unsigned long long integer
292 float a floating point number
293 double double-precision floating point number
294 string array of characters (see the \fBNOTE\fR below)
295 stringz null-terminated string of characters
298 The following alignment declarations can be used within \fIdefnlist\fR:
301 The next member begins at offset \fIN\fR.
304 Add \fIN\fR bytes of padding to the previous member.
318 To define data consisting of a single data member, the following
319 simplified construct can be used:
323 \fBdefine\fR \fBkey\fR|\fBcontent\fR \fItype\fR
326 where \fItype\fR is one of the types discussed above.
328 \fBNOTE\fR: The \fBstring\fR type can reasonably be used only if it is
329 the last or the only member of the data structure. That's because it
330 provides no information about the number of elements in the array, so
331 it is interpreted to contain all bytes up to the end of the datum.
334 .BR confirm ", boolean"
335 Whether to ask for confirmation before certain destructive operations,
336 such as truncating the existing database. Default is
340 Primary prompt string. Its value can contain \fIconversion
341 specifiers\fR, consisting of the \fB%\fR character followed by another
342 character. These specifiers are expanded in the resulting prompt as
349 \fB%f\fR name of the db file
350 \fB%p\fR program name
351 \fB%P\fR package name (\fBgdbm\fR)
352 \fB%_\fR horizontal space (\fBASCII\fR 32)
353 \fB%v\fR program version
357 The default prompt is \fB%p>%_\fR.
360 Secondary prompt. See
362 for a description of its value.
363 This prompt is displayed before reading the second and subsequent
364 lines of a multi-line command.
366 The default value is \fB%_>%_\fR.
368 .BR delim1 ", string"
369 A string used to delimit fields of a structured datum on output
370 (see the section \fBDATA DEFINITIONS\fR).
372 Default is \fB,\fR (a comma). This variable cannot be unset.
374 .BR delim2 ", string"
375 A string used to delimit array items when printing a structured datum.
377 Default is \fB,\fR (a comma). This variable cannot be unset.
380 The name and command line of the pager program to pipe output to.
381 This program is used in interactive mode when the estimated number of
382 output lines is greater then the number of lines on your screen.
384 The default value is inherited from the environment variable
385 \fBPAGER\fR. Unsetting this variable disables paging.
387 .BR quiet ", boolean"
388 Whether to display welcome banner at startup. This variable should
389 be set in a startup script file.
391 The following variables control how the database is opened:
393 .BR cachesize ", numeric"
394 Sets the cache size. By default this variable is not set.
396 .BR blocksize ", numeric"
397 Sets the block size. Unset by default.
400 Open mode. The following values are allowed:
404 Truncate the database if it exists or create a new one. Open it in
407 .BR wrcreat " or " rw
408 Open the database in read-write mode. Create it if it does not
409 exist. This is the default.
411 .BR reader " or " readonly
412 Open the database in read-only mode. Signal an error if it does not
417 Lock the database. This is the default.
420 Use memory mapping. This is the default.
427 Report bugs to <bug\-gdbm@gnu.org>.
429 Copyright \(co 2013 Free Software Foundation, Inc
432 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
435 This is free software: you are free to change and redistribute it.
436 There is NO WARRANTY, to the extent permitted by law.
438 .\" eval: (add-hook 'write-file-hooks 'time-stamp)
439 .\" time-stamp-start: ".TH GDBM[A-Z_-]* 1 \""
440 .\" time-stamp-format: "%:B %:d, %:y"
441 .\" time-stamp-end: "\""
442 .\" time-stamp-line-limit: 20