Next: Closing the database, Previous: Introduction to GNU dbm, Up: The GNU database manager [Contents][Index]
Opens or creates a GDBM database file.
The arguments are:
The name of the file (the complete name, GDBM does not append any
characters to this name).
This parameter is used only when gdbm_open has to create a new
database file and represents the size of a single transfer from disk to
memory. If its value is less than 512, the file system block
size is used instead. The size is adjusted so that the block can hold
exact number of directory entries, so that the effective block size
can be slightly greater than requested. However, if the
GDBM_BSEXACT flag is set and the size needs to be adjusted, the
function will return with error status, setting the gdbm_errno
variable to GDBM_BLOCK_SIZE_ERROR.
If flags is set to GDBM_READER, the user wants to just read the
database and any call to gdbm_store or gdbm_delete will fail.
Many readers can access the database at the same time. If flags is
set to GDBM_WRITER, the user wants both read and write access
to the database and requires exclusive access. If flags is set
to GDBM_WRCREAT, the user wants both read and write access to
the database and wants it created if it does not already exist. If
flags is set to GDBM_NEWDB, the user want a new database
created, regardless of whether one existed, and wants read and write
access to the new database. If an existing database file is opened with
the GDBM_NEWDB flag, the existing data are destroyed, and an
empty database structure is created in its place.
The following constants may also be logically or’d into the database flags:
Set the close-on-exec flag on the database file descriptor. The
libc must support the O_CLOEXEC flag
(see O_CLOEXEC in open(2) man page).
Don’t lock the database file. Use this flag if you intend to do locking separately. See File Locking.
Disable memory mapping mechanism. Note, that this degrades performance.
When mapping GDBM file to memory, read its contents immediately,
instead of when needed (prefault reading). This can be
advantageous if you open a read-only database and are going to
do a lot of look-ups on it. In this case entire database will be
pre-read and look-ups will operate on an in-memory copy. In
contrast, GDBM_PREREAD should not be used if you open a
database (even in read-only mode) only to do a couple of look-ups.
Finally, never use GDBM_PREREAD when opening a database for
updates, especially for inserts: this will degrade performance.
This flag has no effect if GDBM_NOMMAP is given, or if the
operating system does not support prefault reading. It is known
to work on Linux and FreeBSD kernels.
Enable additional consistency checks. With this flag, eventual corruptions of the database are discovered when opening it, instead of when a corrupted structure is read during normal operation. However, on large databases, it can slow down the opening process.
See Additional functions.
The following additional flags are valid when the database is opened
for writing (i.e. together with GDBM_WRITER,
GDBM_WRCREAT, or GDBM_NEWDB):
Synchronize all database operations to disk immediately. Notice, that this option entails severe performance degradation and does not necessarily ensure that the resulting database state is consistent. In general, we discourage its use (see Database Synchronization). See Crash Tolerance, for a discussion of how to ensure database consistency with minimal performance overhead.
A reverse of GDBM_SYNC. Synchronize writes only when needed.
This is the default. The flag is provided for compatibility with
previous versions of GDBM.
The following flags can be used together with GDBM_NEWDB. They
also take effect when used with GDBM_WRCREAT, if the requested
database file doesn’t exist:
If this flag is set and the requested block_size cannot be used
without adjustment, gdbm_open will refuse to create the
databases. In this case it will set the gdbm_errno
variable to GDBM_BLOCK_SIZE_ERROR and return NULL.
Useful only together with GDBM_NEWDB, this bit instructs
gdbm_open to create new database in extended database
format, a format best suitable for effective crash recovery.
See Numsync Extension, for a detailed discussion of this format, and
Crash Tolerance, for a discussion of crash recovery.
File mode1, which is used if the file is created.
This parameter is deprecated and must always be NULL.
Early versions of GDBM (prior to 1.13) lacked proper error
handling and would abort on any “fatal” error (such as out of memory
condition, disk write error, or the like). In these versions,
fatal_func was provided as a hook, allowing the caller to do
proper cleanup before such abnormal exit. As of version
1.25, this functionality is deprecated, although still
supported for backward compatibility.
The return value, is the pointer needed by all other functions to
access that GDBM file. If the return is the NULL pointer,
gdbm_open was not successful. The errors can be found in
gdbm_errno variable (see gdbm_errno). Available
error codes are discussed in Error codes.
In all of the following calls, the parameter dbf refers to the pointer
returned from gdbm_open (or gdbm_fd_open, described below).
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.
In case of error, the function behaves like gdbm_open and
does not close fd. This can be altered by the following
value passed in the flags argument:
Close fd before exiting on error.
This is a general purpose interface function, that combines the
possibilities of gdbm_open and gdbm_fd_open2, and offers additional control over how the
database is locked.
The parameters name and flags have the same meaning as for
gdbm_open. Additional information is supplied via spec.
If it is NULL, default values are assumed, so that
gdbm_open_ext(name, flags, NULL)
is equivalent to
gdbm_open(name, 0, flags, 0600, NULL)
The structure gdbm_open_spec contains at least the following
fields:
Unless set to -1, this is the file descriptor of the database
file obtained by a call to open(2), creat(2) or similar
functions. The function will act as gdbm_fd_open: it will
create and initialize the GDBM_FILE object using this file
descriptor.
Block size to be used when creating new database. 0 stands for
default value. See block_size, for a detailed discussion.
This field, together with the two fields described below, controls how
long will gdbm_open_ext wait if the database is locked by
another process. For a detailed discussion, File Locking.
Its possible values are:
If the database is locked, return NULL immediately. The
gdbm_errno variable will be set to GDBM_CANT_BE_READER
or GDBM_CANT_BE_READER, depending on the access mode, requested
by flags. This is the default.
If the database is locked, sleep for the amount of time defined by the
lock_interval field, and retry the attempt. In case of failure,
repeat until the lock is acquired, or total time spent exceeds
lock_timeout (see below).
If the database is locked, wait for it to become available for at
most the time interval set by the lock_timeout field. In the
contrast to the GDBM_LOCKWAIT_RETRY, this method does not
require multiple attempts and, consequently, does not use the
lock_interval field. The database is locked as soon as other
process relinquishes the lock. The drawback is that it relies on
delivery of a signal in case of timeout, so it is not advised to use
this method in multi-threaded programs.
Specifies the timeout for file locking operation, in case
lock_wait is GDBM_LOCKWAIT_RETRY or
GDBM_LOCKWAIT_SIGNAL.
See File Locking.
Specifies the time interval between two successive locking attempts. Used
if lock_wait is GDBM_LOCKWAIT_RETRY.
See File Locking.
The values of lock_wait, lock_timeout and
lock_interval fields are ignored if the GDBM_NOLOCK bit
is set in flags parameter.
A macro for static initialization of struct gdbm_open_spec
variable with default values. Example usage:
struct gdbm_open_spec spec = GDBM_OPEN_SPEC_INITIALIZER;
This sets fd = -1, mode = 0600,
lock_wait = GDBM_LOCKWAIT_NONE, and initializes the rest of
fields with 0.
Initializes the structure pointed to by spec. The resulting
settings are the same as for GDBM_OPEN_SPEC_INITIALIZER.
Copy file ownership and mode from src to dst.
See chmod in chmod(2) man page, and See open a file in open(2) man page.
As a
matter of fact, both gdbm_open and gdbm_fd_open are just
wrappers over a call to gdbm_open_ext with appropriately
prepared last argument.
See chmod in chmod(2) man page, and See open a file in open(2) man page.
Next: Closing the database, Previous: Introduction to GNU dbm, Up: The GNU database manager [Contents][Index]