Next: , Previous: , Up: Top   [Contents][Index]


3 Opening the database

gdbm interface: GDBM_FILE gdbm_open (const char *name, int block_size, int flags, int mode, void (*fatal_func)(const char *))

Opens or creates a GDBM database file.

The arguments are:

name

The name of the file (the complete name, GDBM does not append any characters to this name).

block_size

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.

flags

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:

gdbm_open flag: 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_open flag: GDBM_NOLOCK

Don’t lock the database file. Use this flag if you intend to do locking separately. See Locking.

gdbm_open flag: GDBM_NOMMAP

Disable memory mapping mechanism. Note, that this degrades performance.

gdbm_open flag: 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 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_open flag: 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.

The following additional flags are valid when the database is opened for writing (i.e. together with GDBM_WRITER, GDBM_WRCREAT, or GDBM_NEWDB):

gdbm_open flag: GDBM_SYNC

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 Sync). See Crash Tolerance, for a discussion of how to ensure database consistency with minimal performance overhead.

gdbm_open flag: 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.

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:

gdbm_open flag: 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_open flag: GDBM_NUMSYNC

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, for a detailed discussion of this format, and Crash Tolerance, for a discussion of crash recovery.

mode

File mode1, which is used if the file is created.

fatal_func

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.22, 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).

gdbm interface: GDBM_FILE gdbm_fd_open (int fd, const char *name, int block_size, int flags, int mode, void (*fatal_func)(const char *))

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:

gdbm_open flag: GDBM_CLOERROR

Close fd before exiting on error.

gdbm interface: int gdbm_copy_meta (GDBM_FILE dst, GDBM_FILE src)

Copy file ownership and mode from src to dst.


Footnotes

(1)

See chmod in chmod(2) man page, and See open a file in open(2) man page.


Next: , Previous: , Up: Top   [Contents][Index]