summaryrefslogtreecommitdiffabout
path: root/doc
authorSergey Poznyakoff <gray@gnu.org.ua>2013-05-16 15:32:45 (GMT)
committer Sergey Poznyakoff <gray@gnu.org.ua>2013-05-16 15:32:45 (GMT)
commit979486e1b46a894fc9de2abe6eb8985536a5013c (patch) (side-by-side diff)
treee9e61bcfd9d1945c612a54e080d4fdc2e87cbad5 /doc
parente5fccca3abee9093f4d1e50823addca8e6c778a6 (diff)
downloadgdbm-979486e1b46a894fc9de2abe6eb8985536a5013c.tar.gz
gdbm-979486e1b46a894fc9de2abe6eb8985536a5013c.tar.bz2
Improve handling of the variables.
* src/gdbmtool.c (opendb): Allow for unset variables. * src/gram.y: Improve error detection. * src/lex.l: Handle multiline strings. (pe_file_name): file_name can be NULL. * src/var.c (VARF_PROT): New flag. Protects the variable from being unset. (vartab): Use VARF_PROT if needed. (s2b): Fix return values. (variable_set, variable_unset): Return error if attempting to unset a variable marked with VARF_PROT. * doc/gdbm.info: Update. * doc/gdbmtool.1: Update.
Diffstat (limited to 'doc') (more/less context) (ignore whitespace changes)
-rw-r--r--doc/gdbm.texinfo501
-rw-r--r--doc/gdbmtool.1253
2 files changed, 541 insertions, 213 deletions
diff --git a/doc/gdbm.texinfo b/doc/gdbm.texinfo
index 17f47f9..d5bb7f3 100644
--- a/doc/gdbm.texinfo
+++ b/doc/gdbm.texinfo
@@ -1629,7 +1629,7 @@ existing @acronym{GDBM} database or to create a new one.
When invoked without arguments, it tries to open a database file called
@file{junk.gdbm}, located in the current working directory. You can
change this default by supplying the name of the database to use as
-the only argument to @command{gdbmtool}, e.g.:
+an argument to the program, e.g.:
@example
$ gdbmtool file.db
@@ -1669,9 +1669,15 @@ Set block size.
@item -c @var{size}
@itemx --cache-size=@var{size}
Set cache size.
+@item -f @var{file}
+@item --file @var{file}
+Read commands from @var{file}, instead of the standard input.
@item -h
@itemx --help
Print a concise help summary.
+@item -N
+@itemx --norc
+Don't read startup files (@pxref{startup files}).
@item -n
@itemx --newdb
Create the database.
@@ -1681,9 +1687,11 @@ Disable file locking.
@item -m
@itemx --no-mmap
Disable mmap.
+@anchor{-q option}
@item -q
@itemx --quiet
-Don't print the usual welcome banner at startup.
+Don't print the usual welcome banner at startup. This is the same as
+setting the variable @samp{quiet} in the startup file. @xref{quiet}.
@item -r
@itemx --read-only
Open the database in read-only mode.
@@ -1703,10 +1711,10 @@ command line options.
@cindex interactive mode, @command{gdbmtool}
After successful startup, @command{gdbmtool} starts a loop, in which
-it reads commands from the user, executes them and prints the results
-on the standard output. If the standard input is attached to a console,
-@command{gdbmtool} runs in interactive mode, which is indicated by its
-@dfn{prompt}:
+it reads commands from the standard input, executes them and prints
+the results on the standard output. If the standard input is attached
+to a console, @command{gdbmtool} runs in interactive mode, which is
+indicated by its @dfn{prompt}:
@example
gdbmtool> _
@@ -1716,30 +1724,49 @@ The utility finishes when it reads the @samp{quit} command (see below) or
detects end-of-file on its standard input, whichever occurs first.
A @command{gdbmtool} command consists of a @dfn{command verb},
-optionally followed by one or two @dfn{arguments}, separated by any
+optionally followed by @dfn{arguments}, separated by any
amount of white space. 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, @samp{co} can be used instead of
-@samp{count} and @samp{ca} instead of @samp{cache}. Furthermore,
-many command verbs also have single-letter forms, called @dfn{command
-letters}.
-
-An argument is any sequence of non-whitespace characters. Notice,
-that currently there is no way to enter arguments containing white
-space. This limitation will be removed in future releases.
-
-Each command takes at most two @dfn{formal parameters}, which can be
-optional or mandatory. If the number of actual arguments is less than the
-number of mandatory parameters, @command{gdbmtool} will prompt you to
-supply missing arguments. For example, the @samp{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:
+@samp{count} and @samp{ca} instead of @samp{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 @dfn{escape sequences} are understood, as
+shown in the table below:
+
+@float Table, backslash-interpretation
+@caption{Backslash escapes}
+@multitable @columnfractions 0.30 .5
+@item Sequence @tab Replaced with
+@item \a @tab Audible bell character (@acronym{ASCII} 7)
+@item \b @tab Backspace character (@acronym{ASCII} 8)
+@item \f @tab Form-feed character (@acronym{ASCII} 12)
+@item \n @tab Newline character (@acronym{ASCII} 10)
+@item \r @tab Carriage return character (@acronym{ASCII} 13)
+@item \t @tab Horizontal tabulation character (@acronym{ASCII} 9)
+@item \v @tab Vertical tabulation character (@acronym{ASCII} 11)
+@item \\ @tab Single slash
+@item \" @tab Double quote
+@end multitable
+@end float
+
+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,
+@command{gdbmtool} will prompt you to supply missing arguments. For
+example, the @samp{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:
@example
gdbmtool> @kbd{store}
-key> @kbd{three}
-data> @kbd{3}
+key? @kbd{three}
+data? @kbd{3}
@end example
However, such prompting is possible only in interactive mode. In
@@ -1747,39 +1774,238 @@ non-interactive mode (e.g.@: when running a script), all arguments must
be supplied with each command, otherwise @command{gdbmtool} will report an
error and exit immediately.
-@anchor{pager}
-@cindex pager, @command{gdbmtool}
-@cindex @env{PAGER}
-Some commands produce excessive amounts of output. To help you follow
-it, @command{gdbmtool} uses a pager utility to display such
-output. The name of the pager utility is taken from the environment
-variable @env{PAGER}. The pager is invoked only in interactive mode
-and only if the estimated number of output lines is greater then the
-number of lines on your screen.
-
-@anchor{nul-termination}
-Many of the @command{gdbmtool} commands operate on database key and
-data values. The utility assumes that both keys and data are
-@acronym{ASCII} strings, either nul-terminated or not. By default,
-it is assumed that strings are nul-terminated. You can change this
-by using @code{z} (@code{key-zero}, for keys) and @code{Z}
-(@code{data-zero}, for data) commands.
-
-The following table summarizes all available commands:
+@menu
+* variables:: shell variables.
+* commands:: shell commands.
+* definitions:: how to define structured data.
+* startup files::
+@end menu
+
+@node variables
+@subsection Shell Variables
+@cindex variables, gdbmtool
+A number of @command{gdbmtool} parameters is kept in its internal
+variables.
+
+@deftypevr {gdbmtool variable} bool confirm
+Whether to ask for confirmation before certain destructive operations,
+such as truncating the existing database.
+
+Default is @samp{true}.
+@end deftypevr
+
+@deftypevr {gdbmtool variable} string ps1
+Primary prompt string. Its value can contain @dfn{conversion
+specifiers}, consisting of the @samp{%} character followed by another
+character. These specifiers are expanded in the resulting prompt as
+follows:
+
+@multitable @columnfractions 0.4 0.5
+@headitem Sequence @tab Expansion
+@item %f @tab name of the current database file
+@item %p @tab program invocation name
+@item %P @tab package name (@samp{GDBM})
+@item %v @tab program version
+@item %_ @tab single space character
+@item %% @tab %
+@end multitable
+
+The default value is @samp{%p>%_}, i.e. the program name, followed by
+a ``greater than'' sign, followed by a single space.
+@end deftypevr
+
+@deftypevr {gdbmtool variable} string ps2
+Secondary prompt. See @samp{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 @samp{%_>%_}.
+@end deftypevr
+
+@deftypevr {gdbmtool variable} string delim1
+A string used to delimit fields of a structured datum on output
+(@pxref{definitions}).
+
+Default is @samp{,} (a comma). This variable cannot be unset.
+@end deftypevr
+
+@deftypevr {gdbmtool variable} string delim2
+A string used to delimit array items when printing a structured datum
+(@pxref{definitions}).
+
+Default is @samp{,} (a comma). This variable cannot be unset.
+@end deftypevr
+
+@deftypevr {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
+@env{PAGER}. Unsetting this variable disables paging.
+@end deftypevr
+
+@anchor{quiet}
+@deftypevr {gdbmtool variable} bool quiet
+Whether to display a welcome banner at startup. This variable should
+be set in a startup script file (@pxref{startup files}).
+@xref{-q option}.
+@end deftypevr
+
+@anchor{open parameters}
+The following variables control how the database is opened:
+
+@deftypevr {gdbmtool variable} numeric cachesize
+Sets the cache size. @xref{Options, GDBM_SETCACHESIZE}.
+By default this variable is not set.
+@end deftypevr
+
+@deftypevr {gdbmtool variable} numeric blocksize
+Sets the block size. @xref{Open, block_size}. Unset by default.
+@end deftypevr
+
+@anchor{openvar}
+@deftypevr {gdbmtool variable} string open
+Open mode. The following values are allowed:
+
+@table @asis
+@item newdb
+Truncate the database if it exists or create a new one. Open it in
+read-write mode.
+
+Technically, this sets the @samp{GDBM_NEWDB} flag in call to @samp{gdbm_open}.
+@xref{Open, GDBM_NEWDB}.
+@item wrcreat
+@itemx rw
+Open the database in read-write mode. Create it if it does not
+exist. This is the default.
+
+Technically speaking, it sets the @samp{GDBM_WRCREAT} flag in call to
+@code{gdbm_open}. @xref{Open, GDBM_WRCREAT}.
+@item reader
+@itemx readonly
+Open the database in read-only mode. Signal an error if it does not
+exist.
+
+This sets the @samp{GDBM_READER} flag (@pxref{Open, GDBM_READER}).
+@end table
+
+Attempting to set any other value or to unset this variable produces
+an error.
+@end deftypevr
+
+@deftypevr {gdbmtool variable} bool lock
+Lock the database. This is the default.
+
+Setting this variable to false or unsetting it results in passing
+@samp{GDBM_NOLOCK} flag to @code{gdbm_open} (@pxref{Open, GDBM_NOLOCK}).
+@end deftypevr
+
+@deftypevr {gdbmtool variable} bool mmap
+Use memory mapping. This is the default.
+
+Setting this variable to false or unsetting it results in passing
+@samp{GDBM_NOMMAP} flag to @code{gdbm_open} (@pxref{Open, GDBM_NOMMAP}).
+@end deftypevr
+
+@deftypevr {gdbmtool variable} bool sync
+Flush all database writes on disk immediately. Default is false.
+@xref{Open, GDBM_SYNC}.
+@end deftypevr
+
+The following commands are used to list or modify the variables:
+
+@deffn {command verb} set [@var{assignments}]
+When used without arguments, lists all variables and their values.
+Unset variables are shown after a comment sign (@samp{#}). 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 @samp{true}. If it is @samp{false}, its name is prefixed with
+@samp{no}.
+
+For example:
+
+@example
+@group
+ps1="%p>%_"
+ps2="%_>%_"
+delim1=","
+delim2=","
+confirm
+# cachesize is unset
+# blocksize is unset
+open="wrcreat"
+lock
+mmap
+nosync
+pager="less"
+# quiet is unset
+@end group
+@end example
+
+If used with arguments, the @code{set} command alters the specified
+variables. In this case, arguments are variable assignments in the
+form @samp{@var{name}=@var{value}}. For boolean variables, the
+@var{value} is interpreted as follows: if it is numeric, @samp{0}
+stands for @samp{false}, any non-zero value stands for @samp{true}.
+Otherwise, the values @samp{on}, @samp{true}, and @samp{yes} denote
+@samp{true}, and @samp{off}, @samp{false}, @samp{no} stand for
+@samp{false}. Alternatively, only the name of a boolean variable can be
+supplied to set it to @samp{true}, and its name prefixed with
+@samp{no} can be used to set it to false. For example, the following
+command sets the @samp{delim2} variable to @samp{;} and the
+@samp{confirm} variable to @samp{false}:
+
+@example
+srt delim2=";" noconfirm
+@end example
+@end deffn
+
+@deffn {command verb} unset @var{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
+@samp{false}. Unsetting a string variable is equivalent to setting it
+to an empty string.
+@end deffn
+
+@node commands
+@subsection Gdbmtool Commands
+
+@deffn {command verb} avail
+Print the @dfn{avail list}.
+@end deffn
+
+@deffn {command verb} bucket @var{num}
+Print the bucket number @var{num} and set it as the current one.
+@end deffn
+
+@deffn {command verb} cache
+Print the bucket cache.
+@end deffn
+
+@deffn {command verb} close
+Close the currently open database.
+@end deffn
@deffn {command verb} count
-@deffnx {command letter} c
Print the number of entries in the database.
@end deffn
+@deffn {command verb} current
+Print the current bucket.
+@end deffn
+
@deffn {command verb} delete @var{key}
-@deffnx {command letter} d @var{key}
-Delete entry with the given @var{key}
+Delete record with the given @var{key}
+@end deffn
+
+@deffn {command verb} dir
+Print hash directory.
@end deffn
@anchor{gdbmtool export}
@deffn {command verb} export @var{file-name} [truncate] [binary|ascii]
-@deffnx {command letter} e @var{file-name} [truncate] [binary|ascii]
Export the database to the flat file @var{file-name}. @xref{Flat files},
for a description of the flat file format and its purposes. This
command will not overwrite an existing file, unless the
@@ -1791,13 +2017,32 @@ See also @ref{gdbmexport}.
@end deffn
@deffn {command verb} fetch @var{key}
-@deffnx {command letter} f @var{key}
Fetch and display the record with the given @var{key}.
@end deffn
+@deffn {command verb} first
+Fetch and display the first record in the database. Subsequent
+records can be fetched using the @code{next} command (see below).
+@xref{Sequential}, for more information on sequential access.
+@end deffn
+
+@deffn {command verb} hash @var{key}
+Compute and display the hash value for the given @var{key}.
+@end deffn
+
+@deffn {command verb} header
+Print file header.
+@end deffn
+
+@deffn {command verb} help
+@deffnx {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.
+@end deffn
+
@anchor{gdbmtool import}
@deffn {command verb} import @var{file-name} [replace] [nometa]
-@deffnx {command letter} i @var{file-name} [replace] [nometa]
Import data from a flat dump file @var{file-name}
(@pxref{Flat files}). If the word @samp{replace} is given
as an argument, any records with the same keys as the already
@@ -1806,135 +2051,111 @@ restoring meta-information from the dump file.
@end deffn
@deffn {command verb} list
-@deffnx {command letter} l
-List the contents of the database (@pxref{pager}).
+List the contents of the database.
@end deffn
@deffn {command verb} next [@var{key}]
-@deffnx {command letter} n [@var{key}]
Sequential access: fetch and display the next record. If the @var{key} is
given, the record following the one with this key will be fetched.
-See also @code{first}, below.
+See also @code{first}, above.
@xref{Sequential}, for more information on sequential access.
@end deffn
-@deffn {command verb} prompt @var{text}
-Changes the command prompt to the string @var{text}. The string can
-contain @dfn{escape sequences}, the special entities consisting of the
-@samp{%} character followed by another character. These sequences are
-replaced in the generated prompt as follows:
+@deffn {command verb} open @var{filename}
+Open the database file @var{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:
+
+@table @samp
+@item open
+The database access mode. @xref{openvar,, The @var{open} variable},
+for a list of its values.
+@item lock
+Whether or not to lock the database. Default is @samp{on}.
+@item mmap
+Use the memmory mapping. Default is @samp{on}.
+@item sync
+Synchronize after each write. Default is @samp{off}.
+@end table
-@multitable @columnfractions 0.4 0.5
-@headitem Sequence @tab Expansion
-@item %f @tab name of the db file
-@item %% @tab %
-@end multitable
+@xref{open parameters}, for a detailed description of these variables.
@end deffn
@deffn {command verb} quit
-@deffnx {command letter} q
Close the database and quit the utility.
@end deffn
-@deffn {command verb} store @var{key} @var{data}
-@deffnx {command letter} s @var{key} @var{data}
-Store the @var{data} with @var{key} in the database. If @var{key}
-already exists, its data will be replaced.
-@end deffn
-
-@deffn {command verb} first
-@deffnx {command letter} 1
-Fetch and display the first record in the database. Subsequent
-records can be fetched using the @code{next} command (see above).
-@xref{Sequential}, for more information on sequential access.
-@end deffn
-
-@deffn {command verb} read @var{file} [replace]
-@deffnx {command letter} < @var{file} [replace]
-Read entries from @var{file} and store them in the database. If the
-@samp{replace} parameter is given, any existing records with matching
-keys will be replaced.
-@end deffn
-
@deffn {command verb} reorganize
-@deffnx {command letter} r
Reorganize the database (@pxref{Reorganization}).
@end deffn
-@deffn {command verb} key-zero
-@deffnx {command letter} z
-Toggle key nul-termination. Use @code{status} to inspect the current
-state. @xref{nul-termination}.
-@end deffn
-
-@deffn {command verb} avail
-@deffnx {command letter} A
-Print the @dfn{avail list}.
-@end deffn
-
-@deffn {command verb} bucket
-@deffnx {command letter} B
-Print the bucket number @var{num}.
-@end deffn
-
-@deffn {command verb} current
-@deffnx {command letter} C
-Print the current bucket.
-@end deffn
-
-@deffn {command verb} dir
-@deffnx {command letter} D
-Print hash directory.
-@end deffn
-
-@deffn {command verb} header
-@deffnx {command letter} F
-Print file header.
-@end deffn
-
-@deffn {command verb} hash @var{key}
-@deffnx {command letter} H @var{key}
-Compute and display the hash value for the given @var{key}.
-@end deffn
-
-@deffn {command verb} cache
-@deffnx {command letter} K
-Print the bucket cache.
+@deffn {command verb} source @var{filename}
+Read @command{gdbmtool} commands from the file @var{filename}.
@end deffn
@deffn {command verb} status
-@deffnx {command letter} S
Print current program status. The following example shows the
information displayed:
@example
Database file: junk.gdbm
-Zero terminated keys: yes
-Zero terminated data: yes
+Database is open
+define key @{
+ string,
+@}
+define content @{
+ string,
+@}
@end example
@end deffn
+@deffn {command verb} store @var{key} @var{data}
+Store the @var{data} with @var{key} in the database. If @var{key}
+already exists, its data will be replaced.
+@end deffn
+
@deffn {command verb} version
-@deffnx {command letter} v
Print the version of @command{gdbm}.
@end deffn
-@deffn {command verb} data-zero
-@deffnx {command letter} Z
-Toggle data nul-termination. Use @code{status} to examine the current
-status.
+@node definitions
+@subsection Data Definitions
-@xref{nul-termination}.
-@end deffn
+@node startup files
+@subsection Startup Files
+@cindex startup file, gdbmtool
+@cindex init file, gdbmtool
+@flindex .gdbmtoolrc
+Upon startup @command{gdbmtool} looks for a file named
+@samp{.gdbmtoolrc} first in the current working directory and, if not
+found, in the home directory of the user who started the command.
-@deffn {command verb} help
-@deffnx {command letter} ?
-Print a concise command summary, showing each command letter and verb
-with its parameters and a short description of what it does. Optional
-arguments are enclosed in square brackets.
-@end deffn
+If found, this file is read and interpreted as a list of
+@command{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:
+
+@example
+@group
+set quiet
+set ps1="(%f) "
+
+define content @{
+ int time,
+ pad 4,
+ int status
+@}
+@end group
+@end example
@node gdbm_dump
@chapter The @command{gdbm_dump} utility
diff --git a/doc/gdbmtool.1 b/doc/gdbmtool.1
index 1c2d2c4..2326a32 100644
--- a/doc/gdbmtool.1
+++ b/doc/gdbmtool.1
@@ -1,4 +1,4 @@
-.\" This file is part of GDBM.
+.\" This file is part of GDBM. -*- nroff -*-
.\" Copyright (C) 2013 Free Software Foundation, Inc.
.\"
.\" GDBM is free software; you can redistribute it and/or modify
@@ -17,10 +17,11 @@
.SH NAME
gdbmtool \- examine and modify a GDBM database
.SH SYNOPSIS
-\fBgdbmtool\fR [\fB\-lmnqrs\fR] [\fB\-b\fR \fISIZE\fR] [\fB\-c\fR \fISIZE\fR]\
- [\fB\-g\fR \fIFILE\fR] [\fB\-\-block\-size\fR=\fISIZE\fR]
- [\fB\-\-cache\-size\fR=\fISIZE\fR] [\fB\-\-newdb\fR]\
- [\fB\-\-no\-lock\fR] [\fB\-\-no\-mmap\fR]
+\fBgdbmtool\fR [\fB\-lmNnqrs\fR] [\fB\-b\fR \fISIZE\fR] [\fB\-c\fR \fISIZE\fR]\
+ [\fB\-f\fR \fIFILE\fR] [\fB\-\-block\-size\fR=\fISIZE\fR]
+ [\fB\-\-cache\-size\fR=\fISIZE\fR] [\fB\-\-file\fR \fIFILE\fR]\
+ [\fB\-\-newdb\fR] [\fB\-\-no\-lock\fR]
+ [\fB\-\-no\-mmap\fR] [\fB\-\-norc\fR]
[\fB\-\-quiet\fR] [\fB\-\-read\-only\fR] [\fB\-\-synchronize\fR]\
[\fIDBFILE\fR]
.sp
@@ -39,10 +40,20 @@ If the named database does not exist, it will be created. An existing
database can be cleared (i.e. all records removed from it) using the
\fB\-\-newdb\fR option (see below).
.PP
-After successful startup,
+Unless the \fB\-N\fR (\fB\-\-norc\fR) option is given, after startup
+.B gdbmtool
+looks for file named
+.B .gdbmtoolrc
+first in the current working directory, and, if not found there, in
+the home directory of the user who started the program. If found,
+this file is read and interpreted as a list of
+.B gdbmtool
+commands.
+.PP
+Then
.B gdbmtool
starts a loop, in which it reads
-commands from the user, executes them and prints the results on the
+commands from the standard input, executes them and prints the results on the
standard output. If the standard input is attached to a console,
the program runs in interactive mode.
.PP
@@ -56,8 +67,32 @@ command consists of a command verb, optionally
followed by one or more arguments, separated by any amount of white
space. 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. Many command verbs have also one-letter abbreviation which can
-be used instead.
+verb.
+.PP
+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:
+.sp
+.nf
+.ta 8n 20n
+.ul
+ Escape Expansion
+ \\a Audible bell character (ASCII 7)
+ \\b Backspace character (ASCII 8)
+ \\f Form-feed character (ASCII 12)
+ \\n Newline character (ASCII 10)
+ \\r Carriage return character (ASCII 13)
+ \\t Horizontal tabulation character (ASCII 9)
+ \\v Vertical tabulation character (ASCII 11)
+ \\\\ Single slash
+ \" Double quote
+.fi
+.PP
+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.
.SH OPTIONS
.TP
\fB\-b\fR, \fB\-\-block\-size\fR=\fISIZE\fR
@@ -66,6 +101,9 @@ Set block size.
\fB\-c\fR, \fB\-\-cache\-size\fR=\fISIZE\fR
Set cache size.
.TP
+\fB\-f\fR, \fB\-\-file\fR=\fIFILE\fR
+Read commands from \fIFILE\fR, instead of from the standard input.
+.TP
\fB\-l\fR, \fB\-\-no\-lock\fR
Disable file locking.
.TP
@@ -94,35 +132,30 @@ Print a list of available options.
\fB\-V\fR, \fB\-\-version\fR
Print program version
.SH SHELL COMMANDS
-For command verbs that have single-letter abbreviations, these are
-printed after a comma. Either command verb or its abbreviation must
-be used, but not both.
.TP
-.BR avail ", " A
-Print the "
+.BR avail
+Print the
.BR "avail list" .
.TP
-\fBbucket\fR, \fBB\fR \fINUM\fR
-Print the bucket number \fINUM\fR.
+\fBbucket\fR \fINUM\fR
+Print the bucket number \fINUM\fR and set is as the current one.
.TP
-.BR cache ", " K
+.BR cache
Print the bucket cache.
.TP
-.BR count ", " c
+.B close
+Close the currently open database.
+.TP
+.BR count
Print the number of entries in the database.
.TP
-.BR current ", " C
+.BR current
Print the current bucket.
.TP
-.BR data-zero ", " Z
-Toggle data nul-termination. Use
-.B status
-to examine the current status.
-.TP
-\fBdelete\fR, \fBd\fR \fIKEY\fR
-Delete entry with the given \fIKEY\fR.
+\fBdelete\fR \fIKEY\fR
+Delete record with the given \fIKEY\fR.
.TP
-.BR dir ", " D
+.BR dir
Print hash directory.
.TP
\fBexport\fR, \fBe\fR \fIFILE\-NAME\fR [\fBtruncate\fR] [\fBbinary\fR|\fBascii\fR]
@@ -134,27 +167,27 @@ This command will not overwrite an existing file, unless the
parameter is also given. Another optional parameter determines the type of
the dump (*note Flat files::). By default, ASCII dump will be created.
.TP
-\fBfetch\fR, \fBf\fR \fIKEY\fR
+\fBfetch\fR \fIKEY\fR
Fetch and display the record with the given \fIKEY\fR.
.TP
-.BR first ", " 1
+.BR first
Fetch and display the first record in the database. Subsequent
records can be fetched using the
.B next
command (see below).
.TP
-\fBhash\fR, \fBH\fR \fIKEY\fR
-Compute and display hash value for the given \fIKEY\fR.
+\fBhash\fR \fIKEY\fR
+Compute and display the hash value for the given \fIKEY\fR.
.TP
-.BR header ", " F
+.BR header
Print file header.
.TP
-.BR help ", " ?
+.BR help " or " ?
Print a concise command summary, showing each command letter and
verb with its parameters and a short description of what it does.
Optional arguments are enclosed in square brackets.
.TP
-\fBimport\fR, \fBi\fR \fIFILE\-NAME\fR [\fBreplace\fR] [\fBnometa\fR]
+\fBimport\fR \fIFILE\-NAME\fR [\fBreplace\fR] [\fBnometa\fR]
Import data from a flat dump file \fIFILE\-NAME\fR.
If the
.B replace
@@ -163,26 +196,66 @@ existing ones will replace them. The
.B nometa
argument turns off restoring meta-information from the dump file.
.TP
-.BR key-zero ", " z
-Toggle key nul-termination. Use
-.B status
-to inspect the current state.
-.TP
-\fBlist\fR, \fBl\fR
+\fBlist\fR
List the contents of the database.
.TP
-\fBnext\fR, \fBn\fR [\fIKEY\fR]
+\fBnext\fR [\fIKEY\fR]
Sequential access: fetch and display the next record. If the \fIKEY\fR is
given, the record following the one with this key will be fetched.
.TP
-\fBprompt\fR \fITEXT\fR
-Changes the command prompt to the string \fITEXT\fR. The string can
-contain
-.BR "escape sequences" ,
-the special entities consisting of the
-.B %
-character followed by another character. These sequences are
-replaced in the generated prompt as follows:
+\fBopen\fR \fIFILE\fR
+Open the database file \fIFILE\fR. 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 variables
+.BR open ,
+.BR lock ,
+.BR mmap ", and"
+.BR sync .
+See the section
+.BR VARIABLES ,
+for a detailed description of these.
+.TP
+.B quit
+Close the database and quit the utility.
+.TP
+.BR reorganize
+Reorganize the database.
+\fBset\fR [\fIVAR\fR=\fIVALUE\fR...]
+Without arguments, lists variables and their values. If arguments are
+specified, sets variables. Boolean variables can be set by specifying
+variable name, optionally prefixed with \fBno\fR, to set it to \fBfalse\fR.
+.TP
+\fBsource\fR \fIFILE\fR
+Read commands from the given \fIFILE\fR.
+.TP
+.BR status
+Print current program status.
+.TP
+\fBstore\fR \fIKEY\fR \fIDATA\fR
+Store the \fIDATA\fR with the given \fIKEY\fR in the database. If the
+\fIKEY\fR already exists, its data will be replaced.
+.TP
+\fBunset\fR \fIVARIABLE\fR...
+Unsets listed variables.
+.TP
+.BR version
+Print the version of
+.BR gdbm .
+.SH "DATA DEFINITIONS"
+.SH VARIABLES
+.TP
+.BR confirm ", boolean"
+Whether to ask for confirmation before certain destructive operations,
+such as truncating the existing database. Default is
+.BR true .
+.TP
+.BR ps1 ", string"
+Primary prompt string. Its value can contain \fIconversion
+specifiers\fR, consisting of the \fB%\fR character followed by another
+character. These specifiers are expanded in the resulting prompt as
+follows:
.sp
.nf
.ta 8n 20n
@@ -198,35 +271,69 @@ replaced in the generated prompt as follows:
.sp
The default prompt is \fB%p>%_\fR.
.TP
-.BR quit ", " q
-Close the database and quit the utility.
+.BR ps2 ", string"
+Secondary prompt. See
+.B 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 \fB%_>%_\fR.
.TP
-\fBread\fR, \fB<\fR \fIFILE\fR [\fBreplace\fR]
-Read entries from \fIFILE\fR and store them in the database. If the
-.B replace
-parameter is given, any existing records with matching keys will be replaced.
+.BR delim1 ", string"
+A string used to delimit fields of a structured datum on output
+(see the section \fBDATA DEFINITIONS\fR).
+
+Default is \fB,\fR (a comma). This variable cannot be unset.
.TP
-.BR reorganize ", " r
-Reorganize the database.
+.BR delim2 ", string"
+A string used to delimit array items when printing a structured datum.
+
+Default is \fB,\fR (a comma). This variable cannot be unset.
.TP
-.BR status ", " S
-Print current program status. The following example shows the
-information displayed:
-.sp
-.nf
-.if +2
-Database file: junk.gdbm
-Zero terminated keys: yes
-Zero terminated data: yes
-.fi
+.BR pager ", string"
+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
+\fBPAGER\fR. Unsetting this variable disables paging.
.TP
-\fBstore\fR, \fBs\fR \fIKEY\fR \fIDATA\fR
-Store the \fIDATA\fR with the given \fIKEY\fR in the database. If the
-\fIKEY\fR already exists, its data will be replaced.
+.BR quiet ", boolean"
+Whether to display welcome banner at startup. This variable should
+be set in a startup script file.
+.PP
+The following variables control how the database is opened:
.TP
-.BR version ", " v
-Print the version of
-.BR gdbm .
+.BR cachesize ", numeric"
+Sets the cache size. By default this variable is not set.
+.TP
+.BR blocksize ", numeric"
+Sets the block size. Unset by default.
+.TP
+.BR open ", string"
+Open mode. The following values are allowed:
+.RS 7
+.TP
+.BR newdb
+Truncate the database if it exists or create a new one. Open it in
+read-write mode.
+.TP
+.BR wrcreat " or " rw
+Open the database in read-write mode. Create it if it does not
+exist. This is the default.
+.TP
+.BR reader " or " readonly
+Open the database in read-only mode. Signal an error if it does not
+exist.
+.RE
+.TP
+.BR lock ", boolean"
+Lock the database. This is the default.
+.TP
+.BR mmap ", boolean"
+Use memory mapping. This is the default.
+
.SH "SEE ALSO"
.BR gdbm_dump (1),
.BR gdbm_load (1),

Return to:

Send suggestions and report system problems to the System administrator.