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