15 Setting options

Gdbm supports the ability to set certain options on an already open database.

gdbm interface: int gdbm_setopt (GDBM_FILE dbf, int option, void *value, int size)

Sets an option on the database or returns the value of an option.

The parameters are:

dbf: The pointer returned by gdbm_open.
option: The option to be set or retrieved.
value: A pointer to the value to which option will be set or where to place the option value (depending on the option).
size: The length of the data pointed to by value.

The valid options are:

GDBM_SETCACHESIZE

GDBM_CACHESIZE

Set the size of the internal bucket cache. This option may only be set once on each GDBM_FILE descriptor, and is set automatically to 100 upon the first access to the database. The value should point to a size_t holding the desired cache size.

The ‘GDBM_CACHESIZE’ option is provided for compatibility with earlier versions.

GDBM_GETCACHESIZE

Return the size of the internal bucket cache. The value should point to a size_t variable, where the size will be stored.

GDBM_GETFLAGS

Return the flags describing the state of the database. The value should point to a int variable where to store the flags. The return is the same as the flags used when opening the database (see section gdbm_open), except that it reflects the current state (which may have been altered by another calls to gdbm_setopt.

GDBM_FASTMODE

Enable or disable the fast writes mode, i.e. writes without subsequent synchronization. The value should point to an integer: ‘TRUE’ to enable fast mode, and ‘FALSE’ to disable it.

This option is retained for compatibility with previous versions of gdbm. Its effect is the reverse of GDBM_SETSYNCMODE (see below).

GDBM_SETSYNCMODE

GDBM_SYNCMODE

Turn on or off file system synchronization operations. This setting defaults to off. The value should point to an integer: ‘TRUE’ to turn synchronization on, and ‘FALSE’ to turn it off.

Note, that this option is a reverse of GDBM_FASTMODE, i.e. calling GDBM_SETSYNCMODE with ‘TRUE’ has the same effect as calling GDBM_FASTMODE with ‘FALSE’.

The ‘GDBM_SYNCMODE’ option is provided for compatibility with earlier versions.

GDBM_GETSYNCMODE

Return the current synchronization status. The value should point to an int where the status will be stored.

GDBM_SETCENTFREE

GDBM_CENTFREE

NOTICE: This feature is still under study.

Set central free block pool to either on or off. The default is off, which is how previous versions of gdbm handled free blocks. If set, this option causes all subsequent free blocks to be placed in the global pool, allowing (in theory) more file space to be reused more quickly. The value should point to an integer: ‘TRUE’ to turn central block pool on, and ‘FALSE’ to turn it off.

The ‘GDBM_CENTFREE’ option is provided for compatibility with earlier versions.

GDBM_SETCOALESCEBLKS

GDBM_COALESCEBLKS

NOTICE: This feature is still under study.

Set free block merging to either on or off. The default is off, which is how previous versions of gdbm handled free blocks. If set, this option causes adjacent free blocks to be merged. This can become a CPU expensive process with time, though, especially if used in conjunction with GDBM_CENTFREE. The value should point to an integer: ‘TRUE’ to turn free block merging on, and ‘FALSE’ to turn it off.

GDBM_GETCOALESCEBLKS

Return the current status of free block merging. The value should point to an int where the status will be stored.

GDBM_SETMAXMAPSIZE

Sets maximum size of a memory mapped region. The value should point to a value of type size_t, unsigned long or unsigned. The actual value is rounded to the nearest page boundary (the page size is obtained from sysconf(_SC_PAGESIZE)).

GDBM_GETMAXMAPSIZE

Return the maximum size of a memory mapped region. The value should point to a value of type size_t where to return the data.

GDBM_SETMMAP

Enable or disable memory mapping mode. The value should point to an integer: ‘TRUE’ to enable memory mapping or ‘FALSE’ to disable it.

GDBM_GETMMAP

Check whether memory mapping is enabled. The value should point to an integer where to return the status.

GDBM_GETDBNAME

Return the name of the database disk file. The value should point to a variable of type char**. A pointer to the newly allocated copy of the file name will be placed there. The caller is responsible for freeing this memory when no longer needed. For example:

char *name;

if (gdbm_setopt (dbf, GDBM_GETDBNAME, &name, sizeof (name)))
  {
     fprintf (stderr, "gdbm_setopt failed: %s\n",
              gdbm_strerror (gdbm_errno));
  }
else
  {
    printf ("database name: %s\n", name);
    free (name);
  }

The return value will be ‘-1’ upon failure, or ‘0’ upon success. The global variable gdbm_errno will be set upon failure.

For instance, to set a database to use a cache of 10, after opening it with gdbm_open, but prior to accessing it in any way, the following code could be used:

int value = 10;
ret = gdbm_setopt (dbf, GDBM_CACHESIZE, &value, sizeof (int));

This document was generated on January 24, 2014 using texi2html 5.0.