Initializes gdbm
system. If the file has a size of zero bytes, a file
initialization procedure is performed, setting up the initial structure in the
file.
The arguments are:
The name of the file (the complete name, gdbm
does not append any
characters to this name).
It is used during initialization to determine the size of various
constructs. It is the size of a single transfer from disk to
memory. This parameter is ignored if the file has been previously
initialized. If the 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.
The following constants may also be logically or’d into the database flags:
GDBM_SYNC
Synchronize all database operations to disk immediately. This provides for the best database consistency at the expense of severe performance degradation.
GDBM_FAST
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
.
GDBM_NUMSYNC
Useful only together with GDBM_NEWDB
, this bit instructs
gdbm_open
to create new database in extended database
format, suitable for effective crash recovery. See Numsync, for a
detailed discussion of this format, and Crash Tolerance, for a
discussion of crash recovery.
GDBM_NOLOCK
Don’t lock the database file. Use this flag if you intend to do locking separately.
GDBM_NOMMAP
Disable memory mapping mechanism. This degrades performance.
GDBM_PREREAD
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 the
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.
GDBM_BSEXACT
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
.
GDBM_CLOEXEC
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).
GDBM_XVERIFY
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.
File mode1, which is used if the file is created.
A function for gdbm
to call if it detects a fatal error. The only
parameter of this function is a string. If the value of NULL
is
provided, gdbm
will use a default function.
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
.
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.
Copy file ownership and mode from src to dst.