aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2013-05-16 15:32:45 +0000
committerSergey Poznyakoff <gray@gnu.org.ua>2013-05-16 15:32:45 +0000
commit979486e1b46a894fc9de2abe6eb8985536a5013c (patch)
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')
-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
@@ -1626,13 +1626,13 @@ existing @acronym{GDBM} database or to create a new one.
@cindex default database, @command{gdbmtool}
@flindex junk.gdbm
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
@end example
@cindex read-only mode, @command{gdbmtool}
@@ -1666,27 +1666,35 @@ options:
@item -b @var{size}
@itemx --block-size=@var{size}
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.
@item -l
@itemx --no-lock
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.
@item -s
@itemx --synchronize
Synchronize to the disk after each write.
@@ -1700,244 +1708,457 @@ command line options.
@node shell
@section gdbmtool interactive mode
@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> _
@end example
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
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
@samp{truncate} parameter is also given. Another optional argument
determines the type of the dump (@pxref{Flat files}). By default, ASCII
dump is created.
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
existing ones will replace them. The word @samp{nometa} turns off
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
@prindex gdbm_dump
The @command{gdbm_dump} utility creates a flat file dump of a GDBM
diff --git a/doc/gdbmtool.1 b/doc/gdbmtool.1
index 1c2d2c4..2326a32 100644
--- a/doc/gdbmtool.1
+++ b/doc/gdbmtool.1
@@ -1,7 +1,7 @@
-.\" 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
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3, or (at your option)
.\" any later version.
@@ -14,16 +14,17 @@
.\" You should have received a copy of the GNU General Public License
.\" along with GDBM. If not, see <http://www.gnu.org/licenses/>. */
.TH GDBM_DUMP 1 "May 9, 2013" "GDBM" "GDBM User Reference"
.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
\fBgdbmtool\fR [\fB\-Vh\fR] ][\fB\-\-help\fR] [\fB\-\-usage\fR] [\fB\-\-version\fR]
.SH DESCRIPTION
The
@@ -36,16 +37,26 @@ If not supplied, the default name
.B junk.gdbm
is used instead.
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
The program terminates when the
.B quit
command is given, or end-of-file is detected on its standard input.
@@ -53,22 +64,49 @@ command is given, or end-of-file is detected on its standard input.
A
.B gdbmtool
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
Set block size.
.TP
\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
\fB\-m\fR, \fB\-\-no\-mmap\fR
Do not use
.BR mmap (2).
@@ -91,101 +129,136 @@ Print a short usage summary.
\fB\-\-usage\fR
Print a list of available options.
.TP
\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]
Export the database to the flat file \fIFILE\-NAME\fR. This is equivalent to
.BR gdbm_dump (1).
This command will not overwrite an existing file, unless the
.B truncate
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
argument is given, any records with the same keys as the already
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
.ul
Sequence Expansion
\fB%f\fR name of the db file
@@ -195,41 +268,75 @@ replaced in the generated prompt as follows:
\fB%v\fR program version
\fB%%\fR \fB%\fR
.fi
.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),
.BR gdbm (3).
.SH "REPORTING BUGS"
Report bugs to <bug\-gdbm@gnu.org>.

Return to:

Send suggestions and report system problems to the System administrator.