doc/gdbmtool.1

   1 .\" This file is part of GDBM.  -*- nroff -*-
   2 .\" Copyright (C) 2013 Free Software Foundation, Inc.
   3 .\"
   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)
   7 .\" any later version.
   8 .\"
   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.
  13 .\"
  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"
  17 .SH NAME
  18 gdbmtool \- examine and modify a GDBM database
  19 .SH SYNOPSIS
  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]\
  26  [\fIDBFILE\fR]
  27 .sp
  28 \fBgdbmtool\fR [\fB\-Vh\fR] ][\fB\-\-help\fR] [\fB\-\-usage\fR] [\fB\-\-version\fR]
  29 .SH DESCRIPTION
  30 The
  31 .B gdbmtool
  32 utility allows you to view and modify an existing GDBM database or to
  33 create a new one.
  34 .PP
  35 The \fIDBFILE\fR argument supplies the name of the database to open.
  36 If not supplied, the default name
  37 .B junk.gdbm
  38 is used instead.
  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).
  42 .PP
  43 Unless the \fB\-N\fR (\fB\-\-norc\fR) option is given, after startup
  44 .B gdbmtool
  45 looks for file named
  46 .B .gdbmtoolrc
  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
  50 .B gdbmtool
  51 commands.
  52 .PP
  53 Then
  54 .B gdbmtool
  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.
  59 .PP
  60 The program terminates when the
  61 .B quit
  62 command is given, or end-of-file is detected on its standard input.
  63 .PP
  64 A
  65 .B gdbmtool
  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
  70 verb.
  71 .PP
  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:
  77 .sp
  78 .nf
  79 .ta 8n 20n
  80 .ul
  81         Escape  Expansion
  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)
  89         \\\\    Single slash
  90         \"      Double quote
  91 .fi
  92 .PP
  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.
  96 .SH OPTIONS
  97 .TP
  98 \fB\-b\fR, \fB\-\-block\-size\fR=\fISIZE\fR
  99 Set block size.
 100 .TP
 101 \fB\-c\fR, \fB\-\-cache\-size\fR=\fISIZE\fR
 102 Set cache size.
 103 .TP
 104 \fB\-f\fR, \fB\-\-file\fR=\fIFILE\fR
 105 Read commands from \fIFILE\fR, instead of from the standard input.
 106 .TP
 107 \fB\-l\fR, \fB\-\-no\-lock\fR
 108 Disable file locking.
 109 .TP
 110 \fB\-m\fR, \fB\-\-no\-mmap\fR
 111 Do not use
 112 .BR mmap (2).
 113 .TP
 114 \fB\-n\fR, \fB\-\-newdb\fR
 115 Create the database, truncating it if it already exists.
 116 .TP
 117 \fB\-q\fR, \fB\-\-quiet\fR
 118 Don't print initial banner.
 119 .TP
 120 \fB\-r\fR, \fB\-\-read\-only\fR
 121 Open database in read-only mode.
 122 .TP
 123 \fB\-s\fR, \fB\-\-synchronize\fR
 124 Synchronize to disk after each write.
 125 .TP
 126 \fB\-h\fR, \fB\-\-help\fR
 127 Print a short usage summary.
 128 .TP
 129 \fB\-\-usage\fR
 130 Print a list of available options.
 131 .TP
 132 \fB\-V\fR, \fB\-\-version\fR
 133 Print program version
 134 .SH SHELL COMMANDS
 135 .TP
 136 .BR avail
 137 Print the
 138 .BR "avail list" .
 139 .TP
 140 \fBbucket\fR \fINUM\fR
 141 Print the bucket number \fINUM\fR and set is as the current one.
 142 .TP
 143 .BR cache
 144 Print the bucket cache.
 145 .TP
 146 .B close
 147 Close the currently open database.
 148 .TP
 149 .BR count
 150 Print the number of entries in the database.
 151 .TP
 152 .BR current
 153 Print the current bucket.
 154 .TP
 155 \fBdelete\fR \fIKEY\fR
 156 Delete record with the given \fIKEY\fR.
 157 .TP
 158 .BR dir
 159 Print hash directory.
 160 .TP
 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
 163 .BR gdbm_dump (1).
 164
 165 This command will not overwrite an existing file, unless the
 166 .B truncate
 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.
 169 .TP
 170 \fBfetch\fR \fIKEY\fR
 171 Fetch and display the record with the given \fIKEY\fR.
 172 .TP
 173 .BR first
 174 Fetch and display the first record in the database.  Subsequent
 175 records can be fetched using the
 176 .B next
 177 command (see below).
 178 .TP
 179 \fBhash\fR \fIKEY\fR
 180 Compute and display the hash value for the given \fIKEY\fR.
 181 .TP
 182 .BR header
 183 Print file header.
 184 .TP
 185 .BR help " or " ?
 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.
 189 .TP
 190 \fBimport\fR \fIFILE\-NAME\fR [\fBreplace\fR] [\fBnometa\fR]
 191 Import data from a flat dump file \fIFILE\-NAME\fR.
 192 If the
 193 .B replace
 194 argument is given, any records with the same keys as the already
 195 existing ones will replace them.  The
 196 .B nometa
 197 argument turns off restoring meta-information from the dump file.
 198 .TP
 199 \fBlist\fR
 200 List the contents of the database.
 201 .TP
 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.
 205 .TP
 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.
 210
 211 This command takes additional information from the variables
 212 .BR open ,
 213 .BR lock ,
 214 .BR mmap ", and"
 215 .BR sync .
 216 See the section
 217 .BR VARIABLES ,
 218 for a detailed description of these.
 219 .TP
 220 .B quit
 221 Close the database and quit the utility.
 222 .TP
 223 .BR reorganize
 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.
 229 .TP
 230 \fBsource\fR \fIFILE\fR
 231 Read commands from the given \fIFILE\fR.
 232 .TP
 233 .BR status
 234 Print current program status.
 235 .TP
 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.
 239 .TP
 240 \fBunset\fR \fIVARIABLE\fR...
 241 Unsets listed variables.
 242 .TP
 243 .BR version
 244 Print the version of
 245 .BR gdbm .
 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
 249 declaration:
 250 .sp
 251 .nf
 252 .in +4
 253 \fBdefine\fR \fBkey\fR|\fBcontent\fR \fB{\fR \fIdefnlist\fR \fB}\fR
 254 .in
 255 .fi
 256 .PP
 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.
 262 .PP
 263 Each declaration has one of the following formats
 264 .sp
 265 .nf
 266 .in +4
 267 \fItype\fR \fIname\fR
 268 \fItype\fR \fIname\fR \fB[\fIN\fB]\fR
 269 .in
 270 .fi
 271 .sp
 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.
 275 .PP
 276 The supported types are:
 277 .sp
 278 .nf
 279 .ta 8n 20n
 280 .ul
 281         type    meaning
 282         char    single byte (signed)
 283         short   signed short integer
 284         ushort  unsigned short integer
 285         int     signed integer
 286         unsigned        unsigned integer
 287         uint    ditto
 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
 296 .fi
 297 .PP
 298 The following alignment declarations can be used within \fIdefnlist\fR:
 299 .TP
 300 \fBoffset\fR \fIN\fR
 301 The next member begins at offset \fIN\fR.
 302 .TP
 303 \fBpad\fR \fIN\fR
 304 Add \fIN\fR bytes of padding to the previous member.
 305 .PP
 306 For example:
 307 .sp
 308 .nf
 309 .in +4
 310 \fBdefine content {
 311         int status,
 312         pad 8,
 313         char id[3],
 314         stringz name
 315 }\fR
 316 .fi
 317 .PP
 318 To define data consisting of a single data member, the following
 319 simplified construct can be used:
 320 .sp
 321 .nf
 322 .in +4
 323 \fBdefine\fR \fBkey\fR|\fBcontent\fR \fItype\fR
 324 .fi
 325 .PP
 326 where \fItype\fR is one of the types discussed above.
 327 .PP
 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.
 332 .SH VARIABLES
 333 .TP
 334 .BR confirm ", boolean"
 335 Whether to ask for confirmation before certain destructive operations,
 336 such as truncating the existing database.  Default is
 337 .BR true .
 338 .TP
 339 .BR ps1 ", string"
 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
 343 follows:
 344 .sp
 345 .nf
 346 .ta 8n 20n
 347 .ul
 348         Sequence        Expansion
 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
 354         \fB%%\fR        \fB%\fR
 355 .fi
 356 .sp
 357 The default prompt is \fB%p>%_\fR.
 358 .TP
 359 .BR ps2 ", string"
 360 Secondary prompt.  See
 361 .B ps1
 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.
 365
 366 The default value is \fB%_>%_\fR.
 367 .TP
 368 .BR delim1 ", string"
 369 A string used to delimit fields of a structured datum on output
 370 (see the section \fBDATA DEFINITIONS\fR).
 371
 372 Default is \fB,\fR (a comma).  This variable cannot be unset.
 373 .TP
 374 .BR delim2 ", string"
 375 A string used to delimit array items when printing a structured datum.
 376
 377 Default is \fB,\fR (a comma).  This variable cannot be unset.
 378 .TP
 379 .BR pager ", string"
 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.
 383
 384 The default value is inherited from the environment variable
 385 \fBPAGER\fR.  Unsetting this variable disables paging.
 386 .TP
 387 .BR quiet ", boolean"
 388 Whether to display welcome banner at startup.  This variable should
 389 be set in a startup script file.
 390 .PP
 391 The following variables control how the database is opened:
 392 .TP
 393 .BR cachesize ", numeric"
 394 Sets the cache size.  By default this variable is not set.
 395 .TP
 396 .BR blocksize ", numeric"
 397 Sets the block size.  Unset by default.
 398 .TP
 399 .BR open ", string"
 400 Open mode.  The following values are allowed:
 401 .RS 7
 402 .TP
 403 .BR newdb
 404 Truncate the database if it exists or create a new one.  Open it in
 405 read-write mode.
 406 .TP
 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.
 410 .TP
 411 .BR reader " or " readonly
 412 Open the database in read-only mode.  Signal an error if it does not
 413 exist.
 414 .RE
 415 .TP
 416 .BR lock ", boolean"
 417 Lock the database.  This is the default.
 418 .TP
 419 .BR mmap ", boolean"
 420 Use memory mapping.  This is the default.
 421
 422 .SH "SEE ALSO"
 423 .BR gdbm_dump (1),
 424 .BR gdbm_load (1),
 425 .BR gdbm (3).
 426 .SH "REPORTING BUGS"
 427 Report bugs to <bug\-gdbm@gnu.org>.
 428 .SH COPYRIGHT
 429 Copyright \(co 2013 Free Software Foundation, Inc
 430 .br
 431 .na
 432 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
 433 .br
 434 .ad
 435 This is free software: you are free to change and redistribute it.
 436 There is NO WARRANTY, to the extent permitted by law.
 437 .\" Local variables:
 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
 443 .\" end: