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


COMPILING

       On IRIX, if you are compiling a threaded application,  you
       must compile with the -D_SGI_MP_SOURCE flag:

            cc -D_SGI_MP_SOURCE ...

       On OSF/1, if you are compiling a threaded application, you
       must compile with the -D_REENTRANT flag:

            cc -D_REENTRANT ...

       On Solaris, if you are compiling a  threaded  application,
       you  must compile with the -D_REENTRANT flag and link with
       the -lthread library:

            cc -D_REENTRANT ... -lthread


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_intro(3), db_load(1), db_recover(1), db_stat(1),
       db_appinit(3), db_cursor(3), db_dbm(3), db_lock(3), db_log(3),
       db_mpool(3), db_open(3), db_txn(3)