# db_appinit

           #include <db.h>

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

           int
           db_appinit(char *db_home,
                char *db_config[], DB_ENV *dbenv, u_int32_t 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
           functions, 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
           containing 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
           initialize 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
           initialized  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_CREATE
                Cause  subsystems  to create any underlying files, as
                necessary.  (See db_lock(3), db_log(3),  db_mpool(3),
                db_open(3) and db_txn(3) for more information.)

           DB_INIT_LOCK
                Initialize  the lock subsystem; see db_lock(3).  This
                subsystem should be used when multiple  processes  or
                threads  are  going  to  be  reading and writing a DB
                database, so that they do  not  interfere  with  each
                other.   If all threads are accessing the database(s)
                read-only, then locking  is  unnecessary.   When  the
                DB_INIT_LOCK   flag   is  specified,  it  is  usually
                necessary   to    run    the    deadlock    detector,
                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
                opening  it for normal use.  If this flag is set, the
                DB_CREATE flag must also be  set  since  the  regions
                will be removed and recreated.

                The   db_appinit  function  returns  successfully  if
                DB_RECOVER is specified and no log files exist, so it
                is  necessary  to  ensure all necessary log files are
                present  before  running   recovery.    For   further
                information,  consult  the man page for db_archive(1)
                and 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 flag must also be  set  since  the  regions
                will be removed and recreated.

                The   db_appinit  function  returns  successfully  if
                DB_RECOVER is specified and no log files exist, so it
                is  necessary  to  ensure all necessary log files are
                present  before  running   recovery.    For   further
                information,  consult  the man page for db_archive(1)
                and 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
                unless DB_INIT_TXN is also specified.

           DB_USE_ENVIRON
                The DB  process'  environment  may  be  permitted  to
                specify information to be used when naming files (see
                the section  entitled  ``FILE  NAMING''  below).   As
                permitting  users to specify which files are used can
                create  security  problems,  environment  information
                will be used in file naming for all users only if the
                DB_USE_ENVIRON flag is set.

           DB_USE_ENVIRON_ROOT
                The DB  process'  environment  may  be  permitted  to
                specify information to be used when naming files (see
                the section  entitled  ``FILE  NAMING''  below).   As
                permitting  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
           argument  to db_appinit, which is a pointer to a structure
           of type DB_ENV (typedef'd in <db.h>).   Applications  will
           normally  use  the  same  DB_ENV structure (initialized by
           db_appinit(3)), as an argument to all of the subsystems in
           the DB package.

           References  to  the DB_ENV structure are maintained by DB,
           so it may not be discarded until the last close  function,
           corresponding  to  an  open  function  for which it was an
           argument, has returned.  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.  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 possible.

           The  following  fields  in  the  DB_ENV  structure  may be
           initialized 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
                completely 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.

                If  db_errpfx  is  non-NULL,  the  message  will   be
                preceded  by  the  string  referenced by db_errpfx, a
                colon (``:'') and  a  space.   The  message  will  be
                followed by a newline character.

           const char *db_errpfx;
                A  prefix  to  prepend to error messages.  Because DB
                does not copy the memory referenced by the  db_errpfx
                field,  the  application may modify the error message
                prefix at any time.

           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
           subsystem has permission  to  read  and  write  underlying
           files  as necessary, and optionally to create files.  (All
           created 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
           relevant  to  the  subsystems   being   initialized   must
           themselves  be  initialized  before  db_appinit is called.
           See the manual 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
           applications;  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
           automatically use the underlying shared memory buffer pool
           that  was  specified  by  the mp_info field of that DB_ENV
           argument.

           The single exception to this rule is  the  tx_info  field,
           which   applications   must   explicitly  specify  to  the
           txn_begin, txn_checkpoint and txn_close functions.

           Once the DB environment has been initialized by a call  to
           db_appinit,  no  fields  other  than  db_errpfx  should be
           modified.

           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
           subsystems, freeing any allocated  resources  and  closing
           any underlying subsystems.

           When   multiple   threads  are  using  the  DB_ENV  handle
           concurrently, only a single thread may call the db_appexit
           function.

           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
           applications  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
           easily in the call to db_appinit by specifying a value for
           the   db_home   argument.    There   are   more    complex
           configurations  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
                database  home, and files named relative to its path.

           db_config
                The db_config argument to db_appinit may be  used  to
                specify  an  array of character strings of the format
                ``NAME VALUE'', that specify  file  name  information
                for  the  process'  DB  environment.   The whitespace
                delimiting the two parts of the entry may be  one  or
                more   <space>  or  <tab>  characters.   (Leading  or
                trailing <space> and <tab> characters are discarded.)
                Each  entry  must specify both the NAME and the VALUE
                of the pair.   All  entries  with  unrecognized  NAME
                values  will be ignored.  The db_config array must be
                NULL terminated.

           DB_CONFIG
                The  same  information  specified  to  the  db_config
                argument  to  db_appinit  may  be  specified  using a
                configuration 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_ENVIRON_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
           argument 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-
                memory  access  method  databases  will  be   created
                relative  to  this path.  Note, these temporary files
                can potentially be quite large, depending on the size
                of the database.

                If   DB_TMP_DIR   is  not  specified,  the  following
                environment   variables   are   checked   in   order:
                ``TMPDIR'', ``TEMP'', ``TMP'' and ``TempFolder''.  If
                one of them  is  set,  temporary  files  are  created
                relative to the directory it specifies.

                If  DB_TMP_DIR is not specified and none of the above
                environment variables are set, the first possible one
                of  the  following  directories  is  used:  /var/tmp,
                /usr/tmp, /temp, /tmp, C:/temp and C:/tmp.

           The following describes  the  specific  circumstances  and
           order  in  which  the  different  ways  of specifying file
           naming information are  applied.   Specifically,  DB  file
           name   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
                configuration 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
                permit  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
                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   argument   is  intended  to  permit
                applications  to  customize  file  location   for   a
                database.   For  example,  an  application writer can
                place  data  files  and  log   files   in   different
                directories,  or instantiate 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
                permit  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
                utilities to let users specify a database home.

           db_home
                If  the  application  specified  a  non-NULL  db_home
                argument to db_appinit (and the database home was not
                already  specified  using  the  DB_HOME   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.

           (nothing)
                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
           presumed to be relative to that directory, and  all  files
           created  by  the  DB  subsystems  will  be created in that
           directory.

           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_DIR datadir",
                      "DB_LOG_DIR 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_DIR /b/data2",
                      "DB_DATA_DIR data1",
                      NULL
                  };

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

           See  the  file  examples/ex_appinit.c  in  the  DB  source
           distribution for a C  language  code  example  of  how  an
           application  might  use  db_appinit  to  configure  its DB
           environment.

## ERRORS

           The db_appinit function may fail and return errno for  any
           of  the  errors specified for the following DB and library
           functions: DB->close(3), calloc(3), db_appexit(3),
           fclose(3), fcntl(2), fflush(3), fgets(3), fopen(3),
           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_RECOVER   or   DB_RECOVER_FATAL   flag   was
                specified, and no log files were found.

                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
           address space multiple times.  For this  reason,  each  DB
           environment may be opened only once by a process on HP-UX,
           i.e., calls to appinit  will  fail  if  the  specified  DB
           environment has been opened and not subsequently closed.

           On Windows/95, files that are opened by multiple processes
           do not share data correctly.  To tell Berkeley DB  to  use
           the  paging  file to share memory among processes, use the
           DB_REGION_NAME  flag   of   the   db_value_set   function.
           Obviously,  you  do  not  need to do this if only a single
           process will be accessing database files.

## 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_internal(3),
           db_lock(3), db_log(3), db_mpool(3), db_open(3), db_thread(3),
           db_txn(3)