1GDBMTOOL(1) GDBM User Reference GDBMTOOL(1)
2
6 gdbmtool - examine and modify a GDBM database
7
9 gdbmtool [-lmNnqrs] [-b SIZE] [-c SIZE] [-f FILE] [--block-size=SIZE]
10 [--cache-size=SIZE] [--file FILE] [--newdb] [--no-lock] [--no-mmap]
11 [--norc] [--quiet] [--read-only] [--synchronize] [DBFILE] [COMMAND [;
12 COMMAND...]]
13 gdbmtool [-Vh] [--help] [--usage] [--version]
15
17 The gdbmtool utility allows you to view and modify an existing GDBM
18 database or to create a new one.
19 The DBFILE argument supplies the name of the database to open. If not
21 supplied, the default name junk.gdbm is used instead. If the named
22 database does not exist, it will be created. An existing database can
23 be cleared (i.e. all records removed from it) using the --newdb option
24 (see below).
25 Unless the -N (--norc) option is given, after startup gdbmtool looks
27 for file named .gdbmtoolrc first in the current working directory, and,
28 if not found there, in the home directory of the user who started the
29 program. If found, this file is read and interpreted as a list of
30 gdbmtool commands.
31 Then gdbmtool starts a loop, in which it reads commands from the stan‐
33 dard input, executes them and prints the results on the standard out‐
34 put. If the standard input is attached to a console, the program runs
35 in interactive mode.
36 The program terminates when the quit command is given, or end-of-file
38 is detected on its standard input.
39 Commands can also be specified in the command line, after the DBFILE
41 argument. In this case, they will be interpreted without attempting to
42 read more commands from the standard input.
43 If several commands are supplied, they must be separated by semicolons
45 (properly escaped or quoted, in order to prevent them from being inter‐
46 preted by the shell).
47 A gdbmtool command consists of a command verb, optionally followed by
49 one or more arguments, separated by any amount of white space. A com‐
50 mand verb can be entered either in full or in an abbreviated form, as
51 long as that abbreviation does not match any other verb.
52 Any sequence of non-whitespace characters appearing after the command
54 verb forms an argument. If the argument contains whitespace or un‐
55 printable characters it must be enclosed in double quotes. Within dou‐
56 ble quotes the usual escape sequences are understood, as shown in the
57 table below:
58 Escape Expansion
60 \a Audible bell character (ASCII 7)
61 \b Backspace character (ASCII 8)
62 \f Form-feed character (ASCII 12)
63 \n Newline character (ASCII 10)
64 \r Carriage return character (ASCII 13)
65 \t Horizontal tabulation character (ASCII 9)
66 \v Vertical tabulation character (ASCII 11)
67 \\ Single slash
68 In addition, a backslash immediately followed by the end-of-line char‐
71 acter effectively removes that character, allowing to split long argu‐
72 ments over several input lines.
73
75 -b, --block-size=SIZE
76 Set block size.
77 -c, --cache-size=SIZE
79 Set cache size.
80 -f, --file=FILE
82 Read commands from FILE, instead of from the standard input.
83 -l, --no-lock
85 Disable file locking.
86 -m, --no-mmap
88 Do not use mmap(2).
89 -n, --newdb
91 Create the database, truncating it if it already exists.
92 -q, --quiet
94 Don't print initial banner.
95 -r, --read-only
97 Open database in read-only mode.
98 -s, --synchronize
100 Synchronize to disk after each write.
101 -h, --help
103 Print a short usage summary.
104 --usage
106 Print a list of available options.
107 -V, --version
109 Print program version
110
112 avail Print the avail list.
113 bucket NUM
115 Print the bucket number NUM and set is as the current one.
116 cache Print the bucket cache.
118 close Close the currently open database.
120 count Print the number of entries in the database.
122 current
124 Print the current bucket.
125 delete KEY
127 Delete record with the given KEY.
128 dir Print hash directory.
130 downgrade
132 Downgrade the database from the extended numsync format to the
133 standard format.
134 export FILE-NAME [truncate] [binary|ascii]
136 Export the database to the flat file FILE-NAME. This is equiva‐
137 lent to gdbm_dump(1).
138 This command will not overwrite an existing file, unless the
140 truncate parameter is also given. Another optional parameter
141 determines the type of the dump (*note Flat files::). By de‐
142 fault, ASCII dump will be created.
143 fetch KEY
145 Fetch and display the record with the given KEY.
146 first Fetch and display the first record in the database. Subsequent
148 records can be fetched using the next command (see below).
149 hash KEY
151 Compute and display the hash value for the given KEY.
152 header Print file header.
154 help or ?
156 Print a concise command summary, showing each command letter and
157 verb with its parameters and a short description of what it
158 does. Optional arguments are enclosed in square brackets.
159 history
161 Shows the command history list with line numbers. This command
162 is available only if the program was compiled with GNU Readline.
163 history COUNT.
165 Shows COUNT latest commands from the command history.
166 history N COUNT.
168 Shows COUNT commands from the command history starting with Nth
169 command.
170 import FILE-NAME [replace] [nometa]
172 Import data from a flat dump file FILE-NAME. If the replace ar‐
173 gument is given, any records with the same keys as the already
174 existing ones will replace them. The nometa argument turns off
175 restoring meta-information from the dump file.
176 list List the contents of the database.
178 next [KEY]
180 Sequential access: fetch and display the next record. If the
181 KEY is given, the record following the one with this key will be
182 fetched.
183 open FILE
185 Open the database file FILE. If successful, any previously open
186 database is closed. Otherwise, if the operation fails, the cur‐
187 rently opened database remains unchanged.
188 This command takes additional information from the variables
190 open, lock, mmap, and sync. See the section VARIABLES, for a
191 detailed description of these.
192 quit Close the database and quit the utility.
194 reorganize
196 Reorganize the database.
197 set [VAR=VALUE...]
199 Without arguments, lists variables and their values. If argu‐
200 ments are specified, sets variables. Boolean variables can be
201 set by specifying variable name, optionally prefixed with no, to
202 set it to false.
203 snapshot FILE FILE
205 Analyzes two database snapshots and selects the most recent of
206 them. In case of error, prints a detailed diagnostics. Use
207 this command to manually recover from a crash. For details,
208 please refer to the chapter Crash Tolerance in the GDBM manual.
209 source FILE
211 Read commands from the given FILE.
212 status Print current program status.
214 store KEY DATA
216 Store the DATA with the given KEY in the database. If the KEY
217 already exists, its data will be replaced.
218 sync Synchronize the database file with the disk storage.
220 upgrade
222 Upgrade the database from the standard to the extended numsync
223 format.
224 unset VARIABLE...
226 Unsets listed variables.
227 version
229 Print the version of gdbm.
230
232 The define statement provides a mechanism for defining key or content
233 structures. It is similar to the C struct declaration:
234 define key|content { defnlist }
236 The defnlist is a comma-separated list of member declarations. Within
238 defnlist the newline character looses its special meaning as the com‐
239 mand terminator, so each declaration can appear on a separate line and
240 arbitrary number of comments can be inserted to document the defini‐
241 tion.
242 Each declaration has one of the following formats
244 type name
246 type name [N]
247 where type is a data type and name is the member name. The second for‐
249 mat defines the member name as an array of N elements of type.
250 The supported types are:
252 type meaning
254 char single byte (signed)
255 short signed short integer
256 ushort unsigned short integer
257 int signed integer
258 unsigned unsigned integer
259 uint ditto
260 long signed long integer
261 ulong unsigned long integer
262 llong signed long long integer
263 ullong unsigned long long integer
264 float a floating point number
265 double double-precision floating point number
266 string array of characters (see the NOTE below)
267 stringz null-terminated string of characters
268 The following alignment declarations can be used within defnlist:
270 offset N
272 The next member begins at offset N.
273 pad N Add N bytes of padding to the previous member.
275 For example:
277 define content {
279 int status,
280 pad 8,
281 char id[3],
282 stringz name
283 }
284 To define data consisting of a single data member, the following sim‐
286 plified construct can be used:
287 define key|content type
289 where type is one of the types discussed above.
291 NOTE: The string type can reasonably be used only if it is the last or
293 the only member of the data structure. That's because it provides no
294 information about the number of elements in the array, so it is inter‐
295 preted to contain all bytes up to the end of the datum.
296
298 confirm, boolean
299 Whether to ask for confirmation before certain destructive oper‐
300 ations, such as truncating the existing database. Default is
301 true.
302 ps1, string
304 Primary prompt string. Its value can contain conversion speci‐
305 fiers, consisting of the % character followed by another charac‐
306 ter. These specifiers are expanded in the resulting prompt as
307 follows:
308 Sequence Expansion
310 %f name of the db file
311 %p program name
312 %P package name (gdbm)
313 %_ horizontal space (ASCII 32)
314 %v program version
315 %% %
316 The default prompt is %p>%_.
318 ps2, string
320 Secondary prompt. See ps1 for a description of its value. This
321 prompt is displayed before reading the second and subsequent
322 lines of a multi-line command.
323 The default value is %_>%_.
325 delim1, string
327 A string used to delimit fields of a structured datum on output
328 (see the section DATA DEFINITIONS).
329 Default is , (a comma). This variable cannot be unset.
331 delim2, string
333 A string used to delimit array items when printing a structured
334 datum.
335 Default is , (a comma). This variable cannot be unset.
337 pager, string
339 The name and command line of the pager program to pipe output
340 to. This program is used in interactive mode when the estimated
341 number of output lines is greater then the number of lines on
342 your screen.
343 The default value is inherited from the environment variable
345 PAGER. Unsetting this variable disables paging.
346 quiet, boolean
348 Whether to display welcome banner at startup. This variable
349 should be set in a startup script file.
350 The following variables control how the database is opened:
352 cachesize, numeric
354 Sets the cache size. By default this variable is not set.
355 blocksize, numeric
357 Sets the block size. Unset by default.
358 open, string
360 Open mode. The following values are allowed:
361 newdb Truncate the database if it exists or create a new one.
363 Open it in read-write mode.
364 wrcreat or rw
366 Open the database in read-write mode. Create it if it
367 does not exist. This is the default.
368 reader or readonly
370 Open the database in read-only mode. Signal an error if
371 it does not exist.
372 filemode, octal
374 Sets the file mode for newly created database files. Default is
375 0644.
376 lock, boolean
378 Lock the database. This is the default.
379 mmap, boolean
381 Use memory mapping. This is the default.
382 coalesce, boolean
384 When set, this option causes adjacent free blocks to be merged
385 which allows for more efficient memory management at the expense
386 of a certain increase in CPU usage.
387 centfree, boolean
389 Enables central free block pool. This causes all free blocks of
390 space to be placed in the global pool, thereby speeding up the
391 allocation of data space.
392
394 gdbm_dump(1), gdbm_load(1), gdbm(3).
395
397 Report bugs to <bug-gdbm@gnu.org>.
398
400 Copyright © 2013-2021 Free Software Foundation, Inc
401 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/li‐
402 censes/gpl.html>
403 This is free software: you are free to change and redistribute it.
404 There is NO WARRANTY, to the extent permitted by law.
405GDBM August 1, 2021 GDBMTOOL(1)