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.24, 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: 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.