db_open



NAME

       db_open - database access methods


SYNOPSIS

       #include <db.h>

       int
       db_open(const char *file, DBTYPE type,
            int flags, int mode, DB_ENV *dbenv, DB_INFO *dbinfo, DB **dbpp);

       int
       DB->close(DB *db, int flags);

       int
       DB->cursor(DB *db, DB_TXN *txnid, DBC **cursorp);

       int
       DB->del(DB *db, DB_TXN *txnid, DBT *key, int flags);

       int
       DB->fd(DB *db, int *fdp);

       int
       DB->get(DB *db, DB_TXN *txnid, DBT *key, DBT *data, int flags);

       int
       DB->put(DB *db, DB_TXN *txnid, DBT *key, DBT *data, int flags);

       int
       DB->sync(DB *db, int flags);

       int
       DB->stat(DB *db, void *sp, void *(*db_malloc)(size_t), int flags);


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

       This manual page describes the overall structure of the DB
       library access methods.

       The currently supported file formats are btree, hashed and
       recno.   The btree format is a representation of a sorted,
       balanced tree structure.  The hashed format is an extensi-
       ble,  dynamic  hashing  scheme.  The recno format supports

       The  db_open  function  copies a pointer to a DB structure
       (as typedef'd in the <db.h> include file), into the memory
       location  referenced  by  dbpp.  This structure includes a
       set of functions to perform various database  actions,  as
       described  below.   The db_open function returns the value
       of errno on failure and 0 on success.

       Note, while most of the access methods  use  file  as  the
       name  of  an  underlying file on disk, this is not guaran-
       teed.  Also, calling db_open  is  a  reasonably  expensive
       operation.  (This is based on a model where the DBMS keeps
       a set of files open for a long time  rather  than  opening
       and closing them on each query.)

       The  type  argument  is  of type DBTYPE (as defined in the
       <db.h> include file) and must be set to one  of  DB_BTREE,
       DB_HASH,  DB_RECNO  or DB_UNKNOWN.  If type is DB_UNKNOWN,
       the database must already  exist  and  db_open  will  then
       determine  if it is of type DB_BTREE, DB_HASH or DB_RECNO.

       The flags and mode arguments specify  how  files  will  be
       opened  and/or created when they don't already exist.  The
       flags value is specified by or'ing together one or more of
       the following values:

       DB_CREATE
            Create  any  underlying  files, as necessary.  If the
            files do not already exist and the DB_CREATE flag  is
            not specified, the call will fail.

       DB_NOMMAP
            Do  not  map  this  file (see db_mpool(3) for further
            information).

       DB_RDONLY
            Open the database for reading only.  Any  attempt  to
            write the database using the access methods will fail
            regardless of the actual permissions of any  underly-
            ing files.


       DB_THREAD
            Cause  the DB handle returned by the db_open function
            to be useable by multiple  threads  within  a  single
            address space, i.e., to be ``free-threaded''.

       DB_TRUNCATE
            ``Truncate''  the database if it exists, i.e., behave
            as if the database were just created, discarding  any
            previous contents.

       All  files  created by the access methods are created with
       mode mode (as described in chmod(2)) and modified  by  the
       patibility 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_open are
       described below.  As references to  the  DB_ENV  structure
       may  be  maintained  by  db_open, it is necessary that the
       DB_ENV structure and memory it references be  valid  until
       the  close function is called.  If dbenv is NULL or any of
       its fields are set to 0, defaults appropriate for the sys-
       tem are used where possible.

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

       DB_LOG *lg_info;
            If modifications to the file being opened  should  be
            logged,  the  lg_info  field  contains a return value
            from the function log_open.  If lg_info is  NULL,  no
            logging is done by the DB access methods.

       DB_LOCKTAB *lk_info;
            If  locking is required for the file being opened (as
            is the case when multiple processes  or  threads  are
            accessing  the same file), the lk_info field contains
            a return  value  from  the  function  lock_open.   If
            lk_info  is NULL, no locking is done by the DB access
            methods.

            If both locking and transactions are being  performed
            (i.e.,  both  lk_info  and tx_info are non-NULL), the
            transaction ID will be used as  the  locker  ID.   If
            only locking is being performed, db_open will acquire
            a locker ID from lock_id(3), and will use it for  all
            locks required for this instance of db_open.

       DB_MPOOL *mp_info;
            If  the  cache  for  the  file being opened should be
            maintained in a shared buffer pool, the mp_info field
            contains  a return value from the function memp_open.
            If mp_info is NULL, a memory pool may still  be  cre-
            ated by DB, but it will be private to the application
            and managed by DB.

       DB_TXNMGR *tx_info;
            If the accesses to the file being opened should  take
            place in the context of transactions (providing atom-
            icity and error recovery), the tx_info field contains
            a  return  value  from  the  function  txn_open  (see
            db_txn(3)).   If  transactions  are  specified,   the
            application  is responsible for making suitable calls


DB_INFO

       The  access  methods are configured using the DB_INFO data
       structure argument to db_open.  The DB_INFO  structure  is
       typedef'd in <db.h> and has a large number of fields, most
       specific to a single access method,  although  a  few  are
       shared.   The fields that are common to all access methods
       are listed here; those specific to  an  individual  access
       method  are  described below.  No reference to the DB_INFO
       structure is maintained by DB, so it is possible  to  dis-
       card it as soon as the db_open call returns.

       In  order  to ensure compatibility with future releases of
       DB, all fields of the DB_INFO structure should be initial-
       ized  to  0  before  the  structure  is  used.  Do this by
       declaring the structure external or static, or by  calling
       the C library function bzero(3) or memset(3).


       If  possible, defaults appropriate for the system are used
       for the DB_INFO fields if dbinfo is NULL or any fields  of
       the DB_INFO structure are set to 0.  The following DB_INFO
       fields may be initialized before calling db_open:

       size_t db_cachesize;
            A suggested maximum size of the memory pool cache, in
            bytes.   If db_cachesize is 0, an appropriate default
            is used.  If the mp_info  field  is  also  specified,
            this field is ignored.

            Note, the minimum number of pages in the cache should
            be no less than 10, and the access methods will  fail
            if  an  insufficiently  large cache is specified.  In
            addition, for applications that exhibit strong local-
            ity  in  their  data  access patterns, increasing the
            size of the cache can significantly improve  applica-
            tion performance.

       int db_lorder;
            The  byte  order  for integers in the stored database
            metadata.  The number should represent the  order  as
            an integer, for example, big endian order is the num-
            ber 4,321, and little  endian  order  is  the  number
            1,234.   If  db_lorder  is  0,  the host order of the
            machine where the DB library was compiled is used.

            The  value  of  db_lorder  is  ignored  except   when
            databases  are  being created.  If a database already
            exists, the byte order it uses is determined when the
            file is read.

            The  access  methods  provide no guarantees about the
            byte ordering of the application data stored  in  the
            database,  and applications are responsible for main-
            The flag DB_DBT_MALLOC, when  specified  in  the  DBT
            structure, will cause the DB library to allocate mem-
            ory which then  becomes  the  responsibility  of  the
            calling application.  See db_dbt(3) for more informa-
            tion.

            On systems where separate heaps  are  maintained  for
            applications  and  libraries  (notably  Windows  NT),
            specifying the DB_DBT_MALLOC flag will  fail  because
            the  DB library will allocate memory from a different
            heap than the application will use to  free  it.   To
            avoid this problem, the db_malloc field should be set
            to point to the application's allocation routine.  If
            db_malloc  is  non-NULL,  it will be used to allocate
            the memory returned when the  DB_DBT_MALLOC  flag  is
            set.   The  db_malloc function must match the calling
            conventions of the malloc(3) library routine.


BTREE

       The btree data structure is a sorted, balanced tree struc-
       ture  storing associated key/data pairs.  Searches, inser-
       tions, and deletions in the btree will all complete  in  O
       (lg  base  N) where base is the average number of keys per
       page.  Often, inserting ordered data into  btrees  results
       in pages that are half-full.  This implementation has been
       modified to make ordered (or  inverse  ordered)  insertion
       the best case, resulting in nearly perfect page space uti-
       lization.

       Space freed by deleting key/data pairs from  the  database
       is  never  reclaimed  from  the filesystem, although it is
       reused where possible.  This means that the btree  storage
       structure  is  grow-only.   If  sufficiently many keys are
       deleted from a tree that shrinking the underlying database
       file  is desirable, this can be accomplished by creating a
       new tree from a scan of the existing one.

       The following additional fields and flags may be  initial-
       ized in the DB_INFO structure before calling db_open, when
       using the btree access method:

       int (*bt_compare)(const DBT *, const DBT *);
            The bt_compare function is the key  comparison  func-
            tion.  It must return an integer less than, equal to,
            or greater than zero if the  first  key  argument  is
            considered to be respectively less than, equal to, or
            greater than the second key argument.  The same  com-
            parison  function  must be used on a given tree every
            time it is opened.  If bt_compare is NULL,  the  keys
            are  compared  lexically, with shorter keys collating
            before longer keys.

       int bt_minkey;
            The minimum number of keys that will be stored on any
            first  key  argument.  If the keys are equal, the key
            length should be returned.

            This is used to compress the keys stored on the btree
            internal  pages.   The  usefulness  of  this  is data
            dependent, but in some data sets can produce signifi-
            cantly  reduced  tree  sizes  and  search  times.  If
            bt_prefix is NULL,  and  no  comparison  function  is
            specified,  a  default lexical comparison function is
            used.  If bt_prefix is NULL and a comparison function
            is specified, no prefix comparison is done.

       unsigned long flags;
            The  following  additional  flags may be specified by
            or'ing together one or more of the following values:

            DB_DUP
                 Permit duplicate keys in the tree,  i.e.  inser-
                 tion  when  the  key  of the key/data pair being
                 inserted already exists in the tree will be suc-
                 cessful.  The ordering of duplicates in the tree
                 is determined by the order of insertion,  unless
                 the  ordering is otherwise specified by use of a
                 cursor (see db_cursor(3) for more  information.)
                 It  is  an  error  to  specify  both  DB_DUP and
                 DB_RECNUM.

            DB_RECNUM
                 Support retrieval from btrees using record  num-
                 bers.     For    more   information,   see   the
                 DB_SET_RECNO  flag  to  the   DB->get   function
                 (below),  and  the  cursor  c_get  function  (in
                 db_cursor(3)).

                 Logical record numbers in btrees are mutable  in
                 the  face  of record insertion or deletion.  See
                 the DB_RENUMBER flag in the RECNO section  below
                 for further discussion.

                 Maintaining  record counts within a btree intro-
                 duces a serious point of contention, namely  the
                 page  locations  where  the  record  counts  are
                 stored.  In addition, the entire  tree  must  be
                 locked  during  both  insertions  and deletions,
                 effectively single-threading the tree for  those
                 operations.   Specifying DB_RECNUM can result in
                 serious performance degradation for some  appli-
                 cations and data sets.


                 It  is  an  error  to  specify  both  DB_DUP and
                 DB_RECNUM.


HASH

            approximation  of the number of keys allowed to accu-
            mulate in any one bucket, determining when  the  hash
            table  grows  or  shrinks.   The  default value is 0,
            indicating that the  fill  factor  will  be  selected
            dynamically as pages are filled.

       u_int32_t (*h_hash)(const void *, u_int32_t);
            The  h_hash field is a user defined hash function; if
            h_hash is NULL, a  default  hash  function  is  used.
            Since  no  hash function performs equally well on all
            possible data, the user may find  that  the  built-in
            hash  function performs poorly with a particular data
            set.  User  specified  hash  functions  must  take  a
            pointer  to  a  byte string and a length as arguments
            and return a u_int32_t value.

            If a  hash  function  is  specified,  hash_open  will
            attempt  to  determine if the hash function specified
            is the same as the one with which  the  database  was
            created,  and will fail if it detects that it is not.

       unsigned int h_nelem;
            An estimate of the final size of the hash table.   If
            not  set  or  set  too  low,  hash tables will expand
            gracefully as keys are  entered,  although  a  slight
            performance  degradation may be noticed.  The default
            value is 1.

       unsigned long flags;
            The following additional flags may  be  specified  by
            or'ing together one or more of the following values:

            DB_DUP
                 Permit  duplicate  keys in the tree, i.e. inser-
                 tion when the key of  the  key/data  pair  being
                 inserted already exists in the tree will be suc-
                 cessful.  The ordering of duplicates in the tree
                 is  determined by the order of insertion, unless
                 the ordering is otherwise specified by use of  a
                 cursor  (see db_cursor(3) for more information.)


RECNO

       The recno access method provides  support  for  fixed  and
       variable  length records, optionally backed by a flat text
       (byte  stream)  file.   Both  fixed  and  variable  length
       records are accessed by their logical record number.

       It is valid to create a record whose record number is more
       than one greater than the last  record  currently  in  the
       database.   For  example, the creation of record number 8,
       when records 6 and 7 do not yet exist, is  not  an  error.
       However,  any  attempt  to  retrieve  such  records (e.g.,
       records 6 and 7) will return DB_KEYEMPTY.

            delimiting  byte  used to mark the end of a record in
            the source file.  If the re_source file is  specified
            and the DB_DELIMITER flag is not set, <newline> char-
            acters (i.e. ``\n'', 0x0a) are interpreted as end-of-
            record markers.

       u_int32_t re_len;
            The length of a fixed-length record.

       int re_pad;
            For  fixed length records, if the DB_PAD flag is set,
            the pad character for short records.  If  the  DB_PAD
            flag  is not set, <space> characters (i.e., 0x20) are
            used for padding.

       char *re_source;
            The purpose of the re_source field is to provide fast
            access  and  modification  to databases that are nor-
            mally stored as flat text files.

            If the re_source field is non-NULL, it  specifies  an
            underlying  flat  text  database file that is read to
            initialize a transient record number index.   In  the
            case of variable length records, the records are sep-
            arated by the  byte  value  re_delim.   For  example,
            standard UNIX byte stream files can be interpreted as
            a sequence of variable length  records  separated  by
            <newline> characters.

            In addition, when cached data would normally be writ-
            ten back to the underlying database file  (e.g.,  the
            close  or  sync  functions are called), the in-memory
            copy of the database will  be  written  back  to  the
            re_source file.

            By  default,  the backing source file is read lazily,
            i.e., records are not read from the file  until  they
            are  requested  by the application.  If multiple pro-
            cesses (not threads) are accessing a  recno  database
            concurrently   and   either   inserting  or  deleting
            records, the backing source file must be read in  its
            entirety  before  more than a single process accesses
            the database, and only that  process  should  specify
            the  backing source file as part of the db_open call.
            See the DB_SNAPSHOT flag below for more  information.

            Reading and writing the backing source file specified
            by  re_source  cannot  be  transactionally  protected
            because  it  involves  filesystem operations that are
            not part of the DB transaction methodology.  For this
            reason,  if  a temporary database is used to hold the
            records, i.e., a NULL was specified as the file argu-
            ment  to db_open, it is possible to lose the contents
            of the re_source file, e.g., if the system crashes at
            only  for DB applications, and that are either gener-
            ated on the fly by software tools, or modified  using
            a different mechanism, e.g., a text editor.

       unsigned long flags;
            The  following  additional  flags may be specified by
            or'ing together one or more of the following values:

            DB_DELIMITER
                 The re_delim field is set.

            DB_FIXEDLEN
                 The records are fixed-length,  not  byte  delim-
                 ited.   The  structure  element re_len specifies
                 the length of the record, and the structure ele-
                 ment re_pad is used as the pad character.

                 Any  records added to the database that are less
                 than re_len bytes long are automatically padded.
                 Any  attempt to insert records into the database
                 that are greater than  re_len  bytes  long  will
                 cause the call to fail immediately and return an
                 error.

            DB_PAD
                 The re_pad field is set.

            DB_RENUMBER
                 Specifying the DB_RENUMBER flag causes the logi-
                 cal  record numbers to be mutable, and change as
                 records  are  added  to  and  deleted  from  the
                 database.   For  example, the deletion of record
                 number 4 causes records numbered 5  and  greater
                 to be renumbered downward by 1.  If a cursor was
                 positioned to record number 4 before  the  dele-
                 tion, it will reference the new record number 4,
                 if any such record exists, after  the  deletion.
                 If a cursor was positioned after record number 4
                 before the deletion, it will be shifted downward
                 1  logical  record,  continuing to reference the
                 same record as it did before.

                 Using the c_put or put interfaces to create  new
                 records  will  cause  the  creation  of multiple
                 records if the record number is  more  than  one
                 greater than the largest record currently in the
                 database.  For example, creating record 28, when
                 record  25 was previously the last record in the
                 database, will create records 26 and 27 as  well
                 as  28.   Attempts to retrieve records that were
                 created in this manner will result in  an  error
                 return of DB_KEYEMPTY.

                 If  a  created  record  is not at the end of the
                 be largely  meaningless,  although  it  is  sup-
                 ported.
            DB_SNAPSHOT
                 This flag specifies that any specified re_source
                 file be read in its  entirety  when  db_open  is
                 called.   If  this  flag  is  not specified, the
                 re_source file may be read lazily.



DB OPERATIONS

       The DB structure returned by db_open describes a  database
       type,  and  includes a set of functions to perform various
       actions, as described  below.   Each  of  these  functions
       takes  a  pointer  to  a DB structure, and may take one or
       more DBT *'s and a flag value as well.  The fields of  the
       DB structure are as follows:

       DBTYPE type;
            The  type  of  the underlying access method (and file
            format).   Set  to  one  of  DB_BTREE,   DB_HASH   or
            DB_RECNO.   This  field  may be used to determine the
            type of the database after a return from db_open with
            the type argument set to DB_UNKNOWN.

       int (*close)(DB *db, int flags);
            A  pointer to a function to flush any cached informa-
            tion to disk, close any  open  cursors  (see  db_cur-
            sor(3)),  free any allocated resources, and close any
            underlying files.  Since key/data pairs are cached in
            memory,  failing  to  sync the file with the close or
            sync function may  result  in  inconsistent  or  lost
            information.

            The flags parameter must be set to 0 or the following
            value:

            DB_NOSYNC
                 Do not flush cached information to disk.

            The DB_NOSYNC flag is a dangerous option.  It  should
            only be set if the application is doing logging (with
            or without transactions)  so  that  the  database  is
            recoverable  after  a system or application crash, or
            if the database  is  always  generated  from  scratch
            after any system or application crash.

            It  is  important  to understand that flushing cached
            information to disk  only  minimizes  the  window  of
            opportunity  for  corrupted data.  While unlikely, it
            is possible for database corruption to  happen  if  a
            system or application crash occurs while writing data
            to the database.  To ensure that database  corruption
            never  occurs, applications must either: use transac-
            tions and logging with automatic recovery,  use  log-

       int (*cursor)(DB *db, DB_TXN *txnid, DBC **cursorp);
            A pointer to a function to create a cursor and copy a
            pointer  to it into the memory referenced by cursorp.

            A cursor is a structure used  to  provide  sequential
            access  through  a  database.  This interface and its
            associated functions replaces the functionality  pro-
            vided by the seq function in previous releases of the
            DB library.


            If the file is being accessed under transaction  pro-
            tection,  the  txnid  parameter  is  a transaction ID
            returned from txn_begin, otherwise, NULL.  If  trans-
            action  protection is enabled, cursors must be opened
            and closed within the context of a  transaction,  and
            the txnid parameter specifies the transaction context
            in which the cursor may be  used.   See  db_cursor(3)
            for more information.

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

       int (*del)(DB *db, DB_TXN *txnid, DBT *key, int flags);
            A pointer to a function to remove key/data pairs from
            the  database.  The key/data pair associated with the
            specified key is discarded from the database.  In the
            presence of duplicate key values, all records associ-
            ated with the designated key will be discarded.

            If the file is being accessed under transaction  pro-
            tection,  the  txnid  parameter  is  a transaction ID
            returned from txn_begin, otherwise, NULL.

            The flags parameter is currently unused, and must  be
            set to 0.

            The  del function returns the value of errno on fail-
            ure, 0 on success, and DB_NOTFOUND if  the  specified
            key did not exist in the file.

       int (*fd)(DB *db, int *fdp);
            A pointer to a function that copies a file descriptor
            representative of the underlying  database  into  the
            memory  referenced  by fdp.  A file descriptor refer-
            encing the same file will be  returned  to  all  pro-
            cesses that call db_open with the same file argument.
            This file descriptor may be safely used as  an  argu-
            ment  to the fcntl(2) and flock(2) locking functions.
            The file descriptor  is  not  necessarily  associated
            with  any  of the underlying files used by the access
            method.

            The fd function only supports a  coarse-grained  form

            In the presence of duplicate  key  values,  get  will
            return  the  first  data item for the designated key.
            Duplicates are sorted by insert  order  except  where
            this order has been overwritten by cursor operations.
            Retrieval of duplicates requires the  use  of  cursor
            operations.  See db_cursor(3) for details.

            If  the file is being accessed under transaction pro-
            tection, the txnid  parameter  is  a  transaction  ID
            returned from txn_begin, otherwise, NULL.

            The flags parameter must be set to 0 or the following
            value:

            DB_SET_RECNO
                 Retrieve the specified  numbered  key/data  pair
                 from  a database.  Upon return, both the key and
                 data items will have been filled  in,  not  just
                 the  data  item as is done for all other uses of
                 the get function.

                 The data field of the specified key  must  be  a
                 pointer  to  a  memory  location  from  which  a
                 db_recno_t  may  be  read,   as   described   in
                 db_dbt(3).  This memory location will be read to
                 determine the record to be retrieved.

                 For DB_SET_RECNO to be specified, the underlying
                 database  must be of type btree and it must have
                 been  created  with  the  DB_RECNUM  flag   (see
                 db_open(3)).

            If the database is a recno database and the requested
            key exists, but was never explicitly created  by  the
            application  or  was  later deleted, the get function
            returns DB_KEYEMPTY.  Otherwise, if the requested key
            isn't  in  the  database,  the  get  function returns
            DB_NOTFOUND.  Otherwise, the get function returns the
            value of errno on failure and 0 on success.

       int (*put)(DB *db, DB_TXN *txnid,
                 DBT *key, DBT *data, int flags);
            A  pointer  to  a function to store key/data pairs in
            the database.  If the database  supports  duplicates,
            the  put  function adds the new data value at the end
            of the duplicate set.

            If the file is being accessed under transaction  pro-
            tection,  the  txnid  parameter  is  a transaction ID
            returned from txn_begin, otherwise, NULL.

            The flags value is specified by or'ing  together  one
            or more of the following values:
            The default behavior of the put function is to  enter
            the  new  key/data  pair,  replacing  any  previously
            existing key if duplicates are disallowed, or to  add
            a duplicate entry if duplicates are allowed.  Even if
            the designated database allows duplicates, a call  to
            put with the DB_NOOVERWRITE flag set will fail if the
            key already exists in the database.

            The put function returns the value of errno on  fail-
            ure,  0 on success, and DB_KEYEXIST if the DB_NOOVER-
            WRITE flag was set and the key already exists in  the
            file.

       int (*sync)(DB *db, int flags);
            A  pointer to a function to flush any cached informa-
            tion to disk.  If the database is in memory only, the
            sync  function has no effect and will always succeed.

            The flags parameter is currently unused, and must  be
            set to 0.


            See  the  close function description above for a dis-
            cussion of DB and cached data.

            The sync function returns the value of errno on fail-
            ure and 0 on success.

       int (*stat)(DB *db, void *sp,
                 void *(*db_malloc)(size_t), int flags);
            A  pointer  to  a  function  to  create a statistical
            structure and copy a pointer to it  into  user-speci-
            fied  memory  locations.  Specifically, if sp is non-
            NULL, a pointer to the statistics  for  the  database
            are copied into the memory location it references.

            Statistical  structures are created in allocated mem-
            ory.  If db_malloc is non-NULL, it is called to allo-
            cate the memory, otherwise, the library function mal-
            loc(3) is used.  The function  db_malloc  must  match
            the calling conventions of the malloc(3) library rou-
            tine.  Regardless,  the  caller  is  responsible  for
            deallocating  the returned memory.  To deallocate the
            returned memory, free each returned  memory  pointer;
            pointers inside the memory do not need to be individ-
            ually freed.

            In the presence  of  multiple  threads  or  processes
            accessing  an  active database, the returned informa-
            tion may be out-of-date.

            This function may access all  of  the  pages  in  the
            database,  and  therefore  may incur a severe perfor-
            mance penalty and have obvious  negative  effects  on
                 database   without   incurring   a   performance
                 penalty.    It   is  only  available  for  recno
                 databases, or btree databases where the underly-
                 ing  database  was  created  with  the DB_RECNUM
                 flag.

            The stat function returns the value of errno on fail-
            ure and 0 on success.

            In  the  case  of  a  btree  or  recno  database, the
            statistics  are  stored  in  a  structure   of   type
            DB_BTREE_STAT  (typedef'd  in <db.h>).  The following
            fields will be filled in:

            u_int32_t bt_magic;
                 Magic number that identifies the file as a btree
                 file.
            u_int32_t bt_version;
                 The version of the btree file type.
            u_int32_t bt_flags;
                 Permanent   database  flags,  including  DB_DUP,
                 DB_FIXEDLEN, DB_RECNUM and DB_RENUMBER.
            u_int32_t bt_minkey;
                 The bt_minkey value specified to db_open(3),  if
                 any.
            u_int32_t bt_re_len;
                 The  re_len  value  specified  to db_open(3), if
                 any.
            u_int32_t bt_re_pad;
                 The re_pad value  specified  to  db_open(3),  if
                 any.
            u_int32_t bt_pagesize;
                 Underlying tree page size.
            u_int32_t bt_levels;
                 Number of levels in the tree.
            u_int32_t bt_nrecs;
                 Number  of  data  items in the tree (since there
                 may be multiple data items per key, this  number
                 may not be the same as the number of keys).
            u_int32_t bt_int_pg;
                 Number of tree internal pages.
            u_int32_t bt_leaf_pg;
                 Number of tree leaf pages.
            u_int32_t bt_dup_pg;
                 Number of tree duplicate pages.
            u_int32_t bt_over_pg;
                 Number of tree overflow pages.
            u_int32_t bt_free;
                 Number of pages on the free list.
            u_int32_t bt_freed;
                 Number of pages made available for reuse because
                 they were emptied.
            u_int32_t bt_int_pgfree;
                 Number of bytes free in tree internal pages.
                 Number of root page splits.
            u_int32_t bt_fastsplit;
                 Number  of  fast  splits.   When sorted keys are
                 added to the database, the DB btree  implementa-
                 tion  will  split  left or right to increase the
                 page-fill factor.  This number is a  measure  of
                 how  often it was possible to make such a split.
            u_int32_t bt_added;
                 Number of keys added.
            u_int32_t bt_deleted;
                 Number of keys deleted.
            u_int32_t bt_get;
                 Number of keys  retrieved.   (Note,  this  value
                 will  not  reflect  any  keys retrieved when the
                 database was open for read-only access, as there
                 is  no  permanent location to store the informa-
                 tion in this case.)
            u_int32_t bt_cache_hit;
                 Number of hits in tree fast-insert  code.   When
                 sorted  keys  are  added to the database, the DB
                 btree implementation will check  the  last  page
                 where  an  insert  occurred  before doing a full
                 lookup.  This number is a measure of  how  often
                 the lookup was successful.
            u_int32_t bt_cache_miss;
                 Number  of misses in tree fast-insert code.  See
                 the description of bt_cache_hit; this number  is
                 a measure of how often the lookup failed.


ENVIRONMENT VARIABLES

       The  following  environment variables affect the execution
       of db_open:

       DB_HOME
            If the dbenv  argument  to  db_open  was  initialized
            using  db_appinit,  the  environment variable DB_HOME
            may be used as the path of the database home for  the
            interpretation  of  the  dir  argument to db_open, as
            described in db_appinit(3).  Specifically, db_open is
            affected   by   the  configuration  string  value  of
            DB_DATA_DIR.


EXAMPLES

       Applications that create short-lived  databases  that  are
       discarded  or  recreated  when  the  system  fails and are
       unconcerned with concurrent access and loss of data due to
       catastrophic  failure,  may  wish to use the db_open func-
       tionality without other parts of  the  DB  library.   Such
       applications  will  only  be  concerned with the DB access
       methods.  The DB access methods will use the  memory  pool
       subsystem,  but the application is unlikely to be aware of
       this.    See    the    files    example/ex_access.c    and
       example/ex_btrec.c  in  the  DB  source distribution for C
       language code examples of how such applications might  use
       munmap(2), open(2), read(2), realloc(3), sigfillset(3),
       sigprocmask(2), stat(2), strcpy(3), strdup(3),
       strerror(3), strlen(3), time(3), and unlink(2).

       In addition, the db_open function may fail and return  er-
       rno for the following conditions:

       [EAGAIN]
            A lock was unavailable.

       [EINVAL]
            An  invalid  flag  value  or  parameter was specified
            (e.g., unknown database type, page size,  hash  func-
            tion,  recno pad byte, byte order) or a flag value or
            parameter that is incompatible with the current  file
            specification.

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

            There is a mismatch between  the  version  number  of
            file and the software.

            A  re_source  file  was  specified  with  either  the
            DB_THREAD flag or a non-NULL  tx_info  field  in  the
            DB_ENV argument to db_open.

       [ENOENT]
            A non-existent re_source file was specified.

       [EPERM]
            Database  corruption  was  detected.   All subsequent
            database calls (other  than  DB->close)  will  return
            EPERM.

       The  DB->close  function may fail and return errno for any
       of the errors specified for the following DB  and  library
       functions: DB->sync(3), calloc(3), close(2), fflush(3),
       lock_get(3), lock_put(3), lock_vec(3), log_put(3),
       log_unregister(3), malloc(3), memcpy(3), memmove(3),
       memp_close(3), memp_fclose(3), memp_fget(3), memp_fput(3),
       memp_fset(3), memp_fsync(3), memset(3), munmap(2),
       realloc(3), and strerror(3).

       The DB->cursor function may fail and return errno for  any
       of  the  errors specified for the following DB and library
       functions: calloc(3).

       In addition, the DB->cursor function may fail  and  return
       errno for the following conditions:

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


       In  addition, the DB->del function may fail and return er-
       rno for the following conditions:

       [EAGAIN]
            A lock was unavailable.

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

       [EPERM]
            Database corruption  was  detected.   All  subsequent
            database  calls  (other  than  DB->close) will return
            EPERM.

       In addition, the DB->fd function may fail and return errno
       for the following conditions:

       [ENOENT]
            The  DB->fd  function  was  called  for  an in-memory
            database, or no underlying file has yet been created.

       [EPERM]
            Database  corruption  was  detected.   All subsequent
            database calls (other  than  DB->close)  will  return
            EPERM.

       The  DB->get function may fail and return errno for any of
       the errors specified for  the  following  DB  and  library
       functions: DBcursor->c_get(3), calloc(3), fcntl(2),
       fflush(3), lock_get(3), lock_id(3), lock_put(3),
       lock_vec(3), log_put(3), malloc(3), memcmp(3), memcpy(3),
       memmove(3), memp_fget(3), memp_fput(3), memp_fset(3),
       memset(3), realloc(3), and strerror(3).

       In  addition, the DB->get function may fail and return er-
       rno for the following conditions:

       [EAGAIN]
            A lock was unavailable.

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

            The DB_THREAD flag was specified  to  the  db_open(3)
            function    and    neither   the   DB_DBT_MALLOC   or
            DB_DBT_USERMEM flags were set in the DBT.

            A record number of 0 was specified.

       [EPERM]
            Database corruption  was  detected.   All  subsequent
            database  calls  (other  than  DB->close) will return
            EPERM.

       [EACCES]
            An attempt was made to modify a read-only database.

       [EAGAIN]
            A lock was unavailable.

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

            A record number of 0 was specified.

            An attempt was made to add a record to a fixed-length
            database that was too large to fit.

            An attempt was made to do a partial put.

       [EPERM]
            Database corruption  was  detected.   All  subsequent
            database  calls  (other  than  DB->close) will return
            EPERM.

       [ENOSPC]
            A btree exceeded the maximum btree depth (255).

       The DB->stat function may fail and return errno for any of
       the  errors  specified  for  the  following DB and library
       functions: calloc(3), fcntl(2), fflush(3), lock_get(3),
       lock_id(3), lock_put(3), lock_vec(3), malloc(3),
       memcpy(3), memp_fget(3), memp_fput(3), and memset(3).

       The DB->sync function may fail and return errno for any of
       the  errors  specified  for  the  following DB and library
       functions: DB->get(3), DB->sync(3), calloc(3), close(2),
       fcntl(2), fflush(3), lock_get(3), lock_id(3), lock_put(3),
       lock_vec(3), log_put(3), malloc(3), memcpy(3), memmove(3),
       memp_fget(3), memp_fput(3), memp_fset(3), memp_fsync(3),
       memset(3), munmap(2), open(2), realloc(3), strerror(3),
       unlink(2), and write(2).

       In addition, the DB->sync function may fail and return er-
       rno for the following conditions:

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

       [EPERM]
            Database corruption  was  detected.   All  subsequent
            database  calls  (other  than  DB->close) will return
            EPERM.


SEE ALSO

       The Ubiquitous B-tree, Douglas Comer,  ACM  Comput.  Surv.
       11, 2 (June 1979), 121-138.

       Document  Processing  in  a  Relational  Database  System,
       Michael Stonebraker, Heidi Stettner,  Joseph  Kalash,  An-
       tonin Guttman, Nadene Lynn, Memorandum No. UCB/ERL M82/32,
       May 1982.
       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)