aboutsummaryrefslogtreecommitdiff
path: root/doc/gdbmtool.1
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/gdbmtool.1
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/gdbmtool.1')
-rw-r--r--doc/gdbmtool.1253
1 files changed, 180 insertions, 73 deletions
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.