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
55 unprintable characters it must be enclosed in double quotes. Within
56 double quotes the usual escape sequences are understood, as shown in
57 the 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 export FILE-NAME [truncate] [binary|ascii]
132 Export the database to the flat file FILE-NAME. This is equiva‐
133 lent to gdbm_dump(1).
134 This command will not overwrite an existing file, unless the
136 truncate parameter is also given. Another optional parameter
137 determines the type of the dump (*note Flat files::). By
138 default, ASCII dump will be created.
139 fetch KEY
141 Fetch and display the record with the given KEY.
142 first Fetch and display the first record in the database. Subsequent
144 records can be fetched using the next command (see below).
145 hash KEY
147 Compute and display the hash value for the given KEY.
148 header Print file header.
150 help or ?
152 Print a concise command summary, showing each command letter and
153 verb with its parameters and a short description of what it
154 does. Optional arguments are enclosed in square brackets.
155 history
157 Shows the command history list with line numbers. This command
158 is available only if the program was compiled with GNU Readline.
159 history COUNT.
161 Shows COUNT latest commands from the command history.
162 history N COUNT.
164 Shows COUNT commands from the command history starting with Nth
165 command.
166 import FILE-NAME [replace] [nometa]
168 Import data from a flat dump file FILE-NAME. If the replace
169 argument is given, any records with the same keys as the already
170 existing ones will replace them. The nometa argument turns off
171 restoring meta-information from the dump file.
172 list List the contents of the database.
174 next [KEY]
176 Sequential access: fetch and display the next record. If the
177 KEY is given, the record following the one with this key will be
178 fetched.
179 open FILE
181 Open the database file FILE. If successful, any previously open
182 database is closed. Otherwise, if the operation fails, the cur‐
183 rently opened database remains unchanged.
184 This command takes additional information from the variables
186 open, lock, mmap, and sync. See the section VARIABLES, for a
187 detailed description of these.
188 quit Close the database and quit the utility.
190 reorganize
192 Reorganize the database.
193 set [VAR=VALUE...]
195 Without arguments, lists variables and their values. If argu‐
196 ments are specified, sets variables. Boolean variables can be
197 set by specifying variable name, optionally prefixed with no, to
198 set it to false.
199 source FILE
201 Read commands from the given FILE.
202 status Print current program status.
204 store KEY DATA
206 Store the DATA with the given KEY in the database. If the KEY
207 already exists, its data will be replaced.
208 unset VARIABLE...
210 Unsets listed variables.
211 version
213 Print the version of gdbm.
214
216 The define statement provides a mechanism for defining key or content
217 structures. It is similar to the C struct declaration:
218 define key|content { defnlist }
220 The defnlist is a comma-separated list of member declarations. Within
222 defnlist the newline character looses its special meaning as the com‐
223 mand terminator, so each declaration can appear on a separate line and
224 arbitrary number of comments can be inserted to document the defini‐
225 tion.
226 Each declaration has one of the following formats
228 type name
230 type name [N]
231 where type is a data type and name is the member name. The second for‐
233 mat defines the member name as an array of N elements of type.
234 The supported types are:
236 type meaning
238 char single byte (signed)
239 short signed short integer
240 ushort unsigned short integer
241 int signed integer
242 unsigned unsigned integer
243 uint ditto
244 long signed long integer
245 ulong unsigned long integer
246 llong signed long long integer
247 ullong unsigned long long integer
248 float a floating point number
249 double double-precision floating point number
250 string array of characters (see the NOTE below)
251 stringz null-terminated string of characters
252 The following alignment declarations can be used within defnlist:
254 offset N
256 The next member begins at offset N.
257 pad N Add N bytes of padding to the previous member.
259 For example:
261 define content {
263 int status,
264 pad 8,
265 char id[3],
266 stringz name
267 }
268 To define data consisting of a single data member, the following sim‐
270 plified construct can be used:
271 define key|content type
273 where type is one of the types discussed above.
275 NOTE: The string type can reasonably be used only if it is the last or
277 the only member of the data structure. That's because it provides no
278 information about the number of elements in the array, so it is inter‐
279 preted to contain all bytes up to the end of the datum.
280
282 confirm, boolean
283 Whether to ask for confirmation before certain destructive oper‐
284 ations, such as truncating the existing database. Default is
285 true.
286 ps1, string
288 Primary prompt string. Its value can contain conversion speci‐
289 fiers, consisting of the % character followed by another charac‐
290 ter. These specifiers are expanded in the resulting prompt as
291 follows:
292 Sequence Expansion
294 %f name of the db file
295 %p program name
296 %P package name (gdbm)
297 %_ horizontal space (ASCII 32)
298 %v program version
299 %% %
300 The default prompt is %p>%_.
302 ps2, string
304 Secondary prompt. See ps1 for a description of its value. This
305 prompt is displayed before reading the second and subsequent
306 lines of a multi-line command.
307 The default value is %_>%_.
309 delim1, string
311 A string used to delimit fields of a structured datum on output
312 (see the section DATA DEFINITIONS).
313 Default is , (a comma). This variable cannot be unset.
315 delim2, string
317 A string used to delimit array items when printing a structured
318 datum.
319 Default is , (a comma). This variable cannot be unset.
321 pager, string
323 The name and command line of the pager program to pipe output
324 to. This program is used in interactive mode when the estimated
325 number of output lines is greater then the number of lines on
326 your screen.
327 The default value is inherited from the environment variable
329 PAGER. Unsetting this variable disables paging.
330 quiet, boolean
332 Whether to display welcome banner at startup. This variable
333 should be set in a startup script file.
334 The following variables control how the database is opened:
336 cachesize, numeric
338 Sets the cache size. By default this variable is not set.
339 blocksize, numeric
341 Sets the block size. Unset by default.
342 open, string
344 Open mode. The following values are allowed:
345 newdb Truncate the database if it exists or create a new one.
347 Open it in read-write mode.
348 wrcreat or rw
350 Open the database in read-write mode. Create it if it
351 does not exist. This is the default.
352 reader or readonly
354 Open the database in read-only mode. Signal an error if
355 it does not exist.
356 filemode, octal
358 Sets the file mode for newly created database files. Default is
359 0644.
360 lock, boolean
362 Lock the database. This is the default.
363 mmap, boolean
365 Use memory mapping. This is the default.
366 coalesce, boolean
368 When set, this option causes adjacent free blocks to be merged
369 which allows for more efficient memory management at the expense
370 of a certain increase in CPU usage.
371 centfree, boolean
373 Enables central free block pool. This causes all free blocks of
374 space to be placed in the global pool, thereby speeding up the
375 allocation of data space.
376
378 gdbm_dump(1), gdbm_load(1), gdbm(3).
379
381 Report bugs to <bug-gdbm@gnu.org>.
382
384 Copyright © 2013-2018 Free Software Foundation, Inc
385 License GPLv3+: GNU GPL version 3 or later
386 <http://gnu.org/licenses/gpl.html>
387 This is free software: you are free to change and redistribute it.
388 There is NO WARRANTY, to the extent permitted by law.
389GDBM June 27, 2018 GDBMTOOL(1)