File: gdbm.info,  Node: Error codes,  Next: Compatibility,  Prev: Additional functions,  Up: Top

22 Error codes
**************

This chapter summarizes error codes which can be set by the functions in
'GDBM' library.

 -- Error Code: GDBM_NO_ERROR
     No error occurred.

 -- Error Code: GDBM_MALLOC_ERROR
     Memory allocation failed.  Not enough memory.

 -- Error Code: GDBM_BLOCK_SIZE_ERROR
     This error is set by the 'gdbm_open' function (*note Open::), if
     the value of its BLOCK_SIZE argument is incorrect and the
     'GDBM_BSEXACT' flag is set.

 -- Error Code: GDBM_FILE_OPEN_ERROR
     The library was not able to open a disk file.  This can be set by
     'gdbm_open' (*note Open::), 'gdbm_dump' ('gdbm_export') and
     'gdbm_load' ('gdbm_import') functions (*note Flat files::).

     Inspect the value of the system 'errno' variable to get more
     detailed diagnostics.

 -- Error Code: GDBM_FILE_WRITE_ERROR
     Writing to a disk file failed.  This can be set by 'gdbm_open'
     (*note Open::), 'gdbm_dump' ('gdbm_export') and 'gdbm_load'
     ('gdbm_import') functions.

     Inspect the value of the system 'errno' variable to get more
     detailed diagnostics.

 -- Error Code: GDBM_FILE_SEEK_ERROR
     Positioning in a disk file failed.  This can be set by 'gdbm_open'
     (*note Open::) function.

     Inspect the value of the system 'errno' variable to get a more
     detailed diagnostics.

 -- Error Code: GDBM_FILE_READ_ERROR
     Reading from a disk file failed.  This can be set by 'gdbm_open'
     (*note Open::), 'gdbm_dump' ('gdbm_export') and 'gdbm_load'
     ('gdbm_import') functions.

     Inspect the value of the system 'errno' variable to get a more
     detailed diagnostics.

 -- Error Code: GDBM_BAD_MAGIC_NUMBER
     The file given as argument to 'gdbm_open' function is not a valid
     'GDBM' file: it has a wrong magic number.

 -- Error Code: GDBM_EMPTY_DATABASE
     The file given as argument to 'gdbm_open' function is not a valid
     'GDBM' file: it has zero length.

 -- Error Code: GDBM_CANT_BE_READER
     This error code is set by the 'gdbm_open' function if it is not
     able to lock file when called in 'GDBM_READER' mode (*note
     GDBM_READER: Open.).

 -- Error Code: GDBM_CANT_BE_WRITER
     This error code is set by the 'gdbm_open' function if it is not
     able to lock file when called in writer mode (*note Open::).

 -- Error Code: GDBM_READER_CANT_DELETE
     Set by the 'gdbm_delete' (*note Delete::) if it attempted to
     operate on a database that is open in read-only mode (*note
     GDBM_READER: Open.).

 -- Error Code: GDBM_READER_CANT_STORE
     Set by the 'gdbm_store' (*note Store::) if it attempted to operate
     on a database that is open in read-only mode (*note GDBM_READER:
     Open.).

 -- Error Code: GDBM_READER_CANT_REORGANIZE
     Set by the 'gdbm_reorganize' (*note Reorganization::) if it
     attempted to operate on a database that is open in read-only mode
     (*note GDBM_READER: Open.).

 -- Error Code: GDBM_ITEM_NOT_FOUND
     Requested item was not found.  This error is set by 'gdbm_delete'
     (*note Delete::) and 'gdbm_fetch' (*note Fetch::) when the
     requested KEY value is not found in the database.

 -- Error Code: GDBM_REORGANIZE_FAILED
     The 'gdbm_reorganize' function is not able to create a temporary
     database.  *Note Reorganization::.

 -- Error Code: GDBM_CANNOT_REPLACE
     Cannot replace existing item.  This error is set by the
     'gdbm_store' if the requested KEY value is found in the database
     and the FLAG parameter is not 'GDBM_REPLACE'.  *Note Store::, for a
     detailed discussion.

 -- Error Code: GDBM_MALFORMED_DATA
 -- Error Code: GDBM_ILLEGAL_DATA
     Input data was malformed in some way.  When returned by
     'gdbm_load', this means that the input file was not a valid 'GDBM'
     dump file (*note gdbm_load function::).  When returned by
     'gdbm_store', this means that either KEY or CONTENT parameter had
     its 'dptr' field set to 'NULL' (*note Store::).

     The 'GDBM_ILLEGAL_DATA' is an alias for this error code, maintained
     for backward compatibility.  Its use in modern applications is
     discouraged.

 -- Error Code: GDBM_OPT_ALREADY_SET
     Requested option can be set only once and was already set.  As of
     version 1.24, this error code is no longer used.  In prior versions
     it could have been returned by the 'gdbm_setopt' function when
     setting the 'GDBM_CACHESIZE' value.

 -- Error Code: GDBM_OPT_BADVAL
 -- Error Code: GDBM_OPT_ILLEGAL
     The OPTION argument is not valid or the VALUE argument points to an
     invalid value in a call to 'gdbm_setopt' function.  *Note
     Options::.

     'GDBM_OPT_ILLEGAL' is an alias for this error code, maintained for
     backward compatibility.  Modern applications should not use it.

 -- Error Code: GDBM_BYTE_SWAPPED
     The 'gdbm_open' function (*note Open::) attempts to open a database
     which is created on a machine with different byte ordering.

 -- Error Code: GDBM_BAD_FILE_OFFSET
     The 'gdbm_open' function (*note Open::) sets this error code if the
     file it tries to open has a wrong magic number.

 -- Error Code: GDBM_BAD_OPEN_FLAGS
     Set by the 'gdbm_dump' ('gdbm_export') function if supplied an
     invalid FLAGS argument.  *Note Flat files::.

 -- Error Code: GDBM_FILE_STAT_ERROR
     Getting information about a disk file failed.  The system 'errno'
     will give more details about the error.

     This error can be set by the following functions: 'gdbm_open',
     'gdbm_reorganize'.

 -- Error Code: GDBM_FILE_EOF
     End of file was encountered where more data was expected to be
     present.  This error can occur when fetching data from the database
     and usually means that the database is truncated or otherwise
     corrupted.

     This error can be set by any 'GDBM' function that does I/O. Some of
     these functions are: 'gdbm_delete', 'gdbm_exists', 'gdbm_fetch',
     'gdbm_dump', 'gdbm_load', 'gdbm_export', 'gdbm_import',
     'gdbm_reorganize', 'gdbm_firstkey', 'gdbm_nextkey', 'gdbm_store'.

 -- Error Code: GDBM_NO_DBNAME
     Output database name is not specified.  This error code is set by
     'gdbm_load' (*note gdbm_load: gdbm_load function.) if the first
     argument points to 'NULL' and the input file does not specify the
     database name.

 -- Error Code: GDBM_ERR_FILE_OWNER
     This error code is set by 'gdbm_load' if it is unable to restore
     database file owner.  It is a mild error condition, meaning that
     the data have been restored successfully, only changing the target
     file owner failed.  Inspect the system 'errno' variable to get a
     more detailed diagnostics.

 -- Error Code: GDBM_ERR_FILE_MODE
     This error code is set by 'gdbm_load' if it is unable to restore
     database file mode.  It is a mild error condition, meaning that the
     data have been restored successfully, only changing the target file
     owner failed.  Inspect the system 'errno' variable to get a more
     detailed diagnostics.

 -- Error Code: GDBM_NEED_RECOVERY
     Database is in inconsistent state and needs recovery.  Call
     'gdbm_recover' if you get this error.  *Note Recovery::, for a
     detailed description of recovery functions.

 -- Error Code: GDBM_BACKUP_FAILED
     The GDBM engine is unable to create backup copy of the file.

 -- Error Code: GDBM_DIR_OVERFLOW
     Bucket directory would overflow the size limit during an attempt to
     split hash bucket.  This error can occur while storing a new key.

 -- Error Code: GDBM_BAD_BUCKET
     Invalid index bucket is encountered in the database.  Database
     recovery is needed (*note Recovery::).

 -- Error Code: GDBM_BAD_HEADER
     This error is set by 'gdbm_open' and 'gdbm_fd_open', if the first
     block read from the database file does not contain a valid 'GDBM'
     header.

 -- Error Code: GDBM_BAD_AVAIL
     The available space stack is invalid.  This error can be set by
     'gdbm_open' and 'gdbm_fd_open', if the extended database
     verification was requested ('GDBM_XVERIFY').  It is also set by the
     'gdbm_avail_verify' function (*note Additional functions::).

     Database recovery is needed (*note Recovery::).

 -- Error Code: GDBM_BAD_HASH_TABLE
     Hash table in a bucket is invalid.  This error can be set by the
     following functions: 'gdbm_delete', 'gdbm_exists', 'gdbm_fetch',
     'gdbm_firstkey', 'gdbm_nextkey', and 'gdbm_store'.

     Database recovery is needed (*note Recovery::).

 -- Error Code: GDBM_BAD_DIR_ENTRY
     Bad directory entry found in the bucket.  The database recovery is
     needed (*note Recovery::).

 -- Error Code: GDBM_FILE_CLOSE_ERROR
     The 'gdbm_close' function was unable to close the database file
     descriptor.  The system 'errno' variable contains the corresponding
     error code.

 -- Error Code: GDBM_FILE_SYNC_ERROR
     Cached content couldn't be synchronized to disk.  Examine the
     'errno' variable to get more info,

     Database recovery is needed (*note Recovery::).

 -- Error Code: GDBM_FILE_TRUNCATE_ERROR
     File cannot be truncated.  Examine the 'errno' variable to get more
     info.

     This error is set by 'gdbm_open' and 'gdbm_fd_open' when called
     with the 'GDBM_NEWDB' flag.

 -- Error Code: GDBM_BUCKET_CACHE_CORRUPTED
     The bucket cache structure is corrupted.  Database recovery is
     needed (*note Recovery::).

 -- Error Code: GDBM_BAD_HASH_ENTRY
     This error is set during sequential access (*note Sequential::), if
     the next hash table entry does not contain the expected key.  This
     means that the bucket is malformed or corrupted and the database
     needs recovery (*note Recovery::).

 -- Error Code: GDBM_ERR_SNAPSHOT_CLONE
     Set by the 'gdbm_failure_atomic' function if it was unable to clone
     the database file into a snapshot.  Inspect the system 'errno'
     variable for the underlying cause of the error.  If 'errno' is
     'EINVAL' or 'ENOSYS', crash tolerance settings will be removed from
     the database.

     *Note Crash Tolerance API::.

 -- Error Code: GDBM_ERR_REALPATH
     Set by the 'gdbm_failure_atomic' function if the call to 'realpath'
     function failed.  'realpath' is used to determine actual path names
     of the snapshot files.  Examine the system 'errno' variable for
     details.

     *Note Crash Tolerance API::.

 -- Error Code: GDBM_ERR_USAGE
     Function usage error.  That includes invalid argument values, and
     the like.