File: gdbm.info,  Node: Options,  Next: Locking,  Prev: Crash Tolerance,  Up: Top

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 (*note gdbm_open: 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.  *Note 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'.