db_appinit



NAME

       db_appinit - initializing the DB environment


SYNOPSIS

       #include <db.h>

       char *
       db_version(int *major, int *minor, int *patch);

       int
       db_appinit(char *db_home,
            char *db_config[], DB_ENV *dbenv, int flags);

       int
       db_appexit(DB_ENV *dbenv);


DESCRIPTION

       The  DB  library  is  a family of groups of functions that
       provides a modular programming interface  to  transactions
       and  record-oriented  file  access.   The library includes
       support for transactions, locking, logging and  file  page
       caching,  as well as various indexed access methods.  Many
       of the functional groups  (e.g.,  the  file  page  caching
       functions)  are  useful  independent of the other DB func-
       tions, although  some  functional  groups  are  explicitly
       based  on  other functional groups (e.g., transactions and
       logging).  For a general description of  the  DB  package,
       see db_intro(3).

  db_version
       The db_version function returns a pointer to a string con-
       taining DB version information.  If major is non-NULL, the
       major version of the DB release is stored in the memory it
       references.  If minor is non-NULL, the  minor  version  of
       the  DB release is stored in the memory it references.  If
       patch is non-NULL, the patch version of the DB release  is
       stored in the memory it references.

  db_appinit
       The  db_appinit function provides a simple way to initial-
       ize and configure the DB environment.  It is not necessary
       that  it be called, but it provides a method of creating a
       consistent environment for processes using one or more  of
       the features of DB.

       The  db_home  and  db_config  arguments  to db_appinit are
       described in the section below entitled ``FILE NAMING''.

       The flags argument specifies the subsystems that are  ini-
       tialized  and  how the environment affects DB file naming,
       among other things.   The  flags  value  is  specified  by
       or'ing together one or more of the following values:


            db_deadlock(1), as well.

       DB_INIT_LOG
            Initialize  the  log  subsystem; see db_log(3).  This
            subsystem is used when recovery from  application  or
            system failure is important.

       DB_INIT_MPOOL
            Initialize  the  mpool  subsystem;  see  db_mpool(3).
            This subsystem is used whenever  the  application  is
            using the DB access methods for any purpose.

       DB_INIT_TXN
            Initialize  the transaction subsystem; see db_txn(3).
            This subsystem is used  when  atomicity  of  multiple
            operations   and   recovery   are   important.    The
            DB_INIT_TXN flag implies the DB_INIT_LOG flag.

       DB_MPOOL_PRIVATE
            Create a private memory  pool  (see  db_mpool(3)  for
            further  information).   Ignored unless DB_INIT_MPOOL
            is also specified.

       DB_NOMMAP
            Do not map any files  within  this  environment  (see
            db_mpool(3) for further information).  Ignored unless
            DB_INIT_MPOOL is also specified.

       DB_RECOVER
            Run normal recovery on this environment before  open-
            ing  it  for  normal  use.   If this flag is set, the
            DB_CREATE, DB_INIT_TXN, and  DB_INIT_LOG  flags  must
            also  be  set  since  the regions will be removed and
            recreated.  For further information, consult the  man
            page for db_recover(1).

       DB_RECOVER_FATAL
            Run  catastrophic recovery on this environment before
            opening it for normal use.  If this flag is set,  the
            DB_CREATE,  DB_INIT_TXN,  and  DB_INIT_LOG flags must
            also be set since the regions  will  be  removed  and
            recreated.   For further information, consult the man
            page for db_recover(1).

       DB_THREAD
            Ensure that handles returned by the DB subsystems are
            useable  by multiple threads within a single process,
            i.e., that the  system  is  ``free-threaded''.   (See
            db_lock(3),  db_log(3),  db_mpool(3),  db_open(3) and
            db_txn(3) for more information.)

       DB_TXN_NOSYNC
            On transaction commit, do not synchronously flush the
            log (see db_txn(3) for further information).  Ignored
            The DB process' environment may be permitted to spec-
            ify information to be used when naming files (see the
            section entitled ``FILE NAMING'' below).  As  permit-
            ting users to specify which files are used can create
            security problems, if the DB_USE_ENVIRON_ROOT flag is
            set,  environment  information  will be used for file
            naming only for users with a user-ID matching that of
            the  superuser  (specifically,  users  for  whom  the
            getuid system call returns the user-ID 0).

       The DB environment is configured based on the dbenv  argu-
       ment  to  db_appinit, which is a pointer to a structure of
       type DB_ENV (typedef'd in <db.h>).  It  is  expected  that
       applications  will  use  a  single DB_ENV structure as the
       argument to all of the subsystems in the DB  package.   In
       order  to ensure compatibility with future releases of DB,
       all fields of the DB_ENV structure that are not explicitly
       set  should  be initialized to 0 before the first time the
       structure is used.  Do this  by  declaring  the  structure
       external  or  static,  or by calling the C library routine
       bzero(3) or memset(3).

       The fields of the DB_ENV structure used by db_appinit  are
       described  below.   As  references to the DB_ENV structure
       may be maintained by db_appinit, it is necessary that  the
       DB_ENV  structure  and memory it references be valid until
       the db_appexit function is called.  The dbenv argument may
       not be NULL.  If any of the fields of the dbenv are set to
       0, defaults appropriate for the system are used where pos-
       sible.

       The  following  fields in the DB_ENV structure may be ini-
       tialized before calling db_appinit:

       void (*db_errcall)(char *db_errpfx, char *buffer);
            When an error occurs in  the  DB  package,  an  errno
            value  is  returned  by the function.  In some cases,
            however, the errno value may be insufficient to  com-
            pletely describe the cause of the error.

            If  db_errcall  is  non-NULL,  it  may be called with
            additional error information.  The db_errpfx argument
            is  the  current  environment's db_errpfx field.  The
            buffer argument contains a nul-terminated string with
            the additional information.

            This  error  logging  facility should not be required
            for normal operation, but may be useful in  debugging
            applications.

       FILE *db_errfile;
            The   db_errfile   field  behaves  similarly  to  the
            db_errcall field, except that the  error  message  is
            written to the file stream represented by db_errfile.

       int db_verbose;
            Include informational and debugging messages as  well
            as  error  messages  in the db_errcall and db_errfile
            output.

       Each of  the  open  functions  that  db_appinit  may  call
       (lock_open, log_open, memp_open and txn_open) is called as
       follows, where the DB_CREATE flag is optional:

            XXX_open(NULL, DB_CREATE,
               S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP, dbenv)

       This call will cause each subsystem to construct pathnames
       as  described in the section on ``FILE NAMING''.  The sub-
       system has permission to read and write  underlying  files
       as  necessary,  and optionally to create files.  (All cre-
       ated files will be created readable and writeable  by  the
       owner and the group.  The group ownership of created files
       is based on the system and directory defaults, and is  not
       further specified by DB.)

       In  addition,  the  dbenv  argument  is passed to the open
       functions of any  subsystems  initialized  by  db_appinit.
       For  this  reason the fields of the DB_ENV structure rele-
       vant to the subsystems being initialized  must  themselves
       be  initialized before db_appinit is called.  See the man-
       ual page for each subsystem for a list of these fields and
       their uses.

       The return value from each of these calls is placed in the
       appropriate field of the DB_ENV structure:

       DB_LOCKTAB *lk_info;
            The return value of the lock_open(3) call.

       DB_LOG *lg_info;
            The return value of the log_open(3) call.

       DB_MPOOL *mp_info;
            The return value of the memp_open(3) call.

       DB_TXNMGR *tx_info;
            The return value of the txn_open(3) call.

       In general, these fields are not directly used by applica-
       tions;  subsystems of DB that use these fields will simply
       reference them using the DB_ENV  argument  passed  to  the
       subsystem.

       For  example,  an  application  using  the  DB hash access
       method functions to access  a  database  will  first  call
       db_open  passing  it  the DB_ENV argument filled in by the
       initial call to db_appinit.  Then, all future calls to the
       hash  access method functions for that database will auto-
       The db_appinit function returns  the  value  of  errno  on
       failure and 0 on success.

  db_appexit
       The  db_appexit function closes the initialized DB subsys-
       tems, freeing any  allocated  resources  and  closing  any
       underlying subsystems.

       When  multiple threads are using the DB_ENV handle concur-
       rently, only a single thread may call the db_appexit func-
       tion.

       The  db_appexit  function  returns  the  value of errno on
       failure and 0 on success.


FILE NAMING

       The most important task of db_appinit is to structure file
       naming within DB.

       Each  of the locking, logging, memory pool and transaction
       subsystems of DB require shared memory regions, backed  by
       the  filesystem.   Further,  cooperating  applications (or
       multiple invocations of the same application)  must  agree
       on  the  location  of  the shared memory regions and other
       files used by the DB subsystems, the log files used by the
       logging subsystem, and, of course, the data files.

       Although  it  is possible to specify full pathnames to all
       DB functions, this is cumbersome and requires that  appli-
       cations  be recompiled when database files are moved.  The
       db_appinit function makes it possible  to  place  database
       files  in  a single directory, or in multiple directories,
       grouped by their function within the database.

       Applications are normally expected  to  specify  a  single
       directory  home for their database.  This can be done eas-
       ily in the call to db_appinit by specifying  a  value  for
       the  db_home  argument.  There are more complex configura-
       tions where it may be desirable  to  override  db_home  or
       provide supplementary path information.

       The  following  describes  the possible ways in which file
       naming information may be specified  to  the  DB  library.
       The  specific  circumstances and order in which these ways
       are applied are described in a subsequent paragraph.

       db_home
            If the db_home argument to  db_appinit  is  non-NULL,
            its value may be used as the database home, and files
            named relative to its path.

       DB_HOME
            If the  DB_HOME  environment  variable  is  set  when
            db_appinit  is  called,  its value may be used as the
            ues will be ignored.  The  db_config  array  must  be
            NULL terminated.

       DB_CONFIG
            The same information specified to the db_config argu-
            ment to db_appinit may be specified using a  configu-
            ration  file.   If a database home directory has been
            specified (either by  the  application  specifying  a
            non-NULL  db_home  argument  to db_appinit, or by the
            application setting the DB_USE_ENVIRON or DB_USE_ENV-
            IRON_ROOT  flags and the DB_HOME environment variable
            being set),  any  file  named  ``DB_CONFIG''  in  the
            database home directory will be read for lines of the
            format ``NAME VALUE''.  The whitespace delimiting the
            two  parts  of the line may be one or more <space> or
            <tab> characters.  (Leading or trailing  <space>  and
            <tab>  characters are discarded.)  All empty lines or
            lines whose first non-whitespace character is a  hash
            character  (``#'')  will  be ignored.  Each line must
            specify both the NAME and the VALUE of the pair.  All
            lines  with unrecognized NAME values will be ignored.

       The following ``NAME VALUE'' pairs in the db_config  argu-
       ment and the DB_CONFIG file are currently supported by DB.

       DB_DATA_DIR
            The path of a directory to be used as the location of
            the  access  method data files, e.g., paths specified
            to the db_open(3) function will be relative  to  this
            path.

            The  DB_DATA_DIR  paths  are additive, and specifying
            more than one will result in each specified directory
            being  searched for database data files.  If multiple
            paths are specified, created data files  will  always
            be created in the first directory specified.

       DB_LOG_DIR
            The path of a directory to be used as the location of
            logging files, e.g., files created by  the  db_log(3)
            subsystem  will  be  relative  to this directory.  If
            specified, this is the directory name  that  will  be
            passed to log_open(3).

       DB_TMP_DIR
            The path of a directory to be used as the location of
            temporary files, e.g., files created to back  in-mem-
            ory  access method databases will be created relative
            to this path.  Note, these temporary files can poten-
            tially  be  quite large, depending on the size of the
            database.

            If DB_TMP_DIR is not specified, the  following  envi-
            ronment  variables  are checked in order: ``TMPDIR'',

       processing proceeds  sequentially  through  the  following
       steps:

       ``/''
            If  any file name specified to any DB function begins
            with a leading slash, that file name is used  without
            modification by DB.

       DB_CONFIG
            If    a    relevant   configuration   string   (e.g.,
            DB_DATA_DIR), is specified in the DB_CONFIG  configu-
            ration  file,  the VALUE from the ``NAME VALUE'' pair
            is prepended  to  the  current  file  name.   If  the
            resulting  file name begins with a leading slash, the
            file name is used without further modification by DB.

            The  DB_CONFIG configuration file is intended to per-
            mit systems to customize file location for a database
            independent of applications using that database.  For
            example,  a  database  administrator  can  move   the
            database  log  and data files to a different location
            without application recompilation.

       db_config
            If   a   relevant   configuration    string    (e.g.,
            DB_DATA_DIR),  is specified in the db_config argument
            and is not specified in the DB_CONFIG file, the VALUE
            from the ``NAME VALUE'' pair is prepended to the cur-
            rent file name.  If the resulting  file  name  begins
            with  a  leading slash, the file name is used without
            further modification by DB.

            The db_config argument is intended to permit applica-
            tions to customize file location for a database.  For
            example, an application writer can place  data  files
            and  log files in different directories, or instanti-
            ate a new log directory  each  time  the  application
            runs.
       DB_HOME
            If the DB_HOME environment variable was set, (and the
            application has set the appropriate DB_USE_ENVIRON or
            DB_USE_ENVIRON_ROOT  environment variable), its value
            is prepended  to  the  current  file  name.   If  the
            resulting  file name begins with a leading slash, the
            file name is used without further modification by DB.

            The  DB_HOME environment variable is intended to per-
            mit  users  and  system  administrators  to  override
            application and installation defaults, e.g.,

                 env DB_HOME=/database/my_home application

            Alternatively,  application writers are encouraged to
            support the -h option  found  in  the  supporting  DB
            Finally,  all  file names are interpreted relative to
            the current working directory of the process.

       The common model for a DB environment is  one  where  only
       the DB_HOME environment variable, or the db_home argument,
       is specified.  In this case, all data files will  be  pre-
       sumed to be relative to that directory, and all files cre-
       ated by the DB subsystems will be created in  that  direc-
       tory.

       The more complex model for a transaction environment might
       be one where a database home is  specified,  using  either
       the  DB_HOME  environment variable or the db_home argument
       to db_appinit, and then DB_DATA_DIR and DB_LOG_DIR are set
       to  the  relative path names of directories underneath the
       home directory using the db_config argument to  db_appinit
       or the DB_CONFIG file.


EXAMPLES

       Store all files in the directory /a/database:

              db_appinit("/a/database", NULL, ...);

       Create  temporary  backing  files in /b/temporary, and all
       other files in /a/database:

              char *config[] = {
                  "DB_TMP_DIR /b/temporary",
                  NULL
              };

              db_appinit("/a/database", config, ...);

       Store data files  in  /a/database/datadir,  log  files  in
       /a/database/logdir,  and  all other files in the directory
       /a/database:

              char *config[] = {
                  "DB_DATA datadir",
                  "DB_LOG logdir",
                  NULL
              };

              db_appinit("/a/database", config, ...);

       Store data files in /a/database/data1  and  /b/data2,  and
       all  other  files  in the directory /a/database.  Any data
       files that are created will be created in /b/data2:

              char *config[] = {
                  "DB_DATA /b/data2",
                  "DB_DATA data1",
                  NULL
              };

       lock_open(3), lock_unlink(3), log_compare(3), log_get(3),
       log_open(3), log_unlink(3), malloc(3), memcpy(3),
       memp_open(3), memp_unlink(3), memset(3), realloc(3),
       stat(2), strchr(3), strcmp(3), strcpy(3), strdup(3),
       strerror(3), strlen(3), strsep(3), time(3),
       txn_checkpoint(3), txn_open(3), and txn_unlink(3).

       In addition, the db_appinit function may fail  and  return
       errno for the following conditions:

       [EINVAL]
            An invalid flag value or parameter was specified.

            The  DB_THREAD  flag  was specified and spinlocks are
            not implemented for this architecture.

            The DB_HOME or TMPDIR environment variables were  set
            but empty.

            An incorrectly formatted ``NAME VALUE'' entry or line
            was found.

       [ENOSPC]
            HP-UX only: a previously created DB  environment  for
            this process still exists.

       The  db_appexit function may fail and return errno for any
       of the errors specified for the following DB  and  library
       functions: lock_close(3), log_close(3), memp_close(3), and
       txn_close(3).


BUGS

       Due to the constraints of the PA-RISC memory architecture,
       HP-UX  does not allow a process to map a file into its ad-
       dress space multiple times.  For this reason, each DB  en-
       vironment  may  be opened only once by a process on HP-UX,
       i.e., calls to appinit will fail if the specified DB envi-
       ronment has been opened and not subsequently closed.


SEE ALSO

       db_archive(1), db_checkpoint(1), db_deadlock(1), db_dump(1),
       db_load(1), db_recover(1), db_stat(1), db_intro(3),
       db_appinit(3), db_cursor(3), db_dbm(3), db_jump(3), db_lock(3),
       db_log(3), db_mpool(3), db_open(3), db_thread(3), db_txn(3)