aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2011-11-14 21:59:38 +0000
committerSergey Poznyakoff <gray@gnu.org.ua>2011-11-14 21:59:38 +0000
commit4931e4393ebff15289ad282f3d3dd0fba4999986 (patch)
tree1386373cfd7c8723fe7eea0a3381c2c604280b10 /doc
parent91751b0ce995e2b3b73fd60d4dbeade3cc4de123 (diff)
downloadgdbm-4931e4393ebff15289ad282f3d3dd0fba4999986.tar.gz
gdbm-4931e4393ebff15289ad282f3d3dd0fba4999986.tar.bz2
Document new flat format and related functions.
Diffstat (limited to 'doc')
-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
@@ -1,124 +1,102 @@
\input texinfo @c -*- Texinfo -*-
@comment $Id$
@comment %**start of header (This is for running Texinfo on a region.)
@setfilename gdbm.info
@include version.texi
-@settitle gdbm manual
+@settitle GDBM manual
@ifinfo
@dircategory Programming & development tools
@direntry
* GDBM: (gdbm). The GNU database manager.
+* gdbm_dump: gdbm_dump(gdbm). Dump the GDBM database into a flat file.
+* gdbm_load: gdbm_load(gdbm). Load the database from a flat file.
@end direntry
@end ifinfo
@c @setchapternewpage odd
@comment %**end of header (This is for running Texinfo on a region.)
@c Use @kwindex for keywords
@defcodeindex kw
@syncodeindex kw cp
@c Use @flindex for files
@defcodeindex fl
@syncodeindex fl cp
+@c Use @prindex for programs
+@defcodeindex pr
+@syncodeindex pr cp
@c Merge all indices into a single one
@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex ky cp
@syncodeindex pg cp
@syncodeindex tp cp
@iftex
@finalout
@end iftex
@copying
-This file documents the GNU dbm utility.
+Published by the Free Software Foundation,
+51 Franklin Street, Fifth Floor
+Boston, MA 02110-1301, USA
-Copyright @copyright{} 1989-1999, 2007, 2008, 2009-2011 Free Software Foundation, Inc.
+Copyright @copyright{} 1989-1999, 2007-2011 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
-Invariant Sections, with the Front-Cover Texts being ``The GNU Database
-Manager,'' and with the Back-Cover Texts as in (a) below. A copy of the
-license is included in the section entitled ``GNU Free Documentation
-License.''
-
-(a) The FSF's Back-Cover Text is: ``You have the freedom to
-copy and modify this GNU manual. Buying copies from the FSF
-supports it in developing GNU and promoting software freedom.''
+Invariant Sections, no Front-Cover, and no Back-Cover texts.
+A copy of the license is included in the section entitled ``GNU Free
+Documentation License.''
@end copying
@titlepage
@sp 6
@center @titlefont{GNU dbm}
@sp 2
@center A Database Manager
@sp 2
@center by Philip A. Nelson, Jason Downs and Sergey Poznyakoff
@sp 4
@center Manual by Pierre Gaumond, Philip A. Nelson, Jason Downs
@center and Sergey Poznyakoff
@sp 1
@center Edition @value{EDITION}
@sp 1
@center for GNU @code{dbm}, Version @value{VERSION}
@page
@vskip 0pt plus 1filll
-Copyright @copyright{} 1993-1999, 2007-2011 Free Software Foundation, Inc.
-@sp 2
-
-This is Edition @value{EDITION} of the @cite{GNU @code{dbm} Manual},
-for @code{gdbm} Version @value{VERSION}. @*
-Last updated @value{UPDATED}
-
-Published by the Free Software Foundation @*
-675 Massachusetts Avenue, @*
-Cambridge, MA 02139 USA @*
-
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
-
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided also that
-the entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions,
-except that this permission notice may be stated in a translation approved
-by the Free Software Foundation.
+@insertcopying
@end titlepage
-@page
@ifnothtml
@page
@summarycontents
@page
@end ifnothtml
@contents
@ifnottex
@node Top
@top The GNU database manager.
GNU @code{dbm} is a library of functions implementing a hashed database
on a disk file. This manual documents GNU @code{dbm} Version @value{VERSION}
-(@code{gdbm}). The software was originally written by Philip A. Nelson. This
-document was originally written by Pierre Gaumond from texts written by
-Phil.
+(@code{gdbm}). The software was originally written by Philip A.@:
+Nelson. This document was originally written by Pierre Gaumond from
+texts written by Phil.
@end ifnottex
@menu
Introduction:
* Copying:: Your rights.
* Intro:: Introduction to GNU dbm.
* List:: List of functions.
Functions:
* Open:: Opening the database.
@@ -127,25 +105,27 @@ Functions:
* Fetch:: Searching records in the database.
* Delete:: Removing records from the database.
* Sequential:: Sequential access to records.
* Reorganization:: Database reorganization.
* Sync:: Insure all writes to disk have competed.
* Flat files:: Export and import to Flat file format.
* Errors:: Convert internal error codes into English.
* Options:: Setting internal options.
* Locking:: File locking.
Programs
-* testgdbm:: Test and modify a GDBM database.
+* testgdbm:: Test and modify a GDBM database.
+* gdbm_dump:: Dump the database into a flat file.
+* gdbm_load:: Load the database from a flat file.
* gdbmexport:: Export a database into a portable format.
Other topics:
* Error codes:: Error codes returned by @code{gdbm} calls.
* Variables:: Two useful variables.
* Compatibility:: Compatibility with UNIX dbm and ndbm.
* Bugs:: Problems and bugs.
* Resources:: Additional resources,
* GNU Free Documentation License:: Document license.
* Index:: Index
@@ -642,67 +622,82 @@ parameter is a pointer returned by @code{gdbm_open}.
This function would usually be called after a complete set of changes
have been made to the database and before some long waiting time.
The @code{gdbm_close} function automatically calls the equivalent of
@code{gdbm_sync} so no call is needed if the database is to be closed
immediately after the set of changes have been made.
@end deftypefn
@node Flat files
@chapter Export and Import
@cindex Flat file format
@cindex export
@cindex import
-@code{Gdbm} databases can be converted into a portable @dfn{flat
-format}. This format can be used, for example, to migrate between
+@code{Gdbm} databases can be converted into so-called @dfn{flat
+format} files. Such files cannot be used for searching, their sole
+purpose is to keep the data from the database for restoring it when
+the need arrives. There are two flat file formats, which differ in
+the way they represent the data and in the amount of meta-information
+stored. Both formats can be used, for example, to migrate between
the different versions of @code{gdbm} databases. Generally speaking,
flat files are safe to send over the network, and can be used to
recreate the database on another machine. The recreated database is
guaranteed to be a byte-to-byte equivalent of the database from which
the flat file was created. This does not necessarily mean, however,
that this file can be used in the same way as the original one. For
example, if the original database contained non-@acronym{ASCII} data
(e.g.@: @acronym{C} structures, integers etc.), the recreated database
can be of any use only if the target machine has the same integer
size and byte ordering as the source one and if its @acronym{C}
compiler uses the same packing conventions as the one which generated
@acronym{C} which populated the original database. In general, such
binary databases are not portable between machines, unless you follow
some stringent rules on what data is written to them and how it is
interpreted.
-GDBM version @value{VERSION} supports two flat file formats. The
-@dfn{binary} flat file, as its name implies, keeps data in binary
-form. The @dfn{ascii} flat file, on the other hand, encodes all data
-in base64 and can be sent over transmission channels that normally
-allow only ASCII data, such as, e.g.@: SMTP. Apart from that, ASCII
-flat files contain original database file metadata (file name, mode
-and ownership), and can therefore be used to restore an exact copy of
-the database.
+The GDBM version @value{VERSION} supports two flat file formats. The
+@dfn{binary} flat file format was first implemented in GDBM version
+1.9.1. This format stores only key/data pairs, it does not keep
+information about the database file itself. As its name implies,
+files in this format are binary files.
+
+The @dfn{ascii} flat file format encodes all data in base64 and stores
+not only key/data pairs, but also the original database file metadata,
+such as file name, mode and ownership. Files in this format can be
+sent without additional encapsulation over transmission channels that
+normally allow only ASCII data, such as, e.g.@: SMTP. Due to additional
+metadata they allow for restoring an exact copy of the database,
+including file ownership and privileges, which is especially important
+if the database in question contained some security-related data.
+
+We call a process of creating a flat file from a database
+@dfn{exporting} or @dfn{dumping} this database. The reverse process,
+creating the database from a flat file is called @dfn{importing} or
+@dfn{loading} the database.
@deftypefn {gdbm interface} int gdbm_dump (GDBM_FILE @var{dbf}, @
const char *@var{filename}, int @var{format}, @
int @var{open_flags}, int @var{mode})
Dumps the database file to the named file in requested format.
Arguments are:
@table @var
@item dbf
A pointer to the source database, returned by a prior call to
@code{gdbm_open}.
@item filename
Name of the dump file.
@item format
-Dump format. Allowed values are: @samp{GDBM_DUMP_FMT_BINARY} to
+Output file format. Allowed values are: @samp{GDBM_DUMP_FMT_BINARY} to
create a binary dump and @samp{GDBM_DUMP_FMT_ASCII} to create an ASCII
dump file.
@item open_flags
How to create the output file. If @var{flag} is @samp{GDBM_WRCREAT}
the file will be created if it does not exist. If it does exist,
the @code{gdbm_dump} will fail.
If @var{flag} is @samp{GDBM_NEWDB}, the function will create a new
output file, replacing it if it already exists.
@item mode
@@ -714,26 +709,26 @@ See @ifhtml
@ref{open,,open a file,open(2), open(2) man page},
@end ifnothtml
for a detailed discussion.
@end table
@end deftypefn
@anchor{gdbm_load function}
@deftypefn {gdbm interface} int gdbm_load (GDBM_FILE *@var{pdbf}, @
const char *@var{filename}, int @var{flag}, unsigned long *@var{errline})
Loads data from the dump file @var{filename} into the database pointed
to by @var{pdbf}. The latter can point to @samp{NULL}, in which case
the function will try to create a new database. If it succeeds, the
-function will return a pointer to the newly created database in the
-memory location pointed to by @var{pdbf}. If the dump file carries no
+function will return, in the memory location pointed to by @var{pdbf},
+a pointer to the newly created database. If the dump file carries no
information about the original database file name, the function will
set @code{gdbm_errno} to @samp{GDBM_NO_DBNAME} and return
@samp{-1}, indicating failure.
The @var{flag} has the same meaning as the @var{flag} argument
to the @code{gdbm_store} function (@pxref{Store}).
The function returns 0 upon successful completion or -1 on error. In
the latter case, @code{gdbm_errno} will be set to one of the
following values:
@table @asis
@@ -803,26 +798,27 @@ gdbm_dump(@var{dbf}, @var{exportfile}, GDBM_DUMP_FMT_BINARY,
@end example
@end deftypefn
@deftypefn {gdbm interface} int gdbm_import (GDBM_FILE @var{dbf}, @
const char *@var{importfile}, int @var{flag})
This function is retained for compatibility with GDBM 1.10 and
earlier. It loads the file @var{importfile}, which must be a binary
flat file, into the database @var{dbf} and is equivalent to the
following construct:
@example
@var{dbf} = gdbm_open (@var{importfile}, 0,
- @var{flag} == GDBM_REPLACE ? GDBM_WRCREAT :
- GDBM_NEWDB, 0600, NULL);
+ @var{flag} == GDBM_REPLACE ?
+ GDBM_WRCREAT : GDBM_NEWDB,
+ 0600, NULL);
gdbm_load (&@var{dbf}, @var{exportfile}, GDBM_DUMP_FMT_BINARY,
@var{flag}, NULL)
@end example
@end deftypefn
@node Errors
@chapter Error strings.
@cindex error strings
To convert a @code{gdbm} error code into English text, use this
routine:
@@ -844,25 +840,25 @@ The @var{errno} argument is usually the value of the global variable
open database.
@deftypefn {gdbm interface} int gdbm_setopt (GDBM_FILE @var{dbf}, int @var{option}, @
void *@var{value}, int @var{size})
Sets an option on the database or returns the value of an option.
The parameters are:
@table @var
@item dbf
The pointer returned by @code{gdbm_open}.
@item option
-The option to be set or retreived.
+The option to be set or retrieved.
@item value
A pointer to the value to which @var{option} will be set or where to
place the option value (depending on the option).
@item size
The length of the data pointed to by @var{value}.
@end table
@end deftypefn
The valid options are:
@table @asis
@kwindex GDBM_CACHESIZE
@@ -986,25 +982,25 @@ to an integer where to return the status.
Return the name of the database disk file. The @var{value} should
point to a variable of type @code{char**}. A pointer to the newly
allocated copy of the file name will be placed there. The caller is
responsible for freeing this memory when no longer needed. For
example:
@example
char *name;
if (gdbm_setopt (dbf, GDBM_GETDBNAME, &name, sizeof (name)))
@{
fprintf (stderr, "gdbm_setopt failed: %s\n",
- gdbm_strerror (gdbm_errno));
+ gdbm_strerror (gdbm_errno));
@}
else
@{
printf ("database name: %s\n", name);
free (name);
@}
@end example
@end table
The return value will be @samp{-1} upon failure, or @samp{0} upon
success. The global variable @code{gdbm_errno} will be set upon failure.
@@ -1031,25 +1027,25 @@ in order to prevent multiple writers operating on the same file
simultaneously.
In order to support this, the @code{gdbm_fdesc} routine is provided.
@deftypefn {gdbm interface} int gdbm_fdesc (GDBM_FILE @var{dbf})
Returns the file descriptor of the database @var{dbf}. This value
can be used as an argument to @code{flock}, @code{lockf} or similar
calls.
@end deftypefn
@node testgdbm
@chapter Test and modify a GDBM database.
-@cindex testgdbm
+@prindex testgdbm
The @command{testgdbm} utility allows you to view and modify an
existing @acronym{GDBM} database or to create a new one.
@cindex default database, @command{testgdbm}
@cindex @option{-g}, @command{testgdbm} option
@cindex @option{-f}, @command{testgdbm} option
@cindex @option{--file}, @command{testgdbm} option
@flindex junk.gdbm
When invoked without options, it tries to open a database file called
@file{junk.gdbm}, located in the current working directory. You can
change this default using the @option{--file} (@option{-f}) command
@@ -1358,32 +1354,42 @@ status.
@xref{nul-termination}.
@end deffn
@deffn {command verb} help
@deffnx {command abbrev} hel
@deffnx {command letter} ?
Print a concise command summary, showing each command letter and verb
with its parameters and a short description of what it does. Optional
arguments are enclosed in square brackets.
@end deffn
+@node gdbm_dump
+@chapter The @command{gdbm_dump} utility
+@prindex gdbm_dump
+FIXME
+
+@node gdbm_load
+@chapter The @command{gdbm_load} utility
+@prindex gdbm_load
+FIXME
+
@node gdbmexport
@chapter Export a database into a portable format.
-@pindex gdbmexport
+@prindex gdbmexport
-The @command{gdbmexport} utility converts the database into a portable
-@dfn{flat format}. Files in this format can be used to populate
-databases using the @code{gdbm_import} function (@pxref{Flat files,
-gdbm_import}) or the @code{i} command of @command{testgdbm} utility
+The @command{gdbmexport} utility converts the database into a binary
+flat format. Files in this format can be used to populate
+databases using the @code{gdbm_load} function (@pxref{Flat files,
+gdbm_load}) or the @code{i} command of @command{testgdbm} utility
(@pxref{testgdbm import}). In many cases files in this format are suitable for
sending over the network to populate the database on another machine.
The only exception to this are databases whose records contain
non-@acronym{ASCII} data (e.g.@: @acronym{C} structures, integers
etc.). For such databases you will be better off by writing a
specialized utility to convert them to an architecture-independent
format.
If @command{gdbmexport} is linked with @file{libgdbm}
version 1.8.3, it can be used to convert databases from old to new
format.
@@ -1960,42 +1966,42 @@ Non-bug suggestions are always welcome as well. If you have questions
about things that are unclear in the documentation or are just obscure
features, please report them too.
You may contact the authors and maintainers by e-mail:
@example
@email{phil@@cs.wwu.edu}, @email{downsj@@downsj.com}, @email{gray@@gnu.org.ua}
@end example
@node Resources
@chapter Additional resources
For the latest updates and pointers to additional resources, visit
-@uref{http://www.gnu.org/software/gdbm}.
+@uref{http://www.gnu.org/@/software/@/gdbm}.
In particular, a copy of @code{gdbm} documentation in various formats
-is available online at @uref{http://www.gnu.org/software/gdbm/manual}.
+is available online at @uref{http://www.gnu.org/@/software/@/gdbm/@/manual.html}.
Latest versions of @code{gdbm} can be downloaded from anonymous FTP:
-@uref{ftp://ftp.gnu.org/gnu/gdbm}, or via HTTP from
-@uref{http://ftp.gnu.org/gnu/gdbm}, or from any
+@uref{ftp://ftp.gnu.org/@/gnu/@/gdbm}, or via HTTP from
+@uref{http://ftp.gnu.org/@/gnu/@/gdbm}, or from any
@ifhtml
@uref{http://www.gnu.org/order/ftp.html,,GNU mirror} worldwide.
@end ifhtml
@ifnothtml
-GNU mirror worldwide. See @uref{http://www.gnu.org/order/ftp.html},
+GNU mirror worldwide. See @uref{http://www.gnu.org/@/order/@/ftp.html},
for a list of mirrors.
@end ifnothtml
To track @code{gdbm} development, visit
-@uref{http://puszcza.gnu.org.ua/projects/gdbm}.
+@uref{http://puszcza.gnu.org.ua/@/projects/@/gdbm}.
@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include fdl.texi
@node Index
@unnumbered Index
@printindex cp
@bye

Return to:

Send suggestions and report system problems to the System administrator.