diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2011-11-14 21:59:38 +0000 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2011-11-14 21:59:38 +0000 |
commit | 4931e4393ebff15289ad282f3d3dd0fba4999986 (patch) | |
tree | 1386373cfd7c8723fe7eea0a3381c2c604280b10 /doc/gdbm.texinfo | |
parent | 91751b0ce995e2b3b73fd60d4dbeade3cc4de123 (diff) | |
download | gdbm-4931e4393ebff15289ad282f3d3dd0fba4999986.tar.gz gdbm-4931e4393ebff15289ad282f3d3dd0fba4999986.tar.bz2 |
Document new flat format and related functions.
Diffstat (limited to 'doc/gdbm.texinfo')
-rw-r--r-- | doc/gdbm.texinfo | 144 |
1 files changed, 75 insertions, 69 deletions
diff --git a/doc/gdbm.texinfo b/doc/gdbm.texinfo index fcbc14e..4dcdd76 100644 --- a/doc/gdbm.texinfo +++ b/doc/gdbm.texinfo | |||
@@ -3,12 +3,14 @@ | |||
3 | @comment %**start of header (This is for running Texinfo on a region.) | 3 | @comment %**start of header (This is for running Texinfo on a region.) |
4 | @setfilename gdbm.info | 4 | @setfilename gdbm.info |
5 | @include version.texi | 5 | @include version.texi |
6 | @settitle gdbm manual | 6 | @settitle GDBM manual |
7 | 7 | ||
8 | @ifinfo | 8 | @ifinfo |
9 | @dircategory Programming & development tools | 9 | @dircategory Programming & development tools |
10 | @direntry | 10 | @direntry |
11 | * GDBM: (gdbm). The GNU database manager. | 11 | * GDBM: (gdbm). The GNU database manager. |
12 | * gdbm_dump: gdbm_dump(gdbm). Dump the GDBM database into a flat file. | ||
13 | * gdbm_load: gdbm_load(gdbm). Load the database from a flat file. | ||
12 | @end direntry | 14 | @end direntry |
13 | @end ifinfo | 15 | @end ifinfo |
14 | 16 | ||
@@ -21,6 +23,9 @@ | |||
21 | @c Use @flindex for files | 23 | @c Use @flindex for files |
22 | @defcodeindex fl | 24 | @defcodeindex fl |
23 | @syncodeindex fl cp | 25 | @syncodeindex fl cp |
26 | @c Use @prindex for programs | ||
27 | @defcodeindex pr | ||
28 | @syncodeindex pr cp | ||
24 | 29 | ||
25 | @c Merge all indices into a single one | 30 | @c Merge all indices into a single one |
26 | @syncodeindex fn cp | 31 | @syncodeindex fn cp |
@@ -34,21 +39,18 @@ | |||
34 | @end iftex | 39 | @end iftex |
35 | 40 | ||
36 | @copying | 41 | @copying |
37 | This file documents the GNU dbm utility. | 42 | Published by the Free Software Foundation, |
43 | 51 Franklin Street, Fifth Floor | ||
44 | Boston, MA 02110-1301, USA | ||
38 | 45 | ||
39 | Copyright @copyright{} 1989-1999, 2007, 2008, 2009-2011 Free Software Foundation, Inc. | 46 | Copyright @copyright{} 1989-1999, 2007-2011 Free Software Foundation, Inc. |
40 | 47 | ||
41 | Permission is granted to copy, distribute and/or modify this document | 48 | Permission is granted to copy, distribute and/or modify this document |
42 | under the terms of the GNU Free Documentation License, Version 1.3 or | 49 | under the terms of the GNU Free Documentation License, Version 1.3 or |
43 | any later version published by the Free Software Foundation; with no | 50 | any later version published by the Free Software Foundation; with no |
44 | Invariant Sections, with the Front-Cover Texts being ``The GNU Database | 51 | Invariant Sections, no Front-Cover, and no Back-Cover texts. |
45 | Manager,'' and with the Back-Cover Texts as in (a) below. A copy of the | 52 | A copy of the license is included in the section entitled ``GNU Free |
46 | license is included in the section entitled ``GNU Free Documentation | 53 | Documentation License.'' |
47 | License.'' | ||
48 | |||
49 | (a) The FSF's Back-Cover Text is: ``You have the freedom to | ||
50 | copy and modify this GNU manual. Buying copies from the FSF | ||
51 | supports it in developing GNU and promoting software freedom.'' | ||
52 | @end copying | 54 | @end copying |
53 | 55 | ||
54 | @titlepage | 56 | @titlepage |
@@ -67,32 +69,8 @@ supports it in developing GNU and promoting software freedom.'' | |||
67 | @center for GNU @code{dbm}, Version @value{VERSION} | 69 | @center for GNU @code{dbm}, Version @value{VERSION} |
68 | @page | 70 | @page |
69 | @vskip 0pt plus 1filll | 71 | @vskip 0pt plus 1filll |
70 | Copyright @copyright{} 1993-1999, 2007-2011 Free Software Foundation, Inc. | 72 | @insertcopying |
71 | @sp 2 | ||
72 | |||
73 | This is Edition @value{EDITION} of the @cite{GNU @code{dbm} Manual}, | ||
74 | for @code{gdbm} Version @value{VERSION}. @* | ||
75 | Last updated @value{UPDATED} | ||
76 | |||
77 | Published by the Free Software Foundation @* | ||
78 | 675 Massachusetts Avenue, @* | ||
79 | Cambridge, MA 02139 USA @* | ||
80 | |||
81 | Permission is granted to make and distribute verbatim copies of | ||
82 | this manual provided the copyright notice and this permission notice | ||
83 | are preserved on all copies. | ||
84 | |||
85 | Permission is granted to copy and distribute modified versions of this | ||
86 | manual under the conditions for verbatim copying, provided also that | ||
87 | the entire resulting derived work is distributed under the terms of a | ||
88 | permission notice identical to this one. | ||
89 | |||
90 | Permission is granted to copy and distribute translations of this manual | ||
91 | into another language, under the above conditions for modified versions, | ||
92 | except that this permission notice may be stated in a translation approved | ||
93 | by the Free Software Foundation. | ||
94 | @end titlepage | 73 | @end titlepage |
95 | @page | ||
96 | 74 | ||
97 | @ifnothtml | 75 | @ifnothtml |
98 | @page | 76 | @page |
@@ -107,9 +85,9 @@ by the Free Software Foundation. | |||
107 | 85 | ||
108 | GNU @code{dbm} is a library of functions implementing a hashed database | 86 | GNU @code{dbm} is a library of functions implementing a hashed database |
109 | on a disk file. This manual documents GNU @code{dbm} Version @value{VERSION} | 87 | on a disk file. This manual documents GNU @code{dbm} Version @value{VERSION} |
110 | (@code{gdbm}). The software was originally written by Philip A. Nelson. This | 88 | (@code{gdbm}). The software was originally written by Philip A.@: |
111 | document was originally written by Pierre Gaumond from texts written by | 89 | Nelson. This document was originally written by Pierre Gaumond from |
112 | Phil. | 90 | texts written by Phil. |
113 | @end ifnottex | 91 | @end ifnottex |
114 | 92 | ||
115 | @menu | 93 | @menu |
@@ -136,7 +114,9 @@ Functions: | |||
136 | 114 | ||
137 | Programs | 115 | Programs |
138 | 116 | ||
139 | * testgdbm:: Test and modify a GDBM database. | 117 | * testgdbm:: Test and modify a GDBM database. |
118 | * gdbm_dump:: Dump the database into a flat file. | ||
119 | * gdbm_load:: Load the database from a flat file. | ||
140 | * gdbmexport:: Export a database into a portable format. | 120 | * gdbmexport:: Export a database into a portable format. |
141 | 121 | ||
142 | Other topics: | 122 | Other topics: |
@@ -651,8 +631,12 @@ immediately after the set of changes have been made. | |||
651 | @cindex Flat file format | 631 | @cindex Flat file format |
652 | @cindex export | 632 | @cindex export |
653 | @cindex import | 633 | @cindex import |
654 | @code{Gdbm} databases can be converted into a portable @dfn{flat | 634 | @code{Gdbm} databases can be converted into so-called @dfn{flat |
655 | format}. This format can be used, for example, to migrate between | 635 | format} files. Such files cannot be used for searching, their sole |
636 | purpose is to keep the data from the database for restoring it when | ||
637 | the need arrives. There are two flat file formats, which differ in | ||
638 | the way they represent the data and in the amount of meta-information | ||
639 | stored. Both formats can be used, for example, to migrate between | ||
656 | the different versions of @code{gdbm} databases. Generally speaking, | 640 | the different versions of @code{gdbm} databases. Generally speaking, |
657 | flat files are safe to send over the network, and can be used to | 641 | flat files are safe to send over the network, and can be used to |
658 | recreate the database on another machine. The recreated database is | 642 | recreate the database on another machine. The recreated database is |
@@ -669,14 +653,25 @@ binary databases are not portable between machines, unless you follow | |||
669 | some stringent rules on what data is written to them and how it is | 653 | some stringent rules on what data is written to them and how it is |
670 | interpreted. | 654 | interpreted. |
671 | 655 | ||
672 | GDBM version @value{VERSION} supports two flat file formats. The | 656 | The GDBM version @value{VERSION} supports two flat file formats. The |
673 | @dfn{binary} flat file, as its name implies, keeps data in binary | 657 | @dfn{binary} flat file format was first implemented in GDBM version |
674 | form. The @dfn{ascii} flat file, on the other hand, encodes all data | 658 | 1.9.1. This format stores only key/data pairs, it does not keep |
675 | in base64 and can be sent over transmission channels that normally | 659 | information about the database file itself. As its name implies, |
676 | allow only ASCII data, such as, e.g.@: SMTP. Apart from that, ASCII | 660 | files in this format are binary files. |
677 | flat files contain original database file metadata (file name, mode | 661 | |
678 | and ownership), and can therefore be used to restore an exact copy of | 662 | The @dfn{ascii} flat file format encodes all data in base64 and stores |
679 | the database. | 663 | not only key/data pairs, but also the original database file metadata, |
664 | such as file name, mode and ownership. Files in this format can be | ||
665 | sent without additional encapsulation over transmission channels that | ||
666 | normally allow only ASCII data, such as, e.g.@: SMTP. Due to additional | ||
667 | metadata they allow for restoring an exact copy of the database, | ||
668 | including file ownership and privileges, which is especially important | ||
669 | if the database in question contained some security-related data. | ||
670 | |||
671 | We call a process of creating a flat file from a database | ||
672 | @dfn{exporting} or @dfn{dumping} this database. The reverse process, | ||
673 | creating the database from a flat file is called @dfn{importing} or | ||
674 | @dfn{loading} the database. | ||
680 | 675 | ||
681 | @deftypefn {gdbm interface} int gdbm_dump (GDBM_FILE @var{dbf}, @ | 676 | @deftypefn {gdbm interface} int gdbm_dump (GDBM_FILE @var{dbf}, @ |
682 | const char *@var{filename}, int @var{format}, @ | 677 | const char *@var{filename}, int @var{format}, @ |
@@ -693,7 +688,7 @@ A pointer to the source database, returned by a prior call to | |||
693 | Name of the dump file. | 688 | Name of the dump file. |
694 | 689 | ||
695 | @item format | 690 | @item format |
696 | Dump format. Allowed values are: @samp{GDBM_DUMP_FMT_BINARY} to | 691 | Output file format. Allowed values are: @samp{GDBM_DUMP_FMT_BINARY} to |
697 | create a binary dump and @samp{GDBM_DUMP_FMT_ASCII} to create an ASCII | 692 | create a binary dump and @samp{GDBM_DUMP_FMT_ASCII} to create an ASCII |
698 | dump file. | 693 | dump file. |
699 | 694 | ||
@@ -723,8 +718,8 @@ for a detailed discussion. | |||
723 | Loads data from the dump file @var{filename} into the database pointed | 718 | Loads data from the dump file @var{filename} into the database pointed |
724 | to by @var{pdbf}. The latter can point to @samp{NULL}, in which case | 719 | to by @var{pdbf}. The latter can point to @samp{NULL}, in which case |
725 | the function will try to create a new database. If it succeeds, the | 720 | the function will try to create a new database. If it succeeds, the |
726 | function will return a pointer to the newly created database in the | 721 | function will return, in the memory location pointed to by @var{pdbf}, |
727 | memory location pointed to by @var{pdbf}. If the dump file carries no | 722 | a pointer to the newly created database. If the dump file carries no |
728 | information about the original database file name, the function will | 723 | information about the original database file name, the function will |
729 | set @code{gdbm_errno} to @samp{GDBM_NO_DBNAME} and return | 724 | set @code{gdbm_errno} to @samp{GDBM_NO_DBNAME} and return |
730 | @samp{-1}, indicating failure. | 725 | @samp{-1}, indicating failure. |
@@ -812,8 +807,9 @@ following construct: | |||
812 | 807 | ||
813 | @example | 808 | @example |
814 | @var{dbf} = gdbm_open (@var{importfile}, 0, | 809 | @var{dbf} = gdbm_open (@var{importfile}, 0, |
815 | @var{flag} == GDBM_REPLACE ? GDBM_WRCREAT : | 810 | @var{flag} == GDBM_REPLACE ? |
816 | GDBM_NEWDB, 0600, NULL); | 811 | GDBM_WRCREAT : GDBM_NEWDB, |
812 | 0600, NULL); | ||
817 | gdbm_load (&@var{dbf}, @var{exportfile}, GDBM_DUMP_FMT_BINARY, | 813 | gdbm_load (&@var{dbf}, @var{exportfile}, GDBM_DUMP_FMT_BINARY, |
818 | @var{flag}, NULL) | 814 | @var{flag}, NULL) |
819 | @end example | 815 | @end example |
@@ -853,7 +849,7 @@ The parameters are: | |||
853 | @item dbf | 849 | @item dbf |
854 | The pointer returned by @code{gdbm_open}. | 850 | The pointer returned by @code{gdbm_open}. |
855 | @item option | 851 | @item option |
856 | The option to be set or retreived. | 852 | The option to be set or retrieved. |
857 | @item value | 853 | @item value |
858 | A pointer to the value to which @var{option} will be set or where to |