17 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 return value will be -1 upon failure, or 0 upon success. The global variable gdbm_errno will be set upon failure.

The valid options are:

GDBM_SETCACHESIZE

GDBM_CACHESIZE

Set the size of the internal bucket cache. The value should point to a size_t holding the desired cache size, or the constant GDBM_CACHE_AUTO, to set the best cache size automatically.

By default, a newly open database is configured to adapt the cache size to the number of index buckets in the database file. This provides for the best performance.

Use this option if you wish to limit the memory usage at the expense of performance. If you chose to do so, please bear in mind that cache becomes effective when its size is greater then 2/3 of the number of index bucket counts in the database. The best performance results are achieved when cache size equals the number of buckets. For example:

size_t bn;
gdbm_bucket_count (dbf, &bn);
ret = gdbm_setopt (dbf, GDBM_SETCACHESIZE, &bn, sizeof (bn));

To set the best cache size, use the constant GDBM_CACHE_AUTO:

size_t bn = GDBM_CACHE_AUTO;
ret = gdbm_setopt (dbf, GDBM_SETCACHESIZE, &bn, sizeof (bn));

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 an int variable where to store the flags. On success, its value will be similar to the flags used when opening the database (see gdbm_open), except that it will reflect 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);
  }

GDBM_GETBLOCKSIZE

Return the block size in bytes. The value should point to int.