File: gdbm.info,  Node: Open,  Next: Close,  Prev: Intro,  Up: Top

3 Opening the database
**********************

 -- gdbm interface: GDBM_FILE gdbm_open (const char *NAME, int
          BLOCK_SIZE, int FLAGS, int MODE, void (*FATAL_FUNC)(const char
          *))
     Opens or creates a 'GDBM' database file.

     The arguments are:

     NAME
          The name of the file (the complete name, 'GDBM' does not
          append any characters to this name).

     BLOCK_SIZE
          This parameter is used only when 'gdbm_open' has to create a
          new database file and represents the size of a single transfer
          from disk to memory.  If its 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'.

     FLAGS
          If 'flags' is set to 'GDBM_READER', the user wants to just
          read the database and any call to 'gdbm_store' or
          'gdbm_delete' will fail.  Many readers can access the database
          at the same time.  If 'flags' is set to 'GDBM_WRITER', the
          user wants both read and write access to the database and
          requires exclusive access.  If 'flags' is 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 'flags' is 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.  If an existing
          database file is opened with the 'GDBM_NEWDB' flag, the
          existing data are destroyed, and an empty database structure
          is created in its place.

          The following constants may also be logically or'd into the
          database flags:

           -- gdbm_open flag: GDBM_CLOEXEC
               Set the close-on-exec flag on the database file
               descriptor.  The 'libc' must support the 'O_CLOEXEC' flag
               (*note (open(2))O_CLOEXEC::).

           -- gdbm_open flag: GDBM_NOLOCK
               Don't lock the database file.  Use this flag if you
               intend to do locking separately.  *Note Locking::.

           -- gdbm_open flag: GDBM_NOMMAP
               Disable memory mapping mechanism.  Note, that this
               degrades performance.

           -- gdbm_open flag: GDBM_PREREAD
               When mapping 'GDBM' file to memory, read its contents
               immediately, instead of when needed ("prefault reading").
               This can be advantageous if you open a _read-only_
               database and are going to do a lot of look-ups on it.  In
               this case entire database will be pre-read and look-ups
               will operate on an in-memory copy.  In contrast,
               'GDBM_PREREAD' should not be used if you open a database
               (even in read-only mode) only to do a couple of look-ups.
               Finally, never use 'GDBM_PREREAD' when opening a database
               for updates, especially for inserts: this will degrade
               performance.

               This flag has no effect if 'GDBM_NOMMAP' is given, or if
               the operating system does not support prefault reading.
               It is known to work on Linux and FreeBSD kernels.

           -- gdbm_open flag: GDBM_XVERIFY
               Enable additional consistency checks.  With this flag,
               eventual corruptions of the database are discovered when
               opening it, instead of when a corrupted structure is read
               during normal operation.  However, on large databases, it
               can slow down the opening process.

               *Note Additional functions::.

          The following additional flags are valid when the database is
          opened for writing (i.e.  together with 'GDBM_WRITER',
          'GDBM_WRCREAT', or 'GDBM_NEWDB'):

           -- gdbm_open flag: GDBM_SYNC
               Synchronize all database operations to disk immediately.
               Notice, that this option entails severe performance
               degradation and does not necessarily ensure that the
               resulting database state is consistent.  In general, we
               discourage its use (*note Sync::).  *Note Crash
               Tolerance::, for a discussion of how to ensure database
               consistency with minimal performance overhead.

           -- gdbm_open flag: GDBM_FAST
               A reverse of 'GDBM_SYNC'.  Synchronize writes only when
               needed.  This is the default.  The flag is provided for
               compatibility with previous versions of 'GDBM'.

          The following flags can be used together with 'GDBM_NEWDB'.
          They also take effect when used with 'GDBM_WRCREAT', if the
          requested database file doesn't exist:

           -- gdbm_open flag: GDBM_BSEXACT
               If this flag is set and the requested BLOCK_SIZE cannot
               be used without adjustment, 'gdbm_open' will refuse to
               create the databases.  In this case it will set the
               'gdbm_errno' variable to 'GDBM_BLOCK_SIZE_ERROR' and
               return 'NULL'.

           -- gdbm_open flag: GDBM_NUMSYNC
               Useful only together with 'GDBM_NEWDB', this bit
               instructs 'gdbm_open' to create new database in "extended
               database format", a format best suitable for effective
               crash recovery.  *Note Numsync::, for a detailed
               discussion of this format, and *note Crash Tolerance::,
               for a discussion of crash recovery.

     MODE
          File mode(1), which is used if the file is created.

     FATAL_FUNC
          This parameter is deprecated and must always be 'NULL'.

          Early versions of 'GDBM' (prior to 1.13) lacked proper error
          handling and would abort on any "fatal" error (such as out of
          memory condition, disk write error, or the like).  In these
          versions, 'fatal_func' was provided as a hook, allowing the
          caller to do proper cleanup before such abnormal exit.  As of
          version 1.26, this functionality is deprecated, although still
          supported for backward compatibility.

     The return value, is the pointer needed by all other functions to
     access that 'GDBM' file.  If the return is the 'NULL' pointer,
     'gdbm_open' was not successful.  The errors can be found in
     'gdbm_errno' variable (*note gdbm_errno: Variables.).  Available
     error codes are discussed in *note Error codes::.

     In all of the following calls, the parameter DBF refers to the
     pointer returned from 'gdbm_open' (or 'gdbm_fd_open', described
     below).

 -- gdbm interface: GDBM_FILE gdbm_fd_open (int FD, const char *NAME,
          int BLOCK_SIZE, int FLAGS, 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 'open'(2), 'creat'(2) or similar functions.  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.

     In case of error, the function behaves like 'gdbm_open' and _does
     not close_ FD.  This can be altered by the following value passed
     in the FLAGS argument:

      -- gdbm_open flag: GDBM_CLOERROR
          Close FD before exiting on error.

 -- gdbm interface: GDBM_FILE gdbm_open_ext (char const *NAME, int
          FLAGS, struct gdbm_open_spec const *SPEC)
     This is a general purpose interface function, that combines the
     possibilities of 'gdbm_open' and 'gdbm_fd_open'(2), and offers
     additional control over how the database is locked.

     The parameters NAME and FLAGS have the same meaning as for
     'gdbm_open'.  Additional information is supplied via SPEC.  If it
     is 'NULL', default values are assumed, so that

          gdbm_open_ext(NAME, FLAGS, NULL)

     is equivalent to

          gdbm_open(NAME, 0, FLAGS, 0600, NULL)

     The structure 'gdbm_open_spec' contains at least the following
     fields:

      -- member of gdbm_open_spec: int fd
          Unless set to '-1', this is the file descriptor of the
          database file obtained by a call to 'open'(2), 'creat'(2) or
          similar functions.  The function will act as 'gdbm_fd_open':
          it will create and initialize the 'GDBM_FILE' object using
          this file descriptor.

      -- member of gdbm_open_spec: int mode
          File mode(3), which is used if the file is created.

      -- member of gdbm_open_spec: int block_size
          Block size to be used when creating new database.  '0' stands
          for default value.  *Note block_size::, for a detailed
          discussion.

      -- member of gdbm_open_spec: int lock_wait
          This field, together with the two fields described below,
          controls how long will 'gdbm_open_ext' wait if the database is
          locked by another process.  For a detailed discussion, *note
          Locking::.  Its possible values are:

           -- lock_wait: GDBM_LOCKWAIT_NONE
               If the database is locked, return 'NULL' immediately.
               The 'gdbm_errno' variable will be set to
               'GDBM_CANT_BE_READER' or 'GDBM_CANT_BE_READER', depending
               on the access mode, requested by FLAGS.  This is the
               default.

           -- lock_wait: GDBM_LOCKWAIT_RETRY
               If the database is locked, sleep for the amount of time
               defined by the 'lock_interval' field, and retry the
               attempt.  In case of failure, repeat until the lock is
               acquired, or total time spent exceeds 'lock_timeout' (see
               below).

           -- lock_wait: GDBM_LOCKWAIT_SIGNAL
               If the database is locked, wait for it to become
               available for at most the time interval set by the
               'lock_timeout' field.  In the contrast to the
               'GDBM_LOCKWAIT_RETRY', this method does not require
               multiple attempts and, consequently, does not use the
               'lock_interval' field.  The database is locked as soon as
               other process relinquishes the lock.  The drawback is
               that it relies on delivery of a signal in case of
               timeout, so it is not advised to use this method in
               multi-threaded programs.

      -- member of gdbm_open_spec: struct timespec lock_timeout
          Specifies the timeout for file locking operation, in case
          'lock_wait' is 'GDBM_LOCKWAIT_RETRY' or
          'GDBM_LOCKWAIT_SIGNAL'.

          *Note Locking::.

      -- member of gdbm_open_spec: struct timespec lock_interval
          Specifies the time interval between two successive locking
          attempts.  Used if 'lock_wait' is 'GDBM_LOCKWAIT_RETRY'.

          *Note Locking::.

     The values of 'lock_wait', 'lock_timeout' and 'lock_interval'
     fields are ignored if the 'GDBM_NOLOCK' bit is set in FLAGS
     parameter.

 -- struct gdbm_open_spec: GDBM_OPEN_SPEC_INITIALIZER
     A macro for static initialization of 'struct gdbm_open_spec'
     variable with default values.  Example usage:

          struct gdbm_open_spec spec = GDBM_OPEN_SPEC_INITIALIZER;

     This sets 'fd = -1', 'mode = 0600', 'lock_wait =
     GDBM_LOCKWAIT_NONE', and initializes the rest of fields with '0'.

 -- gdbm interface: void gdbm_open_spec_init (struct gdbm_open_spec
          *SPEC)
     Initializes the structure pointed to by SPEC.  The resulting
     settings are the same as for 'GDBM_OPEN_SPEC_INITIALIZER'.

 -- gdbm interface: int gdbm_copy_meta (GDBM_FILE DST, GDBM_FILE SRC)
     Copy file ownership and mode from SRC to DST.

   ---------- Footnotes ----------

   (1) *Note (chmod(2))chmod::, and *Note open a file: (open(2))open.

   (2) As a matter of fact, both 'gdbm_open' and 'gdbm_fd_open' are just
wrappers over a call to 'gdbm_open_ext' with appropriately prepared last
argument.

   (3) *Note (chmod(2))chmod::, and *Note open a file: (open(2))open.