GDBM manual (split by section):   Section:   Chapter:FastBack: gdbmtool   Up: gdbmtool   FastForward: gdbm_dump   Contents: Table of ContentsIndex: Index

21.2 gdbmtool interactive mode

After successful startup, gdbmtool starts a loop, in which it reads commands from the standard input, executes them and prints results on the standard output. If the standard input is attached to a console, gdbmtool runs in interactive mode, which is indicated by its prompt:

gdbmtool> _

The utility finishes when it reads the ‘quit’ command (see below) or detects end-of-file on its standard input, whichever occurs first.

A gdbmtool command consists of a command verb, optionally followed by arguments, separated by any amount of white space and terminated with a newline or semicolon. A command verb can be entered either in full or in an abbreviated form, as long as that abbreviation does not match any other verb. For example, ‘co’ can be used instead of ‘count’ and ‘ca’ instead of ‘cache’.

Any sequence of non-whitespace characters appearing after the command verb forms an argument. If the argument contains whitespace or unprintable characters it must be enclosed in double quotes. Within double quotes the usual escape sequences are understood, as shown in the table below:

SequenceReplaced with
\aAudible bell character (ASCII 7)
\bBackspace character (ASCII 8)
\fForm-feed character (ASCII 12)
\nNewline character (ASCII 10)
\rCarriage return character (ASCII 13)
\tHorizontal tabulation character (ASCII 9)
\vVertical tabulation character (ASCII 11)
\\Single slash
\"Double quote

Table 21.1: Backslash escapes

In addition, a backslash immediately followed by the end-of-line character effectively removes that character, allowing to split long arguments over several input lines.

Command parameters may be optional or mandatory. If the number of actual arguments is less than the number of mandatory parameters, gdbmtool will prompt you to supply missing arguments. For example, the ‘store’ command takes two mandatory parameters, so if you invoked it with no arguments, you would be prompted twice to supply the necessary data, as shown in example below:

gdbmtool> store
key? three
data? 3

However, such prompting is possible only in interactive mode. In non-interactive mode (e.g. when running a script), all arguments must be supplied with each command, otherwise gdbmtool will report an error and exit immediately.

If the package is compiled with GNU Readline, the input line can be edited (see Command Line Editing in GNU Readline Library).

21.2.1 Shell Variables

A number of gdbmtool parameters is kept in its internal variables.

gdbmtool variable: bool confirm

Whether to ask for confirmation before certain destructive operations, such as truncating the existing database.

Default is ‘true’.

gdbmtool variable: string ps1

Primary prompt string. Its value can contain conversion specifiers, consisting of the ‘%’ character followed by another character. These specifiers are expanded in the resulting prompt as follows:

SequenceExpansion
%fname of the current database file
%pprogram invocation name
%Ppackage name (‘GDBM’)
%vprogram version
%_single space character
%%%

The default value is ‘%p>%_’, i.e. the program name, followed by a “greater than” sign, followed by a single space.

gdbmtool variable: string ps2

Secondary prompt. See ‘ps1’ for a description of its value. This prompt is displayed before reading the second and subsequent lines of a multi-line command.

The default value is ‘%_>%_’.

gdbmtool variable: string delim1

A string used to delimit fields of a structured datum on output (see definitions).

Default is ‘,’ (a comma). This variable cannot be unset.

gdbmtool variable: string delim2

A string used to delimit array items when printing a structured datum (see definitions).

Default is ‘,’ (a comma). This variable cannot be unset.

gdbmtool variable: string pager

The name and command line of the pager program to pipe output to. This program is used in interactive mode when the estimated number of output lines is greater then the number of lines on your screen.

The default value is inherited from the environment variable PAGER. Unsetting this variable disables paging.

gdbmtool variable: bool quiet

Whether to display a welcome banner at startup. This variable should be set in a startup script file (see startup files). See -q option.

The following variables control how the database is opened:

gdbmtool variable: numeric blocksize

Sets the block size. See block_size. Unset by default.

gdbmtool variable: numeric cachesize

Sets the cache size. See GDBM_SETCACHESIZE. By default this variable is not set.

gdbmtool variable: string open

Open mode. The following values are allowed:

newdb

Truncate the database if it exists or create a new one. Open it in read-write mode.

Technically, this sets the ‘GDBM_NEWDB’ flag in call to ‘gdbm_open’. See GDBM_NEWDB.

wrcreat
rw

Open the database in read-write mode. Create it if it does not exist. This is the default.

Technically speaking, it sets the ‘GDBM_WRCREAT’ flag in call to gdbm_open. See GDBM_WRCREAT.

reader
readonly

Open the database in read-only mode. Signal an error if it does not exist.

This sets the ‘GDBM_READER’ flag (see GDBM_READER).

Attempting to set any other value or to unset this variable produces an error.

gdbmtool variable: number filemode

File mode (in octal) for creating new database files and database dumps.

gdbmtool variable: bool lock

Lock the database. This is the default.

Setting this variable to false or unsetting it results in passing ‘GDBM_NOLOCK’ flag to gdbm_open (see GDBM_NOLOCK).

gdbmtool variable: bool mmap

Use memory mapping. This is the default.

Setting this variable to false or unsetting it results in passing ‘GDBM_NOMMAP’ flag to gdbm_open (see GDBM_NOMMAP).

gdbmtool variable: bool sync

Flush all database writes on disk immediately. Default is false. See GDBM_SYNC.

gdbmtool variable: bool coalesce

Enables the coalesce mode, i.e. merging of the freed blocks of GDBM files with entries in available block lists. This provides for effective memory management at the cost of slight increase in execution time when calling gdbm_delete. See GDBM_SETCOALESCEBLKS.

This variable affects the open command and should be set before invoking it.

gdbmtool variable: bool centfree

Set to ‘true’, enables the use of central free block pool in newly opened databases. See GDBM_SETCENTFREE.

This variable affects the open command and should be set before invoking it.

The following commands are used to list or modify the variables:

command verb: set [assignments]

When used without arguments, lists all variables and their values. Unset variables are shown after a comment sign (‘#’). For string and numeric variables, values are shown after an equals sign. For boolean variables, only the variable name is displayed if the variable is ‘true’. If it is ‘false’, its name is prefixed with ‘no’.

For example:

ps1="%p>%_"
ps2="%_>%_"
delim1=","
delim2=","
confirm
# cachesize is unset
# blocksize is unset
open="wrcreat"
lock
mmap
nosync
pager="less"
# quiet is unset

If used with arguments, the set command alters the specified variables. In this case, arguments are variable assignments in the form ‘name=value’. For boolean variables, the value is interpreted as follows: if it is numeric, ‘0’ stands for ‘false’, any non-zero value stands for ‘true’. Otherwise, the values ‘on’, ‘true’, and ‘yes’ denote ‘true’, and ‘off’, ‘false’, ‘no’ stand for ‘false’. Alternatively, only the name of a boolean variable can be supplied to set it to ‘true’, and its name prefixed with ‘no’ can be used to set it to false. For example, the following command sets the ‘delim2’ variable to ‘;’ and the ‘confirm’ variable to ‘false’:

set delim2=";" noconfirm
command verb: unset variables

Unsets the listed variables. The effect of unsetting depends on the variable. Unless explicitly described in the discussion of the variables above, unsetting a boolean variable is equivalent to setting it to ‘false’. Unsetting a string variable is equivalent to assigning it an empty string.

21.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: 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

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

This command takes additional information from the following variables:

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’.

filemode

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

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

command verb: quit

Close the database and quit the utility.

command verb: recover [options]

Run database recovery. 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: 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: version

Print the version of gdbm.

21.2.3 Data Definitions

GDBM databases are able to keep data of any type, both in the key and in the content part of a record. Quite often these data are structured, i.e. they consist of several fields of various types. Gdbmtool provides a mechanism for handling such kind of records.

The define command defines a record structure. The general syntax is:

define what definition

where what is ‘key’ to defining the structure of key data and ‘content’ to define the structure of the content records.

The definition can be of two distinct formats. In the simplest case it is a single data type. For example,

define content int

defines content records consisting of a single integer field. Supported data types are:

char

Single byte (signed).

short

Signed short integer.

ushort

Unsigned short integer.

int

Signed integer.

unsigned
uint

Unsigned integer.

long

Signed long integer.

ulong

Unsigned long integer.

llong

Signed long long integer.

ullong

Unsigned long long integer.

float

A floating point number.

double

Double-precision floating point number.

string

Array of bytes.

stringz

Null-terminated string, trailing null being part of the string.

All numeric data types (integer as well as floating point) have the same respective widths as in C language on the host where the database file resides.

The ‘string’ and ‘stringz’ are special. Both define a string of bytes, similar to ‘char x[]’ in C. The former defines an array of bytes, the latter - a null-terminated string. This makes a difference, in particular, when the string is the only part of datum. Consider the following two definitions:

  1. define key string
  2. define key stringz

Now, suppose we want to store the string "ab" in the key. Using the definition (1), the dptr member of GDBM datum will contain two bytes: ‘a’, and ‘b’. Consequently, the dsize member will have the value 2. Using the definition (2), the dptr member will contain three bytes: ‘a’, ‘b’, and ASCII 0. The dsize member will have the value 3.

The definition (1) is the default for both key and content.

The second form of the define statement is similar to the C struct statement and allows for defining structural data. In this form, the definition part is a comma-separated list of data types and variables enclosed in curly braces. In contrast to the rest of gdbm commands, this command is inherently multiline and is terminated with the closing curly brace. For example:

define content {
        int status,
        pad 8,
        char id[3],
        string name
}        

This defines a structure consisting of three members: an integer status, an array of 8 bytes id, and a null-terminated string name. Notice the pad statement: it allows to introduce padding between structure members. Another useful statement is offset: it specifies that the member following it begins at the given offset in the structure. Assuming the size of int is 8 bytes, the above definition can also be written as

define content {
        int status,
        offset 16,
        char id[3],
        string name
}        

NOTE: The ‘string’ type can reasonably be used only if it is the last or the only member of the data structure. That’s because it provides no information about the number of elements in the array, so it is interpreted to contain all bytes up to the end of the datum.

When displaying the structured data, gdbmtool precedes each value with the corresponding field name and delimits parts of the structure with the string defined in the ‘delim1’ variable (see variables). Array elements are delimited using the string from ‘delim2’. For example:

gdbmtool> fetch foo
status=2,id={ a, u, x },name="quux"

To supply a structured datum as an argument to a gdbmtool command, use the same notation, but without field names, e.g.:

gdbmtool> hash { 2, {a,u,x}, "quux" }
hash value = 13089969.

21.2.4 Startup Files

Upon startup gdbmtool looks for a file named ‘.gdbmtoolrc’ first in the current working directory and, if not found, in the home directory of the user who started the command.

If found, this file is read and interpreted as a list of gdbmtool commands. This allows you to customize the program behavior.

Following is an example startup file which disables the welcome banner, sets command line prompt to contain the name of the database file in parentheses and defines the structure of the database content records:

set quiet
set ps1="(%f) "
define key stringz
define content {
        int time,
        pad 4,
        int status
}

GDBM manual (split by section):   Section:   Chapter:FastBack: gdbmtool   Up: shell   FastForward: gdbm_dump   Contents: Table of ContentsIndex: Index