db_mpool



NAME

       db_mpool - shared memory buffer pool


SYNOPSIS

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

       #include <db.h>

       int
       memp_open(char *dir,
            int flags, int mode, DB_ENV *dbenv, DB_MPOOL **regionp);

       int
       memp_close(DB_MPOOL *mp);

       int
       memp_fopen(DB_MPOOL *mp, char *file, int ftype, int flags,
            int mode, size_t pagesize, int lsn_offset, DBT *pgcookie,
            DB_MPOOLFILE **mpf);

       int
       memp_fclose(DB_MPOOLFILE *mpf);

       int
       memp_fget(DB_MPOOLFILE *mpf,
            db_pgno_t *pgnoaddr, unsigned long flags, void **pagep);

       int
       memp_fput(DB_MPOOLFILE *mpf, void *pgaddr, unsigned long flags);

       int
       memp_fset(DB_MPOOLFILE *mpf, void *pgaddr, unsigned long flags);

       int
       memp_fsync(DB_MPOOLFILE *mpf);

       int
       memp_unlink(const char *dir, int force, DB_ENV *);

       int
       memp_register(DB_MPOOL *mp, int ftype,
            int (*pgin)(db_pgno_t pgno, void *pgaddr, DBT *pgcookie),
            int (*pgout)(db_pgno_t pgno, void *pgaddr, DBT *pgcookie));

       int
       memp_sync(DB_MPOOL *mp, LSN *lsn);

       int
       memp_stat(DB_MPOOL *mp, DB_MPOOL_STAT **gsp,
            DB_MPOOL_FSTAT *(*fsp)[], void *(*db_malloc)(size_t));


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

       This manual page describes the  specific  details  of  the
       memory pool interface.

       The  db_mpool functions are the library interface intended
       to provide general-purpose, page-oriented  buffer  manage-
       ment  of  one  or more files.  While designed to work with
       the other DB functions, these functions  are  also  useful
       for  more general purposes.  The memory pools (DB_MPOOL's)
       are referred to in  this  document  as  simply  ``pools''.
       Pools  may be shared between processes.  Pools are usually
       filled by pages from one or more  files  (DB_MPOOLFILE's).
       Pages  in  the  pool  are replaced in LRU (least-recently-
       used) order, with each new page replacing  the  page  that
       has  been  unused  the  longest.  Pages retrieved from the
       pool using  memp_fget  are  ``pinned''  in  the  pool,  by
       default,  until  they  are  returned to the pool's control
       using the memp_fput function.

  mpool_open
       The mpool_open function copies a pointer,  to  the  memory
       pool  identified  by  the  directory  dir, into the memory
       location referenced by regionp.

       If the dbenv argument to mpool_open was initialized  using
       db_appinit,   dir   is   interpreted   as   described   by
       db_appinit(3).

       Otherwise, if dir is not NULL, it is interpreted  relative
       to  the  current working directory of the process.  If dir
       is NULL, the following environment variables  are  checked
       in  order:  ``TMPDIR'',  ``TEMP'', and ``TMP''.  If one of
       them is set, memory pool files are created relative to the
       directory  it  specifies.   If  none  of them are set, the
       first possible one of the following directories  is  used:
       /var/tmp, /usr/tmp, /temp, /tmp, C:/temp and C:/tmp.

       All  files  associated with the memory pool are created in
       this directory.  This directory must  already  exist  when
       mpool_open  is called.  If the memory pool already exists,
       the process must have permission to  read  and  write  the
       existing  files.   If  the  memory  pool  does not already
       exist, it is optionally created and initialized.

       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_MPOOL_PRIVATE
            Create  a  private  MPOOL that is not shared with any
            other process or thread.

       DB_NOMMAP
            Always copy files in this memory pool into the  local
            cache  instead  of  mapping  them into process memory
            (see the description of the mp_mmapsize field of  the
            DB_ENV structure for further information).

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

       All files created by the memory pool subsystem (other than
       files  created by the memp_fopen function, which are sepa-
       rately specified) are created with mode mode (as described
       in  chmod(2))  and modified by the process' umask value at
       the time of creation (see umask(2)).  The group  ownership
       of  created  files  is  based  on the system and directory
       defaults, and is not further specified by DB.

       The memory pool subsystem is configured based on the dbenv
       argument  to  memp_open, 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  memp_open  are  described
       below.  As references to the DB_ENV structure may be main-
       tained by memp_open,  it  is  necessary  that  the  DB_ENV
       structure  and  memory  it references be valid until after
       the memp_closed function is called.  If dbenv is  NULL  or
       any  of  its fields are set to 0, defaults appropriate for
       the system are used where possible.

       The following DB_ENV  fields  may  be  initialized  before
       calling memp_open:

       void *(*db_errcall)(char *db_errpfx, char *buffer);
       FILE *db_errfile;
       const char *db_errpfx;
       int db_verbose;
            The  error  fields  of the DB_ENV structure behave as
            described for db_appinit(3).

       int (*db_yield)(void);
            The db_yield field of the DB_ENV structure behaves as
            described for db_appinit(3).

       size_t mp_mmapsize;
            Files that are opened read-only in the pool (and that
            satisfy a few other criteria) are, by default, mapped
            into  the  process  address  space  instead  of being
            copied into the local cache.  This can result in bet-
            ter-than-usual performance, as available virtual mem-
            ory is normally much larger than the local cache, and
            page faults are faster than page copying on many sys-
            tems.  However, in the presence  of  limited  virtual
            memory  it  can cause resource starvation, and in the
            presence of large databases, it can result in immense
            process sizes.  If mp_mmapsize is non-zero, it speci-
            fies the maximum file size for a file  to  be  mapped
            into  the  process  address space.  By default, it is
            set to 10Mb.

       size_t mp_size;
            The suggested size  of  the  pool,  in  bytes.   This
            should  be the size of the normal working data set of
            the application, with some small amount of additional
            memory  for  unusual  situations.  (Note, the working
            set is not the same as the number  of  simultaneously
            referenced  pages, and should be quite a bit larger!)
            The default cache size is  128K  bytes  (16  8K  byte
            pages), and may not be less than 20K bytes.

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

  memp_close
       The memp_close function closes the pool indicated  by  the
       DB_MPOOL  pointer  mp,  as  returned  by  memp_open.  This
       function does not  imply  a  call  to  memp_fsync  (or  to
       memp_fclose)  i.e. no pages are written to the source file
       as as a result of calling memp_close.

       In addition, if the dir argument to memp_open was NULL and
       dbenv was not initialized using db_appinit, all files cre-
       ated for  this  shared  region  will  be  removed,  as  if
       memp_unlink were called.

       When  multiple  threads are using the DB_MPOOL handle con-
       currently, only a single thread may  call  the  memp_close
       function.

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

  memp_fopen
       The memp_fopen function opens a file in the pool specified
       by the DB_MPOOL argument, copying the DB_MPOOLFILE pointer
       into the memory location referenced by mpf.

       The file argument is the name of the file  to  be  opened.
       If  file is NULL, a private file is created that cannot be
       shared with any other process or thread.

       The ftype argument should be the same as a ftype  argument
       previously specified to the memp_register function, unless
       no input or output processing of the file's pages are nec-
       essary,  in  which case it should be 0.  (See the descrip-
       tion of the memp_register function for more  information.)

       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
            Always copy this file into the local cache instead of
            mapping  it  into process memory (see the description
            of the mp_mmapsize field of the DB_ENV structure  for
            further information).

       DB_RDONLY
            Open  any  underlying  files  for  reading only.  Any
            attempt to write the file using  the  pool  functions
            will  fail,  regardless  of the actual permissions of
            the file.

       All files created by the function memp_fopen  are  created
       with  mode mode (as described in chmod(2)) and modified by
       the process' umask value at  the  time  of  creation  (see
       umask(2)).   The group ownership of created files is based
       on the system and directory defaults, and is  not  further
       specified by DB.

       The  pagesize  argument is the size, in bytes, of the unit
       of transfer between the application and the pool, although
       it  is  not  necessarily  the unit of transfer between the
       pool and the source file.

       The lsn_offset argument is the zero-based byte  offset  in
       the page of the page's log sequence number (LSN), or -1 if
       no LSN offset is specified.  (See the description  of  the
       memp_sync function for more information.)

       The  pgcookie  argument  contains  the byte string that is
       passed to the pgin and pgout functions for this  file,  if
       any.   (See  the description of the memp_register function
       for more information.)

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

  memp_fclose
       The  memp_fclose function closes the source file indicated
       by the DB_MPOOLFILE pointer mpf.  This function  does  not
       imply  a  call to memp_fsync, i.e. no pages are written to
       the source file as as a result of calling memp_fclose.

       In addition, if the file argument to memp_fopen was  NULL,
       any underlying files created for this DB_MPOOLFILE will be
       removed.

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

  memp_fget
       The  memp_fget  function copies a pointer to the page with
       the page number specified by  pgnoaddr,  from  the  source
       file  specified  by the DB_MPOOLFILE pointer mpf, into the
       memory location referenced by pagep.  If the page does not
       exist or cannot be retrieved, memp_fget will fail.

       The returned page is size_t type aligned.

       Page  numbers begin at 0, e.g., the first page in the file
       is page number 0, not page number 1.

       The flags argument is specified by or'ing together one  or
       more of the following values:

       DB_MPOOL_CREATE
            If  the specified page does not exist, create it.  In
            this  case,  the  pgin  function,  if  specified,  is
            called.

       DB_MPOOL_LAST
            Return  the last page of the source file and copy its
            page number to the location referenced by pgnoaddr.

       DB_MPOOL_NEW
            Create a new page in the file and copy its page  num-
            ber  to the location referenced by pgnoaddr.  In this
            case, the pgin function, if specified, is not called.

       The  DB_MPOOL_CREATE, DB_MPOOL_LAST and DB_MPOOL_NEW flags
       are mutually exclusive.

       Created pages have all their bytes set to 0.

       All pages returned by memp_fget  will  be  retained  (i.e.
       ``pinned'')  in  the  pool  until  a  subsequent  call  to
       memp_fput.

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

  memp_fput
       The  memp_fput function indicates that the page referenced
       by pgaddr can be evicted from the pool.  Pgaddr must be an
       address previously returned by memp_fget.

       The  flags argument is specified by or'ing together one or
       more of the following values:

       DB_MPOOL_CLEAN
            Clear any  previously  set  modification  information
            (i.e.,  don't  bother  writing  the  page back to the
            source file).

       DB_MPOOL_DIRTY
            The page has been modified and must be written to the
            source file before being evicted from the pool.

       DB_MPOOL_DISCARD
            The page is unlikely to be useful in the near future,
            and should be discarded before  other  pages  in  the
            pool.

       The  DB_MPOOL_CLEAN  and DB_MPOOL_DIRTY flags are mutually
       exclusive.

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

  memp_fset
       The  memp_fset function sets the flags associated with the
       page referenced by pgaddr without unpinning  it  from  the
       pool.   Pgaddr  must  be an address previously returned by
       memp_fget.  The flags argument to memp_fset  is  specified
       by  or'ing together one or more of the values specified as
       flags for the memp_fput call.

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

  memp_fsync
       The  memp_fsync  function writes all pages associated with
       the DB_MPOOLFILE pointer mpf, that were marked as modified
       using memp_fput or memp_fset, back to the source file.  If
       any of the modified pages are also pinned (i.e., currently
       referenced  by  this  or  another process) memp_fsync will
       ignore them.

       The memp_fsync function returns  the  value  of  errno  on
       failure,  0  on  success,  and DB_INCOMPLETE if there were
       pages which were modified but which memp_fsync was  unable
       to write.

  mpool_unlink
       The mpool_unlink function destroys the memory pool identi-
       fied by the directory dir,  removing  all  files  used  to
       implement  the  memory  pool.   (The  directory dir is not
       removed.)   If  there  are  processes  that  have   called
       mpool_open  without  calling  mpool_close (i.e., there are
       processes currently using the memory  pool),  mpool_unlink
       will fail without further action, unless the force flag is
       set, in which case mpool_unlink will attempt to remove the
       memory  pool files regardless of any processes still using
       the memory pool.

       The result of attempting to forcibly  destroy  the  region
       when  a  process has the region open is unspecified.  Pro-
       cesses using a shared memory region maintain an open  file
       descriptor  for  it.   On UNIX systems, the region removal
       should succeed and processes that have already joined  the
       region  should  continue  to  run  in  the  region without
       change, however processes attempting to  join  the  memory
       pool  will  either fail or attempt to create a new region.
       On other systems, e.g., WNT, where  the  unlink(2)  system
       call  will fail if any process has an open file descriptor
       for the file, the region removal will fail.

       In the case of catastrophic or  system  failure,  database
       recovery  must  be  performed  (see  db_recovery(1) or the
       DB_RECOVER flags  to  db_appinit(3)).   Alternatively,  if
       recovery  is  not  required  because  no database state is
       maintained across failures, it is possible to clean  up  a
       memory  pool by removing all of the files in the directory
       specified to the mpool_open function, as memory pool files
       are  never  created  in  any  directory other than the one
       specified to mpool_open.  Note, however, that this has the
       potential  to remove files created by the other DB subsys-
       tems in this database environment.

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

  memp_register
       The  memp_register function registers page-in and page-out
       functions for files of type ftype in the specified pool.

       If the pgin function is non-NULL, it is called each time a
       page  is  read  into  the  memory pool from a file of type
       ftype, or a page is created for a file of type ftype  (see
       the  DB_MPOOL_CREATE flag for the memp_fget function).  If
       the pgout function is non-NULL, it is called each  time  a
       page is written to a file of type ftype.

       Both the pgin and pgout functions are called with the page
       number, a pointer to the page being read or  written,  and
       any argument pgcookie that was specified to the memp_fopen
       function when the file was opened.   The  pgin  and  pgout
       functions  should  return  0 on success, and an applicable
       non-zero  errno  value  on  failure,  in  which  case  the
       db_mpool  function  calling  it  will also fail, returning
       that errno value.

       The purpose of the memp_register function  is  to  support
       processing  when  pages are entered into, or flushed from,
       the pool.  A file type must be specified to make it possi-
       ble for unrelated threads or processes, that are sharing a
       pool, to evict each other's pages from the pool.  Applica-
       tions  should  call  memp_register, during initialization,
       for each type of file requiring input or output processing
       that will be sharing the underlying pool.  (No registry is
       necessary for the standard  access  method  types,  btree,
       hash  and recno, as db_open(3) registers them separately.)

       If a thread or process does not call memp_register  for  a
       file  type, it is impossible for it to evict pages for any
       file requiring input or output processing from  the  pool.
       For  this reason, memp_register should always be called by
       each application sharing a pool  for  each  type  of  file
       included  in  the  pool,  regardless of whether or not the
       application itself uses files of that type.

       There are no standard values for ftype,  pgin,  pgout  and
       pgcookie, except that the ftype value for a file must be a
       non-zero positive number, as negative numbers are reserved
       for  internal use by db(3).  For this reason, applications
       sharing a pool must coordinate their values amongst  them-
       selves.

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

  memp_sync
       The memp_sync function ensures that all the modified pages
       in the pool with log sequence numbers (LSNs) less than the
       lsn argument are written to disk.

       The memp_sync function returns the value of errno on fail-
       ure,  0  on success, and DB_INCOMPLETE if there were pages
       which need to be written but which memp_sync was unable to
       write immediately.  In addition, if memp_sync returns suc-
       cess, the value  of  lsn  will  be  overwritten  with  the
       largest  LSN  from any page which was written by memp_sync
       to satisfy this request.

       The purpose of the  memp_sync  function  is  to  enable  a
       transaction  manager  to  ensure, as part of a checkpoint,
       that all pages modified by a certain time have been  writ-
       ten  to  disk.   Pages in the pool which cannot be written
       back to disk immediately (e.g., are currently pinned)  are
       written  to  disk as soon as it is possible to do so.  The
       expected behavior of the transaction manager  is  to  call
       the  memp_sync  function and then, if the return indicates
       that some pages could not be written immediately, to  wait
       briefly  and  retry  again  with  the  same  LSN until the
       memp_sync function returns that all pages have been  writ-
       ten.

       To  support  the  memp_sync functionality, it is necessary
       that the pool functions know the location of  the  LSN  on
       the  page  for  each  file  type.  This location should be
       specified when the file is  opened  using  the  memp_fopen
       function.   (Note,  it  is  not  required  that the LSN be
       aligned on the page in any way.)

  memp_stat
       The memp_stat function creates statistical structures  and
       copies  pointers  to them into user-specified memory loca-
       tions.  The statistics include the number of files partic-
       ipating  in  the  pool,  the active pages in the pool, and
       information as to how effective the cache has been.

       Statistical structures are created  in  allocated  memory.
       If  db_malloc  is  non-NULL,  it is called to allocate the
       memory, otherwise, the library function malloc(3) is used.
       The  function db_malloc must match the calling conventions
       of the malloc(3) library routine.  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
       individually freed.

       If gsp is non-NULL, the global statistics for  the  memory
       pool mp are copied into the memory location it references.
       The global statistics are stored in a  structure  of  type
       DB_MPOOL_STAT (typedef'd in <db.h>).

       The following DB_MPOOL_STAT fields will be filled in:

       size_t st_cachesize;
            Cache size in bytes.
       unsigned long st_cache_hit;
            Requested pages found in the cache.
       unsigned long st_cache_miss;
            Requested pages not found in the cache.
       unsigned long st_map;
            Requested  pages  mapped  into  the  process' address
            space  (there  is  no  available  information  as  to
            whether or not this request caused disk I/O, although
            examining the application  page  fault  rate  may  be
            helpful).
       unsigned long st_page_create;
            Pages created in the cache.
       unsigned long st_page_in;
            Pages read into the cache.
       unsigned long st_page_out;
            Pages written from the cache to the backing file.
       unsigned long st_ro_evict;
            Read-only pages forced from the cache.
       unsigned long st_rw_evict;
            Read-write pages forced from the cache.
       unsigned long st_hash_buckets;
            Number of hash buckets in buffer hash table.
       unsigned long st_hash_searches;
            Total number of buffer hash table lookups.
       unsigned long st_hash_longest;
            The  longest  chain  ever  encountered in buffer hash
            table lookups.
       unsigned long st_hash_examined;
            Total number of hash elements traversed  during  hash
            table lookups.

       If  fsp  is non-NULL, a pointer to a NULL-terminated vari-
       able length array of statistics for individual  files,  in
       the  memory pool mp, is copied into the memory location it
       references.  If no individual files currently exist in the
       memory pool, fsp will be set to NULL.

       The  per-file  statistics are stored in structures of type
       DB_MPOOL_FSTAT  (typedef'd  in  <db.h>).   The   following
       DB_MPOOL_FSTAT  fields  will be filled in for each file in
       the pool, i.e., each element of the array:

       char *file_name;
            The name of the file.
       size_t st_pagesize;
            Page size in bytes.

       unsigned long st_cache_hit;
            Requested pages found in the cache.
       unsigned long st_cache_miss;
            Requested pages not found in the cache.
       unsigned long st_map;
            Requested pages  mapped  into  the  process'  address
            space.
       unsigned long st_page_create;
            Pages created in the cache.
       unsigned long st_page_in;
            Pages read into the cache.
       unsigned long st_page_out;
            Pages written from the cache to the backing file.

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


ENVIRONMENT VARIABLES

       The following environment variables affect  the  execution
       of db_mpool:

       DB_HOME
            If  the  dbenv  argument to memp_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  memp_open,  as
            described in db_appinit(3).

       TMPDIR
            If  the  dbenv argument to mpool_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  memory  pool,  as   described   in   the
            mpool_open section above.


ERRORS

       The  memp_open  function may fail and return errno for any
       of the errors specified for the following DB  and  library
       functions:   close(2),   fcntl(2),   fstat(2),  getpid(2),
       lseek(2),   mmap(2),   munmap(2),   open(2),    unlink(2),
       write(2),  abort(3),  db_version(3), fflush(3), getenv(3),
       isdigit(3),     llseek(3),      malloc(3),      memcpy(3),
       memp_unlink(3),  memset(3), sigfillset(3), sigprocmask(3),
       stat(3), strcpy(3), strdup(3), strerror(3), strlen(3)  and
       vsnprintf(3).

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

       [EAGAIN]
            The shared memory region was locked and  (repeatedly)
            unavailable.


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

            A   NULL   pathname   was   specified   without   the
            DB_MPOOL_PRIVATE flag.

            The specified cache size was impossibly small.

       The memp_close function may fail and return errno for  any
       of  the  errors specified for the following DB and library
       functions:  close(2),  fcntl(2),   getpid(2),   munmap(2),
       fflush(3), memp_fclose(3), strerror(3) and vsnprintf(3).

       The  memp_fopen function may fail and return errno for any
       of the errors specified for the following DB  and  library
       functions:  close(2),  fcntl(2),  fstat(2), fsync(2), get-
       pid(2), lseek(2), mmap(2), open(2),  unlink(2),  write(2),
       abort(3),  fflush(3),  getenv(3),  isdigit(3),  llseek(3),
       log_compare(3), log_flush(3), malloc(3),  memcmp(3),  mem-
       cpy(3), memset(3), sigfillset(3), sigprocmask(3), stat(3),
       strcpy(3),   strdup(3),   strerror(3),    strlen(3)    and
       vsnprintf(3).


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

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

            The file has already been entered into the pool,  and
            the  pagesize  value is not the same as when the file
            was entered into the pool, or the length of the  file
            is not zero or a multiple of the pagesize.

            The  DB_RDONLY  flag  was  specified for an in-memory
            pool.

       The memp_fclose function may fail and return errno for any
       of  the  errors specified for the following DB and library
       functions:  close(2),  fcntl(2),   getpid(2),   munmap(2),
       fflush(3), strerror(3) and vsnprintf(3).

       The  memp_fget  function may fail and return errno for any
       of the errors specified for the following DB  and  library
       functions:  close(2),  fcntl(2),  fstat(2), fsync(2), get-
       pid(2), lseek(2), mmap(2),  open(2),  read(2),  unlink(2),
       write(2),   abort(3),  fflush(3),  getenv(3),  isdigit(3),
       llseek(3),   log_compare(3),   log_flush(3),    malloc(3),
       memcmp(3),   memcpy(3),   memp_fput(3),   memset(3),  sig-
       fillset(3), sigprocmask(3), stat(3), strcpy(3), strdup(3),
       strerror(3), strlen(3) and vsnprintf(3).


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

       [EAGAIN]
            The  page  reference  count  has  overflowed.   (This
            should  never  happen  unless  there's  a  bug in the
            application.)

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

            The DB_MPOOL_NEW flag was set and the source file was
            not opened for writing.

            The requested page does not exist and DB_MPOOL_CREATE
            was not set.

            More than one of DB_MPOOL_CREATE,  DB_MPOOL_LAST  and
            DB_MPOOL_NEW was set.

       [ENOMEM]
            The  cache  is full and no more pages will fit in the
            pool.

       The memp_fput function may fail and return errno  for  any
       of  the  errors specified for the following DB and library
       functions: close(2), fcntl(2),  fstat(2),  fsync(2),  get-
       pid(2),  lseek(2),  mmap(2), open(2), unlink(2), write(2),
       abort(3),  fflush(3),  getenv(3),  isdigit(3),  llseek(3),
       log_compare(3),  log_flush(3),  malloc(3), memcmp(3), mem-
       cpy(3), memset(3), sigfillset(3), sigprocmask(3), stat(3),
       strcpy(3),    strdup(3),    strerror(3),   strlen(3)   and
       vsnprintf(3).


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

       [EACCES]
            The  DB_MPOOL_DIRTY  flag was set and the source file
            was not opened for writing.

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

            The  pgaddr  parameter  does  not  reference  a  page
            returned by memp_fget.

            More  than  one  of DB_MPOOL_CLEAN and DB_MPOOL_DIRTY
            was set.

       The memp_fset function may fail and return errno  for  any
       of  the  errors specified for the following DB and library
       functions:    fcntl(2),    getpid(2),    fflush(3)     and
       vsnprintf(3).


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

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

       The memp_fsync function may fail and return errno for  any
       of  the  errors specified for the following DB and library
       functions:  fcntl(2),   fsync(2),   getpid(2),   lseek(2),
       write(2),     fflush(3),     llseek(3),    log_compare(3),
       log_flush(3), memcpy(3) and vsnprintf(3).

       The memp_unlink function may fail and return errno for any
       of  the  errors specified for the following DB and library
       functions:  close(2),   fcntl(2),   fstat(2),   getpid(2),
       mmap(2),    munmap(2),   open(2),   unlink(2),   abort(3),
       fflush(3), getenv(3),  isdigit(3),  malloc(3),  memcpy(3),
       memset(3),  sigfillset(3),  sigprocmask(3),  stat(3), str-
       cpy(3),    strdup(3),    strerror(3),    strlen(3)     and
       vsnprintf(3).


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

       [EBUSY]
            The shared memory region was in  use  and  the  force
            flag was not set.

       The  memp_register  function may fail and return errno for
       any of the errors  specified  for  the  following  DB  and
       library functions: malloc(3).

       The  memp_sync  function may fail and return errno for any
       of the errors specified for the following DB  and  library
       functions:  close(2),  fcntl(2),  fstat(2), fsync(2), get-
       pid(2), lseek(2), mmap(2), open(2),  unlink(2),  write(2),
       abort(3),  fflush(3),  getenv(3),  isdigit(3),  llseek(3),
       log_compare(3), log_flush(3), malloc(3),  memcmp(3),  mem-
       cpy(3), memset(3), sigfillset(3), sigprocmask(3), stat(3),
       strcpy(3),   strdup(3),   strerror(3),    strlen(3)    and
       vsnprintf(3).


       In  addition,  the  memp_sync function may fail and return
       errno for the following conditions:  [EINVAL]  An  invalid
       flag value or parameter was specified.

       The  memp_sync  function was called without logging having
       been initialized in the environment.

       The memp_stat function may fail and return errno  for  any
       of  the  errors specified for the following DB and library
       functions: malloc(3).


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)