diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2013-05-08 16:27:01 +0000 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2013-05-08 16:27:01 +0000 |
commit | 6658f41e38fec9e007a0fbd0883e030f6337e28d (patch) | |
tree | d7ecc0b72b23a01a2bfa10e8a7bb184d704269dc /doc/gdbm.texinfo | |
parent | c0cba983ab0c0bc1de630a200f902189ddddff09 (diff) | |
download | gdbm-6658f41e38fec9e007a0fbd0883e030f6337e28d.tar.gz gdbm-6658f41e38fec9e007a0fbd0883e030f6337e28d.tar.bz2 |
Rename testgdbm to gdbmtool. Improve documentation.
* configure.ac: Fix a typo.
* src/.cvsignore: Add gdbmtool
* src/Makefile.am: Rename testgdbm to gdbmtool. Source
file not renamed because of CVS deficiency.
* src/gdbm_dump.c: Enable NLS.
* src/gdbm_load.c: Likewise.
* src/testgdbm.c: New option -q (--quiet).
New command: prompt.
* doc/Makefile.am (man_MANS): Add new manpages.
* doc/gdbmtool.1: New file.
* doc/gdbm_load.1: New file.
* doc/gdbm_dump.1: New file.
* doc/gdbm.3: Update.
* doc/gdbm.texinfo: Update.
Diffstat (limited to 'doc/gdbm.texinfo')
-rw-r--r-- | doc/gdbm.texinfo | 134 |
1 files changed, 65 insertions, 69 deletions
diff --git a/doc/gdbm.texinfo b/doc/gdbm.texinfo index 9f0af5b..17f47f9 100644 --- a/doc/gdbm.texinfo +++ b/doc/gdbm.texinfo | |||
@@ -120,3 +120,3 @@ Programs | |||
120 | 120 | ||
121 | * testgdbm:: Test and modify a GDBM database. | 121 | * gdbmtool:: Examine and modify a GDBM database. |
122 | * gdbm_dump:: Dump the database into a flat file. | 122 | * gdbm_dump:: Dump the database into a flat file. |
@@ -1619,10 +1619,10 @@ never free it. | |||
1619 | 1619 | ||
1620 | @node testgdbm | 1620 | @node gdbmtool |
1621 | @chapter Test and modify a GDBM database. | 1621 | @chapter Examine and modify a GDBM database. |
1622 | @prindex testgdbm | 1622 | @prindex gdbmtool |
1623 | 1623 | ||
1624 | The @command{testgdbm} utility allows you to view and modify an | 1624 | The @command{gdbmtool} utility allows you to view and modify an |
1625 | existing @acronym{GDBM} database or to create a new one. | 1625 | existing @acronym{GDBM} database or to create a new one. |
1626 | 1626 | ||
1627 | @cindex default database, @command{testgdbm} | 1627 | @cindex default database, @command{gdbmtool} |
1628 | @flindex junk.gdbm | 1628 | @flindex junk.gdbm |
@@ -1631,11 +1631,11 @@ When invoked without arguments, it tries to open a database file called | |||
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{testgdbm}, e.g.: | 1632 | the only argument to @command{gdbmtool}, e.g.: |
1633 | 1633 | ||
1634 | @example | 1634 | @example |
1635 | $ testgdbm file.db | 1635 | $ gdbmtool file.db |
1636 | @end example | 1636 | @end example |
1637 | 1637 | ||
1638 | @cindex read-only mode, @command{testgdbm} | 1638 | @cindex read-only mode, @command{gdbmtool} |
1639 | @cindex @option{-r}, @command{testgdbm} option | 1639 | @cindex @option{-r}, @command{gdbmtool} option |
1640 | @cindex @option{--read-only}, @command{testgdbm} option | 1640 | @cindex @option{--read-only}, @command{gdbmtool} option |
1641 | The database will be opened in read-write mode, unless the | 1641 | The database will be opened in read-write mode, unless the |
@@ -1644,6 +1644,6 @@ it will be opened only for reading. | |||
1644 | 1644 | ||
1645 | @cindex creating a database, @command{testgdbm} | 1645 | @cindex creating a database, @command{gdbmtool} |
1646 | @cindex @option{-n}, @command{testgdbm} option | 1646 | @cindex @option{-n}, @command{gdbmtool} option |
1647 | @cindex @option{--newdb}, @command{testgdbm} option | 1647 | @cindex @option{--newdb}, @command{gdbmtool} option |
1648 | If the database does not exist, @command{testgdbm} will create it. | 1648 | If the database does not exist, @command{gdbmtool} will create it. |
1649 | There is a special option @option{-n} (@option{--newdb}, which | 1649 | There is a special option @option{-n} (@option{--newdb}, which |
@@ -1658,6 +1658,6 @@ the database already exists, it will be deleted, so use it sparingly. | |||
1658 | @node invocation | 1658 | @node invocation |
1659 | @section testgdbm invocation | 1659 | @section gdbmtool invocation |
1660 | @cindex command line options, @command{testgdbm} | 1660 | @cindex command line options, @command{gdbmtool} |
1661 | 1661 | ||
1662 | The following table summarizes all @command{testgdbm} command line | 1662 | The following table summarizes all @command{gdbmtool} command line |
1663 | options: | 1663 | options: |
@@ -1683,2 +1683,5 @@ Disable file locking. | |||
1683 | Disable mmap. | 1683 | Disable mmap. |
1684 | @item -q | ||
1685 | @itemx --quiet | ||
1686 | Don't print the usual welcome banner at startup. | ||
1684 | @item -r | 1687 | @item -r |
@@ -1698,9 +1701,9 @@ command line options. | |||
1698 | @node shell | 1701 | @node shell |
1699 | @section testgdbm interactive mode | 1702 | @section gdbmtool interactive mode |
1700 | @cindex interactive mode, @command{testgdbm} | 1703 | @cindex interactive mode, @command{gdbmtool} |
1701 | 1704 | ||
1702 | After successful startup, @command{testgdbm} starts a loop, in which | 1705 | After successful startup, @command{gdbmtool} starts a loop, in which |
1703 | it reads commands from the user, executes them and prints the results | 1706 | it reads commands from the user, executes them and prints the results |
1704 | on the standard output. If the standard input is attached to a console, | 1707 | on the standard output. If the standard input is attached to a console, |
1705 | @command{testgdbm} runs in interactive mode, which is indicated by its | 1708 | @command{gdbmtool} runs in interactive mode, which is indicated by its |
1706 | @dfn{prompt}: | 1709 | @dfn{prompt}: |
@@ -1708,3 +1711,3 @@ on the standard output. If the standard input is attached to a console, | |||
1708 | @example | 1711 | @example |
1709 | testgdbm> _ | 1712 | gdbmtool> _ |
1710 | @end example | 1713 | @end example |
@@ -1714,3 +1717,3 @@ detects end-of-file on its standard input, whichever occurs first. | |||
1714 | 1717 | ||
1715 | A @command{testgdbm} command consists of a @dfn{command verb}, | 1718 | A @command{gdbmtool} command consists of a @dfn{command verb}, |
1716 | optionally followed by one or two @dfn{arguments}, separated by any | 1719 | optionally followed by one or two @dfn{arguments}, separated by any |
@@ -1729,3 +1732,3 @@ Each command takes at most two @dfn{formal parameters}, which can be | |||
1729 | optional or mandatory. If the number of actual arguments is less than the | 1732 | optional or mandatory. If the number of actual arguments is less than the |
1730 | number of mandatory parameters, @command{testgdbm} will prompt you to | 1733 | number of mandatory parameters, @command{gdbmtool} will prompt you to |
1731 | supply missing arguments. For example, the @samp{store} command takes two | 1734 | supply missing arguments. For example, the @samp{store} command takes two |
@@ -1736,3 +1739,3 @@ example below: | |||
1736 | @example | 1739 | @example |
1737 | testgdbm> @kbd{store} | 1740 | gdbmtool> @kbd{store} |
1738 | key> @kbd{three} | 1741 | key> @kbd{three} |
@@ -1743,3 +1746,3 @@ However, such prompting is possible only in interactive mode. In | |||
1743 | non-interactive mode (e.g.@: when running a script), all arguments must | 1746 | non-interactive mode (e.g.@: when running a script), all arguments must |
1744 | be supplied with each command, otherwise @command{testgdbm} will report an | 1747 | be supplied with each command, otherwise @command{gdbmtool} will report an |
1745 | error and exit immediately. | 1748 | error and exit immediately. |
@@ -1747,6 +1750,6 @@ error and exit immediately. | |||
1747 | @anchor{pager} | 1750 | @anchor{pager} |
1748 | @cindex pager, @command{testgdbm} | 1751 | @cindex pager, @command{gdbmtool} |
1749 | @cindex @env{PAGER} | 1752 | @cindex @env{PAGER} |
1750 | Some commands produce excessive amounts of output. To help you follow | 1753 | Some commands produce excessive amounts of output. To help you follow |
1751 | it, @command{testgdbm} uses a pager utility to display such | 1754 | it, @command{gdbmtool} uses a pager utility to display such |
1752 | output. The name of the pager utility is taken from the environment | 1755 | output. The name of the pager utility is taken from the environment |
@@ -1757,3 +1760,3 @@ number of lines on your screen. | |||
1757 | @anchor{nul-termination} | 1760 | @anchor{nul-termination} |
1758 | Many of the @command{testgdbm} commands operate on database key and | 1761 | Many of the @command{gdbmtool} commands operate on database key and |
1759 | data values. The utility assumes that both keys and data are | 1762 | data values. The utility assumes that both keys and data are |
@@ -1767,3 +1770,2 @@ The following table summarizes all available commands: | |||
1767 | @deffn {command verb} count | 1770 | @deffn {command verb} count |
1768 | @deffnx {command abbrev} co | ||
1769 | @deffnx {command letter} c | 1771 | @deffnx {command letter} c |
@@ -1773,16 +1775,15 @@ Print the number of entries in the database. | |||
1773 | @deffn {command verb} delete @var{key} | 1775 | @deffn {command verb} delete @var{key} |
1774 | @deffnx {command abbrev} de @var{key} | ||
1775 | @deffnx {command letter} d @var{key} | 1776 | @deffnx {command letter} d @var{key} |
1776 | Delete entry with a given @var{key} | 1777 | Delete entry with the given @var{key} |
1777 | @end deffn | 1778 | @end deffn |
1778 | 1779 | ||
1779 | @anchor{testgdbm export} | 1780 | @anchor{gdbmtool export} |
1780 | @deffn {command verb} export @var{file-name} [truncate] [binary|ascii] | 1781 | @deffn {command verb} export @var{file-name} [truncate] [binary|ascii] |
1781 | @deffnx {command abbrev} e @var{file-name} [truncate] [binary|ascii] | 1782 | @deffnx {command letter} e @var{file-name} [truncate] [binary|ascii] |
1782 | Export the database to the flat file @var{file-name}. @xref{Flat files}, | 1783 | Export the database to the flat file @var{file-name}. @xref{Flat files}, |
1783 | for a description of the flat file format and its purposes. This | 1784 | for a description of the flat file format and its purposes. This |
1784 | command will not overwrite an existing file, unless the argument | 1785 | command will not overwrite an existing file, unless the |
1785 | @samp{truncate} is also given. Another optional argument determines | 1786 | @samp{truncate} parameter is also given. Another optional argument |
1786 | the type of dump (@pxref{Flat files}). By default, ASCII dump is | 1787 | determines the type of the dump (@pxref{Flat files}). By default, ASCII |
1787 | created. | 1788 | dump is created. |
1788 | 1789 | ||
@@ -1792,10 +1793,9 @@ See also @ref{gdbmexport}. | |||
1792 | @deffn {command verb} fetch @var{key} | 1793 | @deffn {command verb} fetch @var{key} |
1793 | @deffnx {command abbrev} fe @var{key} | ||
1794 | @deffnx {command letter} f @var{key} | 1794 | @deffnx {command letter} f @var{key} |
1795 | Fetch and display a record with the given @var{key}. | 1795 | Fetch and display the record with the given @var{key}. |
1796 | @end deffn | 1796 | @end deffn |
1797 | 1797 | ||
1798 | @anchor{testgdbm import} | 1798 | @anchor{gdbmtool import} |
1799 | @deffn {command verb} import @var{file-name} [replace] [nometa] | 1799 | @deffn {command verb} import @var{file-name} [replace] [nometa] |
1800 | @deffnx {command abbrev} i @var{file-name} [replace] [nometa] | 1800 | @deffnx {command letter} i @var{file-name} [replace] [nometa] |
1801 | Import data from a flat dump file @var{file-name} | 1801 | Import data from a flat dump file @var{file-name} |
@@ -1808,3 +1808,3 @@ restoring meta-information from the dump file. | |||
1808 | @deffn {command verb} list | 1808 | @deffn {command verb} list |
1809 | @deffnx {command abbrev} l | 1809 | @deffnx {command letter} l |
1810 | List the contents of the database (@pxref{pager}). | 1810 | List the contents of the database (@pxref{pager}). |
@@ -1813,7 +1813,5 @@ List the contents of the database (@pxref{pager}). | |||
1813 | @deffn {command verb} next [@var{key}] | 1813 | @deffn {command verb} next [@var{key}] |
1814 | @deffnx {command abbrev} n [@var{key}] | 1814 | @deffnx {command letter} n [@var{key}] |
1815 | Sequential access: fetch and display a next record. If @var{key} is | 1815 | Sequential access: fetch and display the next record. If the @var{key} is |
1816 | given, a record following one with this key will be fetched. | 1816 | given, the record following the one with this key will be fetched. |
1817 | Otherwise, the key supplied by the latest @code{1}, @code{2} or | ||
1818 | @var{n} command will be used. | ||
1819 | 1817 | ||
@@ -1824,4 +1822,17 @@ See also @code{first}, below. | |||
1824 | 1822 | ||
1823 | @deffn {command verb} prompt @var{text} | ||
1824 | Changes the command prompt to the string @var{text}. The string can | ||
1825 | contain @dfn{escape sequences}, the special entities consisting of the | ||
1826 | @samp{%} character followed by another character. These sequences are | ||
1827 | replaced in the generated prompt as follows: | ||
1828 | |||
1829 | @multitable @columnfractions 0.4 0.5 | ||
1830 | @headitem Sequence @tab Expansion | ||
1831 | @item %f @tab name of the db file | ||
1832 | @item %% @tab % | ||
1833 | @end multitable | ||
1834 | @end deffn | ||
1835 | |||
1825 | @deffn {command verb} quit | 1836 | @deffn {command verb} quit |
1826 | @deffnx {command abbrev} q | 1837 | @deffnx {command letter} q |
1827 | Close the database and quit the utility. | 1838 | Close the database and quit the utility. |
@@ -1830,3 +1841,2 @@ Close the database and quit the utility. | |||
1830 | @deffn {command verb} store @var{key} @var{data} | 1841 | @deffn {command verb} store @var{key} @var{data} |
1831 | @deffnx {command abbrev} sto @var{key} @var{data} | ||
1832 | @deffnx {command letter} s @var{key} @var{data} | 1842 | @deffnx {command letter} s @var{key} @var{data} |
@@ -1837,6 +1847,5 @@ already exists, its data will be replaced. | |||
1837 | @deffn {command verb} first | 1847 | @deffn {command verb} first |
1838 | @deffnx {command abbrev} fi | ||
1839 | @deffnx {command letter} 1 | 1848 | @deffnx {command letter} 1 |
1840 | Fetch and display the first record in the database. Subsequent | 1849 | Fetch and display the first record in the database. Subsequent |
1841 | records can be fetched using @code{next} command (see above). | 1850 | records can be fetched using the @code{next} command (see above). |
1842 | @xref{Sequential}, for more information on sequential access. | 1851 | @xref{Sequential}, for more information on sequential access. |
@@ -1845,7 +1854,6 @@ records can be fetched using @code{next} command (see above). | |||
1845 | @deffn {command verb} read @var{file} [replace] | 1854 | @deffn {command verb} read @var{file} [replace] |