summaryrefslogtreecommitdiffabout
path: root/doc
authorSergey Poznyakoff <gray@gnu.org>2018-07-01 07:08:55 (GMT)
committer Sergey Poznyakoff <gray@gnu.org>2018-07-01 07:19:36 (GMT)
commit030e685eb9df82f63d73a1bf206da84b7aa52374 (patch) (side-by-side diff)
treedcfc6693121e332d2cdb7c579e65ed0f397dc78e /doc
parentd6fe3b45bc669a6bc3f21e4bda69c6a052d78482 (diff)
downloadgdbm-030e685eb9df82f63d73a1bf206da84b7aa52374.tar.gz
gdbm-030e685eb9df82f63d73a1bf206da84b7aa52374.tar.bz2
Change return value of gdbm_close and gdbm_sync
* src/gdbm.h.in (gdbm_close, gdbm_sync): Return int (GDBM_FILE_CLOSE_ERROR, GDBM_FILE_SYNC_ERROR): New error codes. * src/gdbmclose.c (gdbm_close): Return 0 on success, -1 on failure. Set gdbm_errno and errno. * src/gdbmsync.c (gdbm_sync): Likewise. * src/gdbmerrno.c: Handle new error codes. * src/mmap.c (_gdbm_mapped_sync): Set gdbm_errno. * src/proto.h (gdbm_file_sync): Set gdbm_errno. * doc/gdbm.3: Document changes. * doc/gdbm.texi: Document changes. * NEWS: Document changes. * configure.ac: Set patchlevel. * tests/Makefile.am: Add new test. * tests/testsuite.at: Add new test. * tests/closerr.at: New test case. * tests/closerr.c: New test program. * tests/gtdel.c: Check gdbm_close return. * tests/gtdump.c: Likewise. * tests/gtfetch.c: Likewise. * tests/gtload.c: Likewise. * tests/gtopt.c: Likewise. * tests/gtrecover.c: Likewise.
Diffstat (limited to 'doc') (more/less context) (ignore whitespace changes)
-rw-r--r--doc/gdbm.310
-rw-r--r--doc/gdbm.texi16
2 files changed, 17 insertions, 9 deletions
diff --git a/doc/gdbm.3 b/doc/gdbm.3
index 6107d9a..d803748 100644
--- a/doc/gdbm.3
+++ b/doc/gdbm.3
@@ -10,13 +10,13 @@
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU General Public License for more details.
.\"
.\" 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 8, 2016" "GDBM" "GDBM User Reference"
+.TH GDBM 3 "July 1, 2018" "GDBM" "GDBM User Reference"
.SH NAME
GDBM \- The GNU database manager. Includes \fBdbm\fR and \fBndbm\fR
compatibility.
.SH SYNOPSIS
.nf
.B #include <gdbm.h>
@@ -28,13 +28,13 @@ compatibility.
.BI "GDBM_FILE gdbm_open (const char *" name ", int " block_size ", "
.ti +21
.BI "int " flags ", int " mode ", "
.ti +21
.BI "void (*" fatal_func ")(const char *))";
.br
-.BI "void gdbm_close (GDBM_FILE " dbf ");"
+.BI "int gdbm_close (GDBM_FILE " dbf ");"
.br
.BI "int gdbm_store (GDBM_FILE " dbf ", datum " key ", datum " content ", int " flag );
.br
.BI "datum gdbm_fetch (GDBM_FILE " dbf ", datum " key );
.br
.BI "int gdbm_delete (GDBM_FILE " dbf ", datum " key );
@@ -42,13 +42,13 @@ compatibility.
.BI "datum gdbm_firstkey (GDBM_FILE " dbf ");"
.br
.BI "datum gdbm_nextkey (GDBM_FILE " dbf ", datum " key );
.br
.BI "int gdbm_reorganize (GDBM_FILE " dbf ");"
.br
-.BI "void gdbm_sync (GDBM_FILE " dbf ");"
+.BI "int gdbm_sync (GDBM_FILE " dbf ");"
.br
.BI "int gdbm_exists (GDBM_FILE " dbf ", datum " key );
.br
.BI "const char *gdbm_strerror (gdbm_error " errno );
.br
.BI "int gdbm_setopt (GDBM_FILE " dbf ", int " option ", int " value ", int " size );
@@ -180,13 +180,13 @@ gdbmerrno.h.)
In all of the following calls, the parameter \fIdbf\fR refers to the pointer
returned from \fBgdbm_open\fR.
It is important that every file opened is also closed. This is needed to
update the reader/writer count on the file. This is done by:
-.BI "void gdbm_close (GDBM_FILE " dbf ");"
+.BI "int gdbm_close (GDBM_FILE " dbf ");"
The database is used by 3 primary routines. The first stores data in the
database.
.BI "int gdbm_store (GDBM_FILE " dbf ", datum " key ", datum " content ", int " flag );
@@ -305,13 +305,13 @@ using this reorganization. (Deleted file space will be reused.)
Unless your database was opened with the \fBGDBM_SYNC\fR flag, \fBgdbm\fR does not
wait for writes to be flushed to the disk before continuing.
The following routine can be used to guarantee that the database is
physically written to the disk file.
-.BI "void gdbm_sync (GDBM_FILE " dbf ");"
+.BI "int gdbm_sync (GDBM_FILE " dbf ");"
It will not return until the disk file state is syncronized with the
in-memory state of the database.
To convert a \fBgdbm\fR error code into English text, use this routine:
diff --git a/doc/gdbm.texi b/doc/gdbm.texi
index b5ba53d..4a0b1a7 100644
--- a/doc/gdbm.texi
+++ b/doc/gdbm.texi
@@ -212,20 +212,20 @@ library. The include file @code{gdbm.h}, that can be included by the user,
contains a definition of these functions.
@example
#include <gdbm.h>
GDBM_FILE gdbm_open(name, block_size, flags, mode, fatal_func);
-void gdbm_close(dbf);
+int gdbm_close(dbf);
int gdbm_store(dbf, key, content, flag);
datum gdbm_fetch(dbf, key);
int gdbm_delete(dbf, key);
datum gdbm_firstkey(dbf);
datum gdbm_nextkey(dbf, key);
int gdbm_reorganize(dbf);
-void gdbm_sync(dbf);
+int gdbm_sync(dbf);
int gdbm_exists(dbf, key);
char *gdbm_strerror(errno);
int gdbm_setopt(dbf, option, value, size);
int gdbm_fdesc(dbf);
int gdbm_export (GDBM_FILE, const char *, int, int);
int gdbm_export_to_file (GDBM_FILE dbf, FILE *fp);
@@ -366,20 +366,24 @@ Copy file ownership and mode from @var{src} to @var{dst}.
@cindex closing database
@cindex database, closing
It is important that every file opened is also closed. This is needed to
update the reader/writer count on the file:
-@deftypefn {gdbm interface} void gdbm_close (GDBM_FILE @var{dbf})
+@deftypefn {gdbm interface} int gdbm_close (GDBM_FILE @var{dbf})
This function closes the @code{gdbm} file and frees all memory
associated with it. The parameter is:
@table @var
@item dbf
The pointer returned by @code{gdbm_open}.
@end table
+
+@code{Gdbm_close} returns 0 on success. On error, it sets
+@code{gdbm_errno} and system @code{errno} variables to the codes
+describing the error and returns -1.
@end deftypefn
@node Count
@chapter Number of Records
@cindex number of records
@deftypefn {gdbm interface} int gdbm_count (GDBM_FILE @var{dbf}, @
@@ -675,21 +679,25 @@ Unless your database was opened with the @samp{GDBM_SYNC} flag,
continuing. This allows for faster writing of databases at the risk
of having a corrupted database if the application terminates in an
abnormal fashion. The following function allows the programmer to
make sure the disk version of the database has been completely updated
with all changes to the current time.
-@deftypefn {gdbm interface} void gdbm_sync (GDBM_FILE @var{dbf})
+@deftypefn {gdbm interface} int gdbm_sync (GDBM_FILE @var{dbf})
Synchronizes the changes in @var{dbf} with its disk file. The
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.
+
+@code{Gdbm_sync} returns 0 on success. On error, it sets
+@code{gdbm_errno} and system @code{errno} variables to the codes
+describing the error and returns -1.
@end deftypefn
@node Flat files
@chapter Export and Import
@cindex Flat file format
@cindex export

Return to:

Send suggestions and report system problems to the System administrator.