1GDBMTOOL(1)                   GDBM User Reference                  GDBMTOOL(1)
2
3
4

NAME

6       gdbmtool - examine and modify a GDBM database
7

SYNOPSIS

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
14       gdbmtool [-Vh] [--help] [--usage] [--version]
15

DESCRIPTION

17       The gdbmtool utility allows you to view and  modify  an  existing  GDBM
18       database or to create a new one.
19
20       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
26       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
32       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
37       The program terminates when the quit command is given,  or  end-of-file
38       is detected on its standard input.
39
40       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
44       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
48       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
53       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
59               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
69
70       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

OPTIONS

75       -b, --block-size=SIZE
76              Set block size.
77
78       -c, --cache-size=SIZE
79              Set cache size.
80
81       -f, --file=FILE
82              Read commands from FILE, instead of from the standard input.
83
84       -l, --no-lock
85              Disable file locking.
86
87       -m, --no-mmap
88              Do not use mmap(2).
89
90       -n, --newdb
91              Create the database, truncating it if it already exists.
92
93       -q, --quiet
94              Don't print initial banner.
95
96       -r, --read-only
97              Open database in read-only mode.
98
99       -s, --synchronize
100              Synchronize to disk after each write.
101
102       -h, --help
103              Print a short usage summary.
104
105       --usage
106              Print a list of available options.
107
108       -V, --version
109              Print program version
110

SHELL COMMANDS

112       avail  Print the avail list.
113
114       bucket NUM
115              Print the bucket number NUM and set is as the current one.
116
117       cache  Print the bucket cache.
118
119       close  Close the currently open database.
120
121       count  Print the number of entries in the database.
122
123       current
124              Print the current bucket.
125
126       delete KEY
127              Delete record with the given KEY.
128
129       dir    Print hash directory.
130
131       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
135              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
140       fetch KEY
141              Fetch and display the record with the given KEY.
142
143       first  Fetch and display the first record in the database.   Subsequent
144              records can be fetched using the next command (see below).
145
146       hash KEY
147              Compute and display the hash value for the given KEY.
148
149       header Print file header.
150
151       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
156       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
160       history COUNT.
161              Shows COUNT latest commands from the command history.
162
163       history N COUNT.
164              Shows COUNT commands from the command history starting with  Nth
165              command.
166
167       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
173       list   List the contents of the database.
174
175       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
180       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
185              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
189       quit   Close the database and quit the utility.
190
191       reorganize
192              Reorganize the database.
193
194       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
200       source FILE
201              Read commands from the given FILE.
202
203       status Print current program status.
204
205       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
209       unset VARIABLE...
210              Unsets listed variables.
211
212       version
213              Print the version of gdbm.
214

DATA DEFINITIONS

216       The define statement provides a mechanism for defining key  or  content
217       structures.  It is similar to the C struct declaration:
218
219           define key|content { defnlist }
220
221       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
227       Each declaration has one of the following formats
228
229           type name
230           type name [N]
231
232       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
235       The supported types are:
236
237               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
253       The following alignment declarations can be used within defnlist:
254
255       offset N
256              The next member begins at offset N.
257
258       pad N  Add N bytes of padding to the previous member.
259
260       For example:
261
262           define content {
263                   int status,
264                   pad 8,
265                   char id[3],
266                   stringz name
267           }
268
269       To define data consisting of a single data member, the  following  sim‐
270       plified construct can be used:
271
272           define key|content type
273
274       where type is one of the types discussed above.
275
276       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

VARIABLES

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
287       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
293                      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
301              The default prompt is %p>%_.
302
303       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
308              The default value is %_>%_.
309
310       delim1, string
311              A  string used to delimit fields of a structured datum on output
312              (see the section DATA DEFINITIONS).
313
314              Default is , (a comma).  This variable cannot be unset.
315
316       delim2, string
317              A string used to delimit array items when printing a  structured
318              datum.
319
320              Default is , (a comma).  This variable cannot be unset.
321
322       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
328              The default value is inherited  from  the  environment  variable
329              PAGER.  Unsetting this variable disables paging.
330
331       quiet, boolean
332              Whether  to  display  welcome  banner at startup.  This variable
333              should be set in a startup script file.
334
335       The following variables control how the database is opened:
336
337       cachesize, numeric
338              Sets the cache size.  By default this variable is not set.
339
340       blocksize, numeric
341              Sets the block size.  Unset by default.
342
343       open, string
344              Open mode.  The following values are allowed:
345
346              newdb  Truncate the database if it exists or create a  new  one.
347                     Open it in read-write mode.
348
349              wrcreat or rw
350                     Open  the  database  in read-write mode.  Create it if it
351                     does not exist.  This is the default.
352
353              reader or readonly
354                     Open the database in read-only mode.  Signal an error  if
355                     it does not exist.
356
357       filemode, octal
358              Sets  the file mode for newly created database files. Default is
359              0644.
360
361       lock, boolean
362              Lock the database.  This is the default.
363
364       mmap, boolean
365              Use memory mapping.  This is the default.
366
367       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
372       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

SEE ALSO

378       gdbm_dump(1), gdbm_load(1), gdbm(3).
379

REPORTING BUGS

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.
389
390
391
392GDBM                             June 27, 2018                     GDBMTOOL(1)
Impressum