db_appinit



NAME

       db_appinit - initializing the DB environment


SYNOPSIS

       On Solaris, load with -lthread:
            cc [ flag ... ] file ...  -lthread [ library ... ]

       #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(3).   For a description of the access methods, see
       db_open(3).  For a description of  cursors  within  access
       methods,  see  db_cursor(3);  transactions, see db_txn(3);
       the lock manager, see db_lock(3);  the  log  manager,  see
       db_log(3);  the memory pool manager, see db_mpool(3).  For
       information on configuring the DB  transaction  processing
       environment,  and DB support utilities, see db_appinit(3),
       db_archive(1),   db_checkpoint(1),   db_deadlock(1)    and
       db_recover(1).   For  information on dumping and reloading
       DB databases, see db_dump(1) and db_load(1).

  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_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  or  writing  a  DB
            database,  so  that  they  do not interfere with each
            other.  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 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
            unless DB_INIT_TXN is also specified.

       DB_USE_ENVIRON
            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,  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 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  DB_ENV  used  by db_appinit are described
       below.  As references to the DB_ENV structure may be main-
       tained  by  db_appinit,  it  is  necessary that the DB_ENV
       structure and memory it references be  valid  until  after
       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 DB_ENV  fields  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 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.

            If  db_errpfx  is  non-NULL, the message will be pre-
            ceded 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.

       int (*db_yield)(void);
            The  DB library makes a system call to pause for some
            number of microseconds whenever it  is  necessary  to
            wait  on a lock.  This may not be optimal, especially
            in a thread-only environment where it  will  be  more
            efficient   to  explicitly  yield  the  processor  to
            another thread.  If db_yield  returns  0,  indicating
            success,  the  lock  will be re-tried, otherwise, the
            default descheduling function will be called and then
            the  lock  will  be  re-tried.   Note, it is probably
            incorrect to supply a  thread  db_yield  function  if
            more  than  a  single  process is operating in the DB
            environment.  This is because most thread-yield func-
            tions  will not allow other processes to run, and the
            lock may be held by another process, not  by  another
            thread.

            Solaris  architecture  note:  Because of bugs in ver-
            sions of Solaris before  version  5.6,  DB  uses  the
            sema_wait(3T)  call  instead  of the sema_trywait(3T)
            call.  For this reason, setting the db_yield field of
            the  DB_ENV structure will have no effect on Solaris.

       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-
       matically 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.

       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
            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 trail-
            ing  <space>  and  <tab>  characters  are discarded.)
            Each entry must specify both the NAME and  the  VALUE
            of the pair.  All entries with unrecognized NAME val-
            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'',
            ``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  nam-
       ing  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  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
            utilities to let users specify a database home.

       db_home
            If the application specified a non-NULL db_home argu-
            ment to db_appinit (and the  database  home  was  not
            already specified using the DB_HOME environment vari-
            able) its value is  prepended  to  the  current  file
            name.  If the resulting file name begins with a lead-
            ing slash, the file name is used without further mod-
            ification 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  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
              };

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

       See the file examples/ex_appinit.c in the DB  source  dis-
       tribution for a C language code example of how an applica-
       tion 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: getuid(2), db_appexit(3), fclose(3), fflush(3),
       fgets(3), fopen(3), getenv(3), lock_open(3),  log_open(3),
       malloc(3), memp_open(3), realloc(3), snprintf(3), stat(3),
       strcmp(3), strdup(3), strerror(3), strsep(3), txn_open(3),
       and vsnprintf(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.

            TMPDIR If the dbenv argument to _open was NULL or not
            initialized  using  db_appinit, the environment vari-
            able TMPDIR may be used as the directory in which  to
            create the , as described in the _open section above.

            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,  only  a
       single  DB  environment  may be maintained by a process on
       HP-UX, i.e., calls to db_appinit will fail if a previously
       created DB environment has not been closed.

       Because of bugs in versions of Solaris before version 5.6,
       setting the db_yield field of the  DB_ENV  structure  will
       have no effect on Solaris.


SEE ALSO

       db_archive(1), db_checkpoint(1), db_deadlock(1), db_dump(1),
       db_load(1), db_recover(1), db(3), db_appinit(3), db_cursor(3),
       db_dbm(3), db_lock(3), db_log(3), db_mpool(3), db_open(3),
       db_txn(3)