Options (GDBM manual)

18 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:

Option: GDBM_SETCACHESIZE

Option: 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 adjust the cache size automatically.

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

If another value is set, it is adjusted to the nearest larger power of two.

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 request the automatically adjustable cache size, use the constant GDBM_CACHE_AUTO:

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

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

Option: GDBM_SETCACHEAUTO

Controls whether the cache size will be adjusted automatically as needed. The value should point to an integer: TRUE to enable automatic cache adjustment and FALSE to disable it.

The following two calls are equivalent:

int t = TRUE;
gdbm_setopt (dbf, GDBM_SETCACHEAUTO, &t, sizeof (t));

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

Option: GDBM_GETCACHEAUTO: Return the state of the automatic cache size adjustment. The value should point to an integer which, upon successful return, will have the value TRUE if the automatic cache size adjustment is enabled and FALSE otherwise.

Option: 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).

Option: GDBM_GETDBFORMAT: Return the database format. The value should point to an int variable. Upon successful return, it will be set to ‘0’ if the database is in standard format and GDBM_NUMSYNC if it is in extended format. See Database format.

Option: GDBM_GETDIRDEPTH

Returns the directory depth: the number of initial (most significant) bits in hash value that are interpreted as index to the directory. The actual directory size can be computed as 1 << value.

The value argument should point to an int.

Option: GDBM_GETBUCKETSIZE: Returns the bucket capacity: maximum number of keys per bucket (int).

Option: 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.

Option: GDBM_SETSYNCMODE

Option: 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.

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

Option: GDBM_SETCENTFREE

Option: 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.

Option: GDBM_SETCOALESCEBLKS

Option: 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.

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

Option: 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)).

Option: 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.

Option: 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.

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

Option: 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);
  }

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