24.2.2 Gdbmtool Commands

command verb: avail

Print the avail list.

command verb: bucket num

Print the bucket number num and set it as the current one.

command verb: cache

Print the bucket cache.

command verb: close

Close the currently open database.

command verb: count

Print the number of entries in the database.

command verb: current

Print the current bucket.

command verb: debug [[+-]token...]

If GDBM is configured with additional debugging, this statement queries or sets GDBM internal debugging level. This is intended for debugging and testing purposes and requires good knowledge of GDBM internals. The use of this command is not recommended.

command verb: delete key

Delete record with the given key

command verb: dir

Print hash directory.

command verb: downgrade

Downgrade the database from extended to the standard database format. See Numsync.

command verb: export file-name [truncate] [binary|ascii]

Export the database to the flat file file-name. See Flat files, for a description of the flat file format and its purposes. This command will not overwrite an existing file, unless the ‘truncate’ parameter is also given. Another optional argument determines the type of the dump (see Flat files). By default, ASCII dump is created.

The global variable filemode specifies the permissions to use for the created output file.

command verb: fetch key

Fetch and display the record with the given key.

command verb: first

Fetch and display the first record in the database. Subsequent records can be fetched using the next command (see below). See Sequential, for more information on sequential access.

command verb: hash key

Compute and display the hash value for the given key.

command verb: header

Print file header.

command verb: help

command verb: ?

Print a concise command summary, showing each command verb with its parameters and a short description of what it does. Optional arguments are enclosed in square brackets.

command verb: import file-name [replace] [nometa]

Import data from a flat dump file file-name (see Flat files). If the word ‘replace’ is given as an argument, any records with the same keys as the already existing ones will replace them. The word ‘nometa’ turns off restoring meta-information from the dump file.

command verb: history

command verb: history count

command verb: history n count

Shows the command history list with line numbers. When used without arguments, shows entire history. When used with one argument, displays count last commands from the history. With two arguments, displays count commands starting from nth command. Command numbering starts with 1.

This command is available only if GDBM was compiled with GNU Readline. The history is saved in file .gdbmtool_history in the user’s home directory. If this file exists upon startup, it is read to populate the history. Thus, command history is preserved between gdbmtool invocations.

command verb: list

List the contents of the database.

command verb: next [key]

Sequential access: fetch and display the next record. If the key is given, the record following the one with this key will be fetched.

Issuing several next commands in row is rather common. A shortcut is provided to facilitate such use: if the last entered command was next, hitting the Enter key repeats it without arguments.

See also first, above.

See Sequential, for more information on sequential access.

command verb: open filename

command verb: open

Open the database file filename. If used without arguments, the database name is taken from the variable filename.

If successful, any previously open database is closed and the filename variable is updated. Otherwise, if the operation fails, the currently opened database remains unchanged.

This command takes additional information from the following variables:

filename

Name of the database to open, if no argument is given.

fd

File descriptor to use. If set, this must be an open file descriptor referring to a valid database file. The database will be opened using gdbm_fd_open (see gdbm_fd_open). The file descriptor will be closed and the variable unset upon closing the database.

filemode

Specifies the permissions to use in case a new file is created.

open

The database access mode. See The open variable, for a list of its values.

lock

Whether or not to lock the database. Default is on.

mmap

Use the memory mapping. Default is on.

sync

Synchronize after each write. Default is off.

See open parameters, for a detailed description of these variables.

command verb: perror [code]

Describe the given GDBM error code.

The description occupies one or two lines. The second line is present if the system error number should be checked when handling this code. In this case, the second line states ‘Examine errno’.

If code is omitted, the latest error that occurred in the current database is described. Second line of the output (if present), contains description of the latest system error.

Example:

gdbmtool> perror 3
GDBM error code 3: "File open error"
Examine errno.

command verb: quit

Close the database and quit the utility.

command verb: recover [options]

Recover the database from structural inconsistencies. See Database consistency.

The following options are understood:

backup

Create a backup copy of the original database.

max-failed-buckets=n

Abort recovery process if n buckets could not be recovered.

max-failed-keys=n

Abort recovery process if n keys could not be recovered.

max-failures=n

Abort recovery process after n failures. A failure in this context is either a key or a bucket that failed to be recovered.

summary

Print the recovery statistics at the end of the run. The statistics includes number of successfully recovered, failed and duplicate keys and the number of recovered and failed buckets.

verbose

Verbosely list each error encountered.

command verb: reorganize

Reorganize the database (see Reorganization).

command verb: shell command

command verb: ! command

Execute command via current shell. If command is empty, shell is started without additional arguments. Otherwise, it is run as ‘$SHELL -c command’.

For convenience, command is not parsed as gdbmtool command line. It is passed to the shell verbatim. It can include newline characters if these are preceded by a backslash or appear within singly or doubly quoted strings.

When using ! form, be sure to separate it from command by whitespace, otherwise it will be treated as readline event specifier.

command verb: snapshot filename filename

Analyze two snapshot files and select the most recent of them. In case of error, display a detailed diagnostics and meta-information of both snapshots.

See Manual crash recovery, for a detailed discussion.

command verb: source filename

Read gdbmtool commands from the file filename.

command verb: status

Print current program status. The following example shows the information displayed:

Database file: junk.gdbm
Database is open
define key string
define content string

The two define strings show the defined formats for key and content data. See definitions, for a detailed discussion of their meaning.

command verb: store key data

Store the data with key in the database. If key already exists, its data will be replaced.

command verb: sync

Synchronize the database with the disk storage (see Sync).

command verb: upgrade

Upgrade the database from standard to extended database format. See Numsync.

command verb: version

Print the version of gdbm.