aboutsummaryrefslogtreecommitdiff
path: root/doc/gdbm.texinfo
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/gdbm.texinfo
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/gdbm.texinfo')
-rw-r--r--doc/gdbm.texinfo501
1 files changed, 361 insertions, 140 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.
1629When invoked without arguments, it tries to open a database file called 1629When invoked without arguments, it tries to open a database file called
1630@file{junk.gdbm}, located in the current working directory. You can 1630@file{junk.gdbm}, located in the current working directory. You can
1631change this default by supplying the name of the database to use as 1631change this default by supplying the name of the database to use as
1632the only argument to @command{gdbmtool}, e.g.: 1632an argument to the program, e.g.:
1633 1633
1634@example 1634@example
1635$ gdbmtool file.db 1635$ gdbmtool file.db
@@ -1669,9 +1669,15 @@ Set block size.
1669@item -c @var{size} 1669@item -c @var{size}
1670@itemx --cache-size=@var{size} 1670@itemx --cache-size=@var{size}
1671Set cache size. 1671Set cache size.
1672@item -f @var{file}
1673@item --file @var{file}
1674Read commands from @var{file}, instead of the standard input.
1672@item -h 1675@item -h
1673@itemx --help 1676@itemx --help
1674Print a concise help summary. 1677Print a concise help summary.
1678@item -N
1679@itemx --norc
1680Don't read startup files (@pxref{startup files}).
1675@item -n 1681@item -n
1676@itemx --newdb 1682@itemx --newdb
1677Create the database. 1683Create the database.
@@ -1681,9 +1687,11 @@ Disable file locking.
1681@item -m 1687@item -m
1682@itemx --no-mmap 1688@itemx --no-mmap
1683Disable mmap. 1689Disable mmap.
1690@anchor{-q option}
1684@item -q 1691@item -q
1685@itemx --quiet 1692@itemx --quiet
1686Don't print the usual welcome banner at startup. 1693Don't print the usual welcome banner at startup. This is the same as
1694setting the variable @samp{quiet} in the startup file. @xref{quiet}.
1687@item -r 1695@item -r
1688@itemx --read-only 1696@itemx --read-only
1689Open the database in read-only mode. 1697Open the database in read-only mode.
@@ -1703,10 +1711,10 @@ command line options.
1703@cindex interactive mode, @command{gdbmtool} 1711@cindex interactive mode, @command{gdbmtool}
1704 1712
1705After successful startup, @command{gdbmtool} starts a loop, in which 1713After successful startup, @command{gdbmtool} starts a loop, in which
1706it reads commands from the user, executes them and prints the results 1714it reads commands from the standard input, executes them and prints
1707on the standard output. If the standard input is attached to a console, 1715the results on the standard output. If the standard input is attached
1708@command{gdbmtool} runs in interactive mode, which is indicated by its 1716to a console, @command{gdbmtool} runs in interactive mode, which is
1709@dfn{prompt}: 1717indicated by its @dfn{prompt}:
1710 1718
1711@example 1719@example
1712gdbmtool> _ 1720gdbmtool> _
@@ -1716,30 +1724,49 @@ The utility finishes when it reads the @samp{quit} command (see below) or
1716detects end-of-file on its standard input, whichever occurs first. 1724detects end-of-file on its standard input, whichever occurs first.
1717 1725
1718A @command{gdbmtool} command consists of a @dfn{command verb}, 1726A @command{gdbmtool} command consists of a @dfn{command verb},
1719optionally followed by one or two @dfn{arguments}, separated by any 1727optionally followed by @dfn{arguments}, separated by any
1720amount of white space. A command verb can be entered either in full 1728amount of white space. A command verb can be entered either in full
1721or in an abbreviated form, as long as that abbreviation does not match 1729or in an abbreviated form, as long as that abbreviation does not match
1722any other verb. For example, @samp{co} can be used instead of 1730any other verb. For example, @samp{co} can be used instead of
1723@samp{count} and @samp{ca} instead of @samp{cache}. Furthermore, 1731@samp{count} and @samp{ca} instead of @samp{cache}.
1724many command verbs also have single-letter forms, called @dfn{command 1732
1725letters}. 1733Any sequence of non-whitespace characters appearing after the command
1726 1734verb forms an argument. If the argument contains whitespace or
1727An argument is any sequence of non-whitespace characters. Notice, 1735unprintable characters it must be enclosed in double quotes. Within
1728that currently there is no way to enter arguments containing white 1736double quotes the usual @dfn{escape sequences} are understood, as
1729space. This limitation will be removed in future releases. 1737shown in the table below:
1730 1738
1731Each command takes at most two @dfn{formal parameters}, which can be 1739@float Table, backslash-interpretation
1732optional or mandatory. If the number of actual arguments is less than the 1740@caption{Backslash escapes}
1733number of mandatory parameters, @command{gdbmtool} will prompt you to 1741@multitable @columnfractions 0.30 .5
1734supply missing arguments. For example, the @samp{store} command takes two 1742@item Sequence @tab Replaced with
1735mandatory parameters, so if you invoked it with no arguments, you 1743@item \a @tab Audible bell character (@acronym{ASCII} 7)
1736would be prompted twice to supply the necessary data, as shown in 1744@item \b @tab Backspace character (@acronym{ASCII} 8)
1737example below: 1745@item \f @tab Form-feed character (@acronym{ASCII} 12)
1746@item \n @tab Newline character (@acronym{ASCII} 10)
1747@item \r @tab Carriage return character (@acronym{ASCII} 13)
1748@item \t @tab Horizontal tabulation character (@acronym{ASCII} 9)
1749@item \v @tab Vertical tabulation character (@acronym{ASCII} 11)
1750@item \\ @tab Single slash
1751@item \" @tab Double quote
1752@end multitable
1753@end float
1754
1755In addition, a backslash immediately followed by the end-of-line
1756character effectively removes that character, allowing to split long
1757arguments over several input lines.
1758
1759Command parameters may be optional or mandatory. If the number of
1760actual arguments is less than the number of mandatory parameters,
1761@command{gdbmtool} will prompt you to supply missing arguments. For
1762example, the @samp{store} command takes two mandatory parameters, so
1763if you invoked it with no arguments, you would be prompted twice to
1764supply the necessary data, as shown in example below:
1738 1765
1739@example 1766@example
1740gdbmtool> @kbd{store} 1767gdbmtool> @kbd{store}
1741key> @kbd{three} 1768key? @kbd{three}
1742data> @kbd{3} 1769data? @kbd{3}
1743@end example 1770@end example
1744 1771
1745However, such prompting is possible only in interactive mode. In 1772However, 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
1747be supplied with each command, otherwise @command{gdbmtool} will report an 1774be supplied with each command, otherwise @command{gdbmtool} will report an
1748error and exit immediately. 1775error and exit immediately.
1749 1776
1750@anchor{pager} 1777@menu
1751@cindex pager, @command{gdbmtool} 1778* variables:: shell variables.
1752@cindex @env{PAGER} 1779* commands:: shell commands.
1753Some commands produce excessive amounts of output. To help you follow 1780* definitions:: how to define structured data.
1754it, @command{gdbmtool} uses a pager utility to display such 1781* startup files::
1755output. The name of the pager utility is taken from the environment 1782@end menu
1756variable @env{PAGER}. The pager is invoked only in interactive mode 1783
1757and only if the estimated number of output lines is greater then the 1784@node variables
1758number of lines on your screen. 1785@subsection Shell Variables
1759 1786@cindex variables, gdbmtool
1760@anchor{nul-termination} 1787A number of @command{gdbmtool} parameters is kept in its internal
1761Many of the @command{gdbmtool} commands operate on database key and 1788variables.
1762data values. The utility assumes that both keys and data are 1789
1763@acronym{ASCII} strings, either nul-terminated or not. By default, 1790@deftypevr {gdbmtool variable} bool confirm
1764it is assumed that strings are nul-terminated. You can change this 1791Whether to ask for confirmation before certain destructive operations,
1765by using @code{z} (@code{key-zero}, for keys) and @code{Z} 1792such as truncating the existing database.
1766(@code{data-zero}, for data) commands. 1793
1767 1794Default is @samp{true}.
1768The following table summarizes all available commands: 1795@end deftypevr
1796
1797@deftypevr {gdbmtool variable} string ps1
1798Primary prompt string. Its value can contain @dfn{conversion
1799specifiers}, consisting of the @samp{%} character followed by another
1800character. These specifiers are expanded in the resulting prompt as
1801follows:
1802
1803@multitable @columnfractions 0.4 0.5
1804@headitem Sequence @tab Expansion
1805@item %f @tab name of the current database file
1806@item %p @tab program invocation name
1807@item %P @tab package name (@samp{GDBM})
1808@item %v @tab program version
1809@item %_ @tab single space character
1810@item %% @tab %
1811@end multitable
1812
1813The default value is @samp{%p>%_}, i.e. the program name, followed by
1814a ``greater than'' sign, followed by a single space.
1815@end deftypevr
1816
1817@deftypevr {gdbmtool variable} string ps2
1818Secondary prompt. See @samp{ps1} for a description of its value.
1819This prompt is displayed before reading the second and subsequent
1820lines of a multi-line command.
1821
1822The default value is @samp{%_>%_}.
1823@end deftypevr
1824
1825@deftypevr {gdbmtool variable} string delim1
1826A string used to delimit fields of a structured datum on output
1827(@pxref{definitions}).
1828
1829Default is @samp{,} (a comma). This variable cannot be unset.
1830@end deftypevr
1831
1832@deftypevr {gdbmtool variable} string delim2
1833A string used to delimit array items when printing a structured datum
1834(@pxref{definitions}).
1835
1836Default is @samp{,} (a comma). This variable cannot be unset.
1837@end deftypevr
1838
1839@deftypevr {gdbmtool variable} string pager
1840The name and command line of the pager program to pipe output to.
1841This program is used in interactive mode when the estimated number of
1842output lines is greater then the number of lines on your screen.
1843
1844The default value is inherited from the environment variable
1845@env{PAGER}. Unsetting this variable disables paging.
1846@end deftypevr
1847
1848@anchor{quiet}
1849@deftypevr {gdbmtool variable} bool quiet
1850Whether to display a welcome banner at startup. This variable should
1851be set in a startup script file (@pxref{startup files}).
1852@xref{-q option}.
1853@end deftypevr