|Official GNU Software|
4 Opening the database.
- gdbm interface: GDBM_FILE gdbm_open (const char *name, int block_size, int flags, int mode, void (*fatal_func)(const char *))
gdbmsystem. 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,
gdbmdoes 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’.
flagsis set to ‘GDBM_READER’, the user wants to just read the database and any call to
gdbm_deletewill fail. Many readers can access the database at the same time. If
flagsis set to ‘GDBM_WRITER’, the user wants both read and write access to the database and requires exclusive access. If
flagsis 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
flagsis 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 may also be logically or’d into the database flags: ‘GDBM_SYNC’, which causes all database operations to be synchronized to the disk, ‘GDBM_NOLOCK’, which prevents the library from performing any locking on the database file, and ‘GDBM_NOMMAP’, which disables the memory mapping mechanism. The option ‘GDBM_FAST’ is now obsolete, since
gdbmdefaults to no-sync mode.
If this flag is set and the requested block_size cannot be used without adjustment,
gdbm_openwill refuse to create the databases. In this case it will set the ‘gdbm_errno’ variable to ‘GDBM_BLOCK_SIZE_ERROR’ and return ‘NULL’.
If the host ‘open’ call (open(2)) supports the ‘O_CLOEXEC’ flag, the ‘GDBM_CLOEXEC’ can be or’d into the flags, to enable the close-on-exec flag for the database file descriptor.
A function for
gdbmto call if it detects a fatal error. The only parameter of this function is a string. If the value of ‘NULL’ is provided,
gdbmwill use a default function.
The return value, is the pointer needed by all other functions to access that
gdbmfile. If the return is the ‘NULL’ pointer,
gdbm_openwas not successful. The errors can be found in
gdbm_errnovariable (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 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
creat(2) or similar funcionss. 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.