From 1aedc2c9df369f8683b2ba78b17c677996a2d815 Mon Sep 17 00:00:00 2001 From: Sergey Poznyakoff Date: Tue, 19 Jul 2016 18:35:18 +0300 Subject: Improve docs. Minor changes. * NEWS: Document new features. * doc/gdbm.texi: Likewise. * src/gdbm.h.in (gdbm_last_errno): Fix return value. (gdbm_check_syserr): New proto. * src/gdbmdefs.h (gdbm_file_info) : Fix data type. * src/gdbmerrno.c (gdbm_last_errno): Fix return value. (gdbm_check_syserr): New function. --- NEWS | 75 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 60 insertions(+), 15 deletions(-) (limited to 'NEWS') diff --git a/NEWS b/NEWS index 2142514..04f4668 100644 --- a/NEWS +++ b/NEWS @@ -18,11 +18,59 @@ the error code. In any case gdbm_errno is guaranteed to have meaningful value upon return. -The gdbm_fetch function no longer aborts on memory allocation errors. -Instead it sets gdbm_errno to GDBM_MALLOC_ERROR and returns NULL datum. +* Error handling + +In previous versions of GDBM, fatal errors (such as write error while +storing the key/data pair or bucket) caused immediate termination of +the program via call to exit(3). This is no longer the case. + +Starting from this version, if a fatal error occurrs while modifying +the database file, that database is marked as needing recovery and +gdbm_errno is set to GDBM_NEED_RECOVERY. Calls to any GDBM functions, +except gdbm_recover, will then return immediately with the same error +code. + +The function gdbm_recover examines the database file and fixes +eventual inconsistencies. Upon successful return it clears the error +state and makes the database operational again. + +For backward compatibility, the fatal_func argument to gdbm_open is +retained and its functionality is not changed. If it is not NULL, the +new error handling procedures are disabled, the function it points to +will be called upon fatal errors. When it returns, exit(1) will be +called. * Per-database error codes +In addition to gdbm_error global variable, the most recent error state +is saved in the GDBM_FILE structure. This facilitates error handling +when operating multiple GDBM databases simultaneously. + +The following new functions are implemented for manipulating error +states: + +** gdbm_error gdbm_last_errno (GDBM_FILE dbf) + +Returns the code of the most recent error that occurred in the given database. + +** int gdbm_last_syserr (GDBM_FILE dbf) + +Returns the value the system errno variable had when the most recent +error occurred. This provides additional information for such error +codes as GDBM_FILE_SEEK_ERROR, GDBM_FILE_WRITE_ERROR and the like. + +** void gdbm_clear_error (GDBM_FILE dbf) + +Clears the error state associated with the database file. + +** char const *gdbm_db_strerror (GDBM_FILE dbf) + +Returns textual description of the error. + +** int gdbm_needs_recovery (GDBM_FILE dbf) + +Returns true if the database file needs recovery. + * New gdbm_open flag: GDBM_BSEXACT When creating a new database, the gdbm_open function will adjust the @@ -44,21 +92,18 @@ Returns the block size in bytes. E.g. * New functions -** gdbm_last_errno - -** gdbm_clear_error - -** gdbm_needs_recovery - -** gdbm_recover - -** gdbm_last_syserr - -** gdbm_db_strerror +** GDBM_FILE gdbm_fd_open (int fd, const char *file_name, int block_size, + int flags, void (*fatal_func) (const char *)) -** gdbm_fd_open +Alternative function for opening a GDBM database. The fd argument is +the file descriptor of the database file obtained by a call to +open(2), creat(2) or similar functions. The descriptor is not dup'ed, and +will be closed when the returned GDBM_FILE is closed. Use dup(2) if +that is not desirable. + +** int gdbm_copy_meta (GDBM_FILE dst, GDBM_FILE src) -** gdbm_copy_meta +Copy meta-information (ownership and file permissions) from src to dst. * Line editing in gdbmtool -- cgit v1.2.1