summaryrefslogtreecommitdiffabout
path: root/doc
authorSergey Poznyakoff <gray@gnu.org.ua>2016-07-08 08:28:53 (GMT)
committer Sergey Poznyakoff <gray@gnu.org.ua>2016-07-08 11:12:34 (GMT)
commit4aef6b36f862e46723403bc6422ac47058a5ef19 (patch) (side-by-side diff)
treefa7afe6ed8f1abf080fa764bda1bbc81e07f407b /doc
parent260102cf7f75db3c87d04a06eb8054853cacce97 (diff)
downloadgdbm-4aef6b36f862e46723403bc6422ac47058a5ef19.tar.gz
gdbm-4aef6b36f862e46723403bc6422ac47058a5ef19.tar.bz2
Fix error handling in gdbm_fetch, gdbm_firstkey, and gdbm_nextkey.
* src/gdbmfetch.c: Hanlde out of memory error. * src/findkey.c: Set gdbm_errno to GDBM_ITEM_NOT_FOUND if nothing was found. * src/gdbmdelete.c: Don't set gdbm_errno after _gdbm_findkey returns -1. It's been done already. * src/gdbmexp.c (gdbm_export_to_file): Return -1 if gdbm_fetch fails. * src/gdbmseq.c (get_next_key): Set gdbm_errno to GDBM_ITEM_NOT_FOUND if there's no next key. Don't call _gdbm_fatal on out of memory condition. (gdbm_nextkey): Set gdbm_errno to GDBM_ITEM_NOT_FOUND if there's no next key. * src/gdbmtool.c (fetch_handler) (firstkey_handler,nextkey_handler): Check gdbm_errno. * src/gdbmstore.c: Handle error return from _gdbm_findkey. * tests/gtdump.c: Likewise. * tests/gtfetch.c: Likewise. * doc/gdbm.texi: Document changes. * doc/gdbm.3: Likewise. * configure.ac: Version 1.12.90 * NEWS: Update. * .gitignore: Update.
Diffstat (limited to 'doc') (more/less context) (ignore whitespace changes)
-rw-r--r--doc/gdbm.323
-rw-r--r--doc/gdbm.texi20
2 files changed, 29 insertions, 14 deletions
diff --git a/doc/gdbm.3 b/doc/gdbm.3
index 860829a..98b718b 100644
--- a/doc/gdbm.3
+++ b/doc/gdbm.3
@@ -1,5 +1,5 @@
.\" This file is part of GDBM.
-.\" Copyright (C) 2011, 2013 Free Software Foundation, Inc.
+.\" Copyright (C) 2011, 2013, 2016 Free Software Foundation, Inc.
.\"
.\" GDBM is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
@@ -13,7 +13,7 @@
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with GDBM. If not, see <http://www.gnu.org/licenses/>. */
-.TH GDBM 3 "July 6, 2016" "GDBM" "GDBM User Reference"
+.TH GDBM 3 "July 8, 2016" "GDBM" "GDBM User Reference"
.SH NAME
GDBM \- The GNU database manager. Includes \fBdbm\fR and \fBndbm\fR
compatibility.
@@ -171,7 +171,7 @@ if it detects a fatal error. The only parameter of this function is a string.
If the value of 0 is provided, \fBgdbm\fR will use a default function.
The return value is the pointer needed by all other routines to
-access that gdbm file. If the return is the NULL pointer, \fBgdbm_open\fR
+access that gdbm file. If the return is the \fBNULL\fR pointer, \fBgdbm_open\fR
was not successful. The errors can be found in \fIgdbm_errno\fR for gdbm
errors and in \fIerrno\fR for system errors. (For error codes, see
gdbmerrno.h.)
@@ -218,8 +218,12 @@ To search for some data, use:
\fIDbf\fR is the pointer returned by \fBgdbm_open\fR. \fIKey\fR is
the key data.
-If the \fIdptr\fR element of the return value is NULL, no data was
-found. Otherwise the return value is a pointer to the found data.
+If the \fIdptr\fR element of the return value is \fBNULL\fR, the
+\fBgdbm_errno\fR variable should be examined. The value of
+\fBGDBM_ITEM_NOT_FOUND\fR means no data was found for that \fIkey\fR.
+Other value means an error occurred.
+
+Otherwise the return value is a pointer to the found data.
The storage space for the \fIdptr\fR element is allocated using
\fBmalloc(3)\fR. \fBGdbm\fI does not automatically free this data.
It is the programmer's responsibility to free this storage when it is
@@ -259,8 +263,11 @@ the database once. (The order has to do with the hash values.)
key data.
The return values are both of type \fBdatum\fR. If the \fIdptr\fR
-element of the return value is NULL, there is no first key or next key.
-Again notice that \fIdptr\fR points to data allocated by \fBmalloc(3)\fR
+element of the return value is \fBNULL\fR, inspect the
+\fBgdbm_errno\fR. If it is \fBGDBM_ITEM_NOT_FOUND\fR, there is no
+first key or next key. Otherwise, an error occurred.
+
+Again, notice that \fIdptr\fR points to data allocated by \fBmalloc(3)\fR
and \fBgdbm\fR will not free it for you.
These functions were intended to visit the database in read-only algorithms,
@@ -426,7 +433,7 @@ Send bug reports to <bug\-gdbm@gnu.org>.
.SH AUTHORS
by Philip A. Nelson, Jason Downs and Sergey Poznyakoff.
.SH COPYRIGHT
-Copyright \(co 1990 - 2011 Free Software Foundation, Inc.
+Copyright \(co 1990 - 2016 Free Software Foundation, Inc.
GDBM is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
diff --git a/doc/gdbm.texi b/doc/gdbm.texi
index 6322a9b..6fad9d9 100644
--- a/doc/gdbm.texi
+++ b/doc/gdbm.texi
@@ -43,7 +43,7 @@ Published by the Free Software Foundation,
51 Franklin Street, Fifth Floor
Boston, MA 02110-1301, USA
-Copyright @copyright{} 1989-1999, 2007-2011 Free Software Foundation, Inc.
+Copyright @copyright{} 1989-1999, 2007-2016 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
@@ -430,7 +430,11 @@ The @samp{dptr} field in the structure that is returned points to a
memory block allocated by @code{malloc}. It is the caller's
responsibility to free it when no longer needed.
-If the @samp{dptr} is @samp{NULL}, no data was found.
+If the @samp{dptr} is @samp{NULL}, inspect the value of the
+@code{gdbm_errno} variable (@pxref{Variables,gdbm_errno}). If it is
+@samp{GDBM_ITEM_NOT_FOUND}, no data was found. Any other value means an
+error occurred. Use @code{gdbm_strerror} function to convert
+@code{gdbm_errno} to a human-readable string.
The parameters are:
@@ -515,8 +519,10 @@ access is not @code{key} sequential, but it is guaranteed to visit every
@deftypefn {gdbm interface} datum gdbm_firstkey (GDBM_FILE @var{dbf})
Initiate sequential access to the database @var{dbf}. The returned
value is the first key accessed in the database. If the @samp{dptr}
-field in the returned datum is @samp{NULL}, the database contains no
-data.
+field in the returned datum is @samp{NULL}, inspect the
+@code{gdbm_errno} variable (@pxref{Variables, gdbm_errno}). The value
+of @code{GDBM_ITEM_NOT_FOUND} means that the database contains no
+data. Other value means an error occurred.
Otherwise, @samp{dptr} points to a memory block obtained from
@code{malloc}, which holds the key value. The caller is responsible
@@ -530,8 +536,10 @@ value returned from a previous call to @code{gdbm_nextkey} or
@code{gdbm_firstkey}.
The function returns next key from the database. If the @samp{dptr}
-field in the returned datum is @samp{NULL}, all keys in the database
-has been visited.
+field in the returned datum is @samp{NULL} inspect the
+@code{gdbm_errno} variable (@pxref{Variables, gdbm_errno}). The value
+of @code{GDBM_ITEM_NOT_FOUND} means that all keys in the database
+has been visited. Any other value means an error occurred.
Otherwise, @samp{dptr} points to a memory block obtained from
@code{malloc}, which holds the key value. The caller is responsible

Return to:

Send suggestions and report system problems to the System administrator.