summaryrefslogtreecommitdiffabout
path: root/doc
authorSergey Poznyakoff <gray@gnu.org.ua>2011-11-14 21:59:38 (GMT)
committer Sergey Poznyakoff <gray@gnu.org.ua>2011-11-14 21:59:38 (GMT)
commit4931e4393ebff15289ad282f3d3dd0fba4999986 (patch) (unidiff)
tree1386373cfd7c8723fe7eea0a3381c2c604280b10 /doc
parent91751b0ce995e2b3b73fd60d4dbeade3cc4de123 (diff)
downloadgdbm-4931e4393ebff15289ad282f3d3dd0fba4999986.tar.gz
gdbm-4931e4393ebff15289ad282f3d3dd0fba4999986.tar.bz2
Document new flat format and related functions.
Diffstat (limited to 'doc') (more/less context) (ignore whitespace changes)
-rw-r--r--doc/gdbm.texinfo144
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
37This file documents the GNU dbm utility. 42Published by the Free Software Foundation,
4351 Franklin Street, Fifth Floor
44Boston, MA 02110-1301, USA
38 45
39Copyright @copyright{} 1989-1999, 2007, 2008, 2009-2011 Free Software Foundation, Inc. 46Copyright @copyright{} 1989-1999, 2007-2011 Free Software Foundation, Inc.
40 47
41Permission is granted to copy, distribute and/or modify this document 48Permission is granted to copy, distribute and/or modify this document
42under the terms of the GNU Free Documentation License, Version 1.3 or 49under the terms of the GNU Free Documentation License, Version 1.3 or
43any later version published by the Free Software Foundation; with no 50any later version published by the Free Software Foundation; with no
44Invariant Sections, with the Front-Cover Texts being ``The GNU Database 51Invariant Sections, no Front-Cover, and no Back-Cover texts.
45Manager,'' and with the Back-Cover Texts as in (a) below. A copy of the 52A copy of the license is included in the section entitled ``GNU Free
46license is included in the section entitled ``GNU Free Documentation 53Documentation License.''
47License.''
48
49(a) The FSF's Back-Cover Text is: ``You have the freedom to
50copy and modify this GNU manual. Buying copies from the FSF
51supports 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
70Copyright @copyright{} 1993-1999, 2007-2011 Free Software Foundation, Inc. 72@insertcopying
71@sp 2
72
73This is Edition @value{EDITION} of the @cite{GNU @code{dbm} Manual},
74for @code{gdbm} Version @value{VERSION}. @*
75Last updated @value{UPDATED}
76
77Published by the Free Software Foundation @*
78675 Massachusetts Avenue, @*
79Cambridge, MA 02139 USA @*
80
81Permission is granted to make and distribute verbatim copies of
82this manual provided the copyright notice and this permission notice
83are preserved on all copies.
84
85Permission is granted to copy and distribute modified versions of this
86manual under the conditions for verbatim copying, provided also that
87the entire resulting derived work is distributed under the terms of a
88permission notice identical to this one.
89
90Permission is granted to copy and distribute translations of this manual
91into another language, under the above conditions for modified versions,
92except that this permission notice may be stated in a translation approved
93by 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
108GNU @code{dbm} is a library of functions implementing a hashed database 86GNU @code{dbm} is a library of functions implementing a hashed database
109on a disk file. This manual documents GNU @code{dbm} Version @value{VERSION} 87on 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.@:
111document was originally written by Pierre Gaumond from texts written by 89Nelson. This document was originally written by Pierre Gaumond from
112Phil. 90texts written by Phil.
113@end ifnottex 91@end ifnottex
114 92
115@menu 93@menu
@@ -136,7 +114,9 @@ Functions:
136 114
137Programs 115Programs
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
142Other topics: 122Other 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
655format}. This format can be used, for example, to migrate between 635format} files. Such files cannot be used for searching, their sole
636purpose is to keep the data from the database for restoring it when
637the need arrives. There are two flat file formats, which differ in
638the way they represent the data and in the amount of meta-information
639stored. Both formats can be used, for example, to migrate between
656the different versions of @code{gdbm} databases. Generally speaking, 640the different versions of @code{gdbm} databases. Generally speaking,
657flat files are safe to send over the network, and can be used to 641flat files are safe to send over the network, and can be used to
658recreate the database on another machine. The recreated database is 642recreate the database on another machine. The recreated database is
@@ -669,14 +653,25 @@ binary databases are not portable between machines, unless you follow
669some stringent rules on what data is written to them and how it is 653some stringent rules on what data is written to them and how it is
670interpreted. 654interpreted.
671 655
672GDBM version @value{VERSION} supports two flat file formats. The 656The 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
674form. The @dfn{ascii} flat file, on the other hand, encodes all data 6581.9.1. This format stores only key/data pairs, it does not keep
675in base64 and can be sent over transmission channels that normally 659information about the database file itself. As its name implies,
676allow only ASCII data, such as, e.g.@: SMTP. Apart from that, ASCII 660files in this format are binary files.
677flat files contain original database file metadata (file name, mode 661
678and ownership), and can therefore be used to restore an exact copy of 662The @dfn{ascii} flat file format encodes all data in base64 and stores
679the database. 663not only key/data pairs, but also the original database file metadata,
664such as file name, mode and ownership. Files in this format can be
665sent without additional encapsulation over transmission channels that
666normally allow only ASCII data, such as, e.g.@: SMTP. Due to additional
667metadata they allow for restoring an exact copy of the database,
668including file ownership and privileges, which is especially important
669if the database in question contained some security-related data.
670
671We call a process of creating a flat file from a database
672@dfn{exporting} or @dfn{dumping} this database. The reverse process,
673creating 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
693Name of the dump file. 688Name of the dump file.
694 689
695@item format 690@item format
696Dump format. Allowed values are: @samp{GDBM_DUMP_FMT_BINARY} to 691Output file format. Allowed values are: @samp{GDBM_DUMP_FMT_BINARY} to
697create a binary dump and @samp{GDBM_DUMP_FMT_ASCII} to create an ASCII 692create a binary dump and @samp{GDBM_DUMP_FMT_ASCII} to create an ASCII
698dump file. 693dump file.
699 694
@@ -723,8 +718,8 @@ for a detailed discussion.
723Loads data from the dump file @var{filename} into the database pointed 718Loads data from the dump file @var{filename} into the database pointed
724to by @var{pdbf}. The latter can point to @samp{NULL}, in which case 719to by @var{pdbf}. The latter can point to @samp{NULL}, in which case
725the function will try to create a new database. If it succeeds, the 720the function will try to create a new database. If it succeeds, the
726function will return a pointer to the newly created database in the 721function will return, in the memory location pointed to by @var{pdbf},
727memory location pointed to by @var{pdbf}. If the dump file carries no 722a pointer to the newly created database. If the dump file carries no
728information about the original database file name, the function will 723information about the original database file name, the function will
729set @code{gdbm_errno} to @samp{GDBM_NO_DBNAME} and return 724set @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);
817gdbm_load (&@var{dbf}, @var{exportfile}, GDBM_DUMP_FMT_BINARY, 813gdbm_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
854The pointer returned by @code{gdbm_open}. 850The pointer returned by @code{gdbm_open}.
855@item option 851@item option
856The option to be set or retreived. 852The option to be set or retrieved.
857@item value 853@item value
858A pointer to the value to which @var{option} will be set or where to 854A pointer to the value to which @var{option} will be set or where to
859place the option value (depending on the option). 855place the option value (depending on the option).
@@ -995,7 +991,7 @@ char *name;
995if (gdbm_setopt (dbf, GDBM_GETDBNAME, &name, sizeof (name))) 991if (gdbm_setopt (dbf, GDBM_GETDBNAME, &name, sizeof (name)))
996 @{ 992 @{
997 fprintf (stderr, "gdbm_setopt failed: %s\n", 993 fprintf (stderr, "gdbm_setopt failed: %s\n",
998 gdbm_strerror (gdbm_errno)); 994 gdbm_strerror (gdbm_errno));
999 @} 995 @}
1000else 996else
1001 @{ 997 @{
@@ -1040,7 +1036,7 @@ calls.
1040 1036
1041@node testgdbm 1037@node testgdbm
1042@chapter Test and modify a GDBM database. 1038@chapter Test and modify a GDBM database.
1043@cindex testgdbm 1039@prindex testgdbm
1044 1040
1045The @command{testgdbm} utility allows you to view and modify an 1041The @command{testgdbm} utility allows you to view and modify an
1046existing @acronym{GDBM} database or to create a new one. 1042existing @acronym{GDBM} database or to create a new one.
@@ -1367,14 +1363,24 @@ with its parameters and a short description of what it does. Optional
1367arguments are enclosed in square brackets. 1363arguments are enclosed in square brackets.
1368@end deffn 1364@end deffn
1369 1365
1366@node gdbm_dump
1367@chapter The @command{gdbm_dump} utility
1368@prindex gdbm_dump
1369FIXME
1370
1371@node gdbm_load
1372@chapter The @command{gdbm_load} utility
1373@prindex gdbm_load
1374FIXME
1375
1370@node gdbmexport 1376@node gdbmexport
1371@chapter Export a database into a portable format. 1377@chapter Export a database into a portable format.
1372@pindex gdbmexport 1378@prindex gdbmexport
1373 1379
1374The @command{gdbmexport} utility converts the database into a portable 1380The @command{gdbmexport} utility converts the database into a binary
1375@dfn{flat format}. Files in this format can be used to populate 1381flat format. Files in this format can be used to populate
1376databases using the @code{gdbm_import} function (@pxref{Flat files, 1382databases using the @code{gdbm_load} function (@pxref{Flat files,
1377gdbm_import}) or the @code{i} command of @command{testgdbm} utility 1383gdbm_load}) or the @code{i} command of @command{testgdbm} utility
1378(@pxref{testgdbm import}). In many cases files in this format are suitable for 1384(@pxref{testgdbm import}). In many cases files in this format are suitable for
1379sending over the network to populate the database on another machine. 1385sending over the network to populate the database on another machine.
1380The only exception to this are databases whose records contain 1386The only exception to this are databases whose records contain
@@ -1969,24 +1975,24 @@ You may contact the authors and maintainers by e-mail:
1969@chapter Additional resources 1975@chapter Additional resources
1970 1976
1971For the latest updates and pointers to additional resources, visit 1977For the latest updates and pointers to additional resources, visit
1972@uref{http://www.gnu.org/software/gdbm}. 1978@uref{http://www.gnu.org/@/software/@/gdbm}.
1973 1979
1974In particular, a copy of @code{gdbm} documentation in various formats 1980In particular, a copy of @code{gdbm} documentation in various formats
1975is available online at @uref{http://www.gnu.org/software/gdbm/manual}. 1981is available online at @uref{http://www.gnu.org/@/software/@/gdbm/@/manual.html}.
1976 1982
1977Latest versions of @code{gdbm} can be downloaded from anonymous FTP: 1983Latest versions of @code{gdbm} can be downloaded from anonymous FTP:
1978@uref{ftp://ftp.gnu.org/gnu/gdbm}, or via HTTP from 1984@uref{ftp://ftp.gnu.org/@/gnu/@/gdbm}, or via HTTP from
1979@uref{http://ftp.gnu.org/gnu/gdbm}, or from any 1985@uref{http://ftp.gnu.org/@/gnu/@/gdbm}, or from any
1980@ifhtml 1986@ifhtml
1981@uref{http://www.gnu.org/order/ftp.html,,GNU mirror} worldwide. 1987@uref{http://www.gnu.org/order/ftp.html,,GNU mirror} worldwide.
1982@end ifhtml 1988@end ifhtml
1983@ifnothtml 1989@ifnothtml
1984GNU mirror worldwide. See @uref{http://www.gnu.org/order/ftp.html}, 1990GNU mirror worldwide. See @uref{http://www.gnu.org/@/order/@/ftp.html},
1985for a list of mirrors. 1991for a list of mirrors.
1986@end ifnothtml 1992@end ifnothtml
1987 1993
1988To track @code{gdbm} development, visit 1994To track @code{gdbm} development, visit
1989@uref{http://puszcza.gnu.org.ua/projects/gdbm}. 1995@uref{http://puszcza.gnu.org.ua/@/projects/@/gdbm}.
1990 1996
1991@node GNU Free Documentation License 1997@node GNU Free Documentation License
1992@appendix GNU Free Documentation License 1998@appendix GNU Free Documentation License

Return to:

Send suggestions and report system problems to the System administrator.