db_internal




SYNOPSIS

       #include <db.h>

       int
       db_jump_set(void *func, int which);

       int
       db_value_set(int value, int which);


DESCRIPTION

       The DB library is a family of  groups  of  functions  that
       provides  a  modular programming interface to transactions
       and record-oriented file  access.   The  library  includes
       support  for  transactions, locking, logging and file page
       caching, as well as various indexed access methods.   Many
       of  the  functional  groups  (e.g.,  the file page caching
       functions)  are  useful  independent  of  the   other   DB
       functions,  although some functional groups are explicitly
       based on other functional groups (e.g.,  transactions  and
       logging).   For  a  general description of the DB package,
       see db_intro(3).

  db_jump_set
       The db_jump_set function enables applications  to  replace
       underlying  DB  library functionality by replacing entries
       in  a  function  call  jump  table.   The  which  argument
       specifies the entry to be replaced by the argument func.

       The following values of which are supported:

       DB_FUNC_CLOSE
            Replace  all  DB  calls  to the IEEE Std 1003.1b-1993
            (``POSIX'') standard close function with func,  which
            must conform to the standard interface.

       DB_FUNC_DIRFREE
            The  DB  library  requires  the ability to return any
            memory allocated as part of the routine  which  reads
            through  a directory and creates a list of files that
            that the directory  contains  (see  DB_FUNC_DIRLIST).
            The  func  argument  must  conform  to  the following
            interface:

                 int dirfree(char **namesp, int cnt);

            The namesp and cnt arguments are the same  values  as
            were returned by the DB_FUNC_DIRLIST function.

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

       DB_FUNC_DIRLIST
            The DB library requires the ability to read through a
            directory  and  create  a list of files that that the
            directory contains.  The func argument  must  conform
            to the following interface:

                 int dirlist(const char *dir,
                    char ***namesp, int *cntp);

            The  dir  argument is the name of the directory to be
            searched.  The function must return a pointer  to  an
            array  of  nul-terminated  file  names  in the memory
            location referenced by the  argument  namesp,  and  a
            count  of  the number of elements in the array in the
            memory location referenced by cntp.

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

       DB_FUNC_EXISTS
            The DB library requires the ability to determine if a
            file exists, and optionally, if it is a file of  type
            directory.   The  func  argument  must conform to the
            following interface:

                 int exists(const char *path, int *isdirp);

            The path argument is the pathname of the file  to  be
            checked.

            If the isdirp argument is non-NULL, it must be set to
            non-0 if path is a directory, and 0 if path is not  a
            directory.

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

       DB_FUNC_FREE
            Replace all  DB  calls  to  the  ANSI  C  X3.159-1989
            (``ANSI  C'') standard free function with func, which
            must conform to the standard interface.

       DB_FUNC_FSYNC
            Replace all DB calls to  the  IEEE  Std  1003.1b-1993
            (``POSIX'')  standard fsync function with func, which
            must conform to the standard interface.

       DB_FUNC_IOINFO
            The DB library requires the ability to determine  the
            size  and  I/O  characteristics  of a file.  The func
            argument must conform to the following interface:

                 int ioinfo(const char *path,
                    int fd, off_t *sizep, off_t *iop);

            The path argument is the pathname of the file  to  be
            checked,   and  the  fd  argument  is  an  open  file
            descriptor on the file.

            The ioinfo function must return the size of the  file
            in  the  memory  location  referenced  by  the  sizep
            argument, and the  appropriate  granularity  for  I/O
            operations   to  the  file  in  the  memory  location
            referenced by the iop argument.

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

       DB_FUNC_MALLOC
            Replace  all  DB  calls  to  the  ANSI  C X3.159-1989
            (``ANSI C'')  standard  malloc  function  with  func,
            which must conform to the standard interface.

       DB_FUNC_MAP
            The  DB  library  requires  the ability to map a file
            into memory.  The func argument must conform  to  the
            following interface:

                 int map(int fd, size_t len,
                    int is_private, int rdonly, void **addr);

            The  fd  argument  is  an open file descriptor on the
            file.  The map function must map the first len  bytes
            of  the  file into memory and return a pointer to the
            mapped location in the the memory location referenced
            by the argument addr.

            The  is_private argument will be non-zero if the file
            is private to the application,  otherwise,  the  file
            must  be  mapped into shared memory accessible to any
            number of processes.

            The is_rdonly argument will be non-zero if  the  file
            is considered read-only by the caller.

            Both private and public files may contain semaphores.

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

       DB_FUNC_OPEN
            Replace  all  DB  calls  to the IEEE Std 1003.1b-1993
            (``POSIX'') standard open function with  func,  which
            must conform to the standard interface.

       DB_FUNC_READ
            Replace  all  DB  calls  to the IEEE Std 1003.1b-1993
            (``POSIX'') standard read function with  func,  which
            must conform to the standard interface.

       DB_FUNC_REALLOC
            Replace  all  DB  calls  to  the  ANSI  C X3.159-1989
            (``ANSI C'') standard  realloc  function  with  func,
            which must conform to the standard interface.

       DB_FUNC_SEEK
            The DB library requires the ability to specify that a
            subsequent read or write to a file will occur from  a
            specific  location  in  that file.  The func argument
            must conform to the following interface:

                 int seek(int fd, size_t pgsize,
                    db_pgno_t pageno, u_long relative, int whence);

            The fd argument is an open  file  descriptor  on  the
            file.  The seek function must cause a subsequent read
            or write from the file to  occur  at  a  byte  offset
            specified by the calculation:

                 (pgsize * pageno) + relative

            The  whence  argument specifies where in the file the
            byte offset is  relative  to,  as  described  by  the
            Replace  all  DB  calls  to the IEEE Std 1003.1b-1993
            (``POSIX'') standard function with func,  which  must
            conform to the standard interface.
             for the lseek system call.

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

       DB_FUNC_SLEEP
            The DB  library  requires  the  ability  to  cause  a
            process  to  suspend  itself  for  a  period of time,
            relinquishing control of the processor to  any  other
            waiting  thread  of  control.  The func argument must
            conform to the following interface:

                 int sleep(u_long seconds, u_long microseconds);

            The seconds and microseconds  arguments  specify  the
            amount of time to wait until the suspending thread of
            control should run again.

            The seconds and microseconds  arguments  may  not  be
            normalized  when  the sleep function is called, i.e.,
            the  microseconds  argument  may  be   greater   than
            1000000.

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

       DB_FUNC_STRDUP
            Replace all  DB  calls  to  the  ANSI  C  X3.159-1989
            (``ANSI  C'')  standard  strdup  function  with func,
            which must conform to the standard interface.

       DB_FUNC_UNLINK
            Replace all DB calls to  the  IEEE  Std  1003.1b-1993
            (``POSIX'') standard unlink function with func, which
            must conform to the standard interface.

       DB_FUNC_UNMAP
            The DB library requires the ability to unmap  a  file
            from  memory.   The func argument must conform to the
            following interface:

                 int unmap(void *addr, size_t len);

            The addr argument is the  argument  returned  by  the
            DB_FUNC_MAP  function  when  the file was mapped into
            memory, and the len argument is the same as  the  len
            argument  specified  to the DB_FUNC_MAP function when
            the file was mapped into memory.

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

       DB_FUNC_WRITE
            Replace  all  DB  calls  to the IEEE Std 1003.1b-1993
            (``POSIX'') standard write function with func,  which
            must conform to the standard interface.

       DB_FUNC_YIELD
            The  DB  library  requires  the  ability to yield the
            processor from the current thread of control  to  any
            other  waiting threads of control.  The func argument
            must conform to the following interface:

                 int yield(void);

            The  yield  function  must  be  able  to  cause   the
            rescheduling  all  participants  in  the  current  DB
            environment, whether threaded  or  not.   It  may  be
            incorrect  to  supply a thread yield function if more
            than  a  single  process  is  operating  in  the   DB
            environment.    This  is  because  many  thread-yield
            functions will not allow other processes to run,  and
            the  contested  lock  may be held by another process,
            not by another thread.

            If no yield function is specified, or  if  the  yield
            function  returns an error, the function specified by
            the DB_FUNC_SLEEP  entry  will  be  used  instead  or
            subsequently,   i.e.,   if   no   yield  function  is
            specified, or it is possible for the  yield  function
            to  fail, the sleep function must cause the processor
            to reschedule any  waiting  threads  of  control  for
            execution.

            Solaris   architecture   note:  Because  of  bugs  in
            versions  of  Solaris  before  version  5.6,  the  DB
            library  uses  the  sema_wait(3T) call instead of the
            sema_trywait(3T) call.  For  this  reason,  replacing
            the yield function will have no effect on Solaris.

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

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

  db_value_set
       The  db_value_set function enables applications to specify
       underlying DB library functionality.  The  which  argument
       specifies the information being set by the argument value.

       The following values of which are supported:

       DB_TSL_SPINS
            Specify the  number  of  times  mutexes  should  spin
            without blocking.

            This  value  normally  defaults  to  1  (correct  for
            uniprocessor systems), but  on  multiprocessor  Win32
            systems   defaults   to   50   times  the  number  of
            processors.  Otherwise, the number of spins should be
            set  to  an  appropriate  value when applications are
            running on multiprocessor systems.

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


ERRORS

       The db_jump_set function may fail and return errno for the
       following conditions:

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


BUGS

       No type  checking  is  done  of  the  func  argument,  and
       specifying  an  invalid  replacement  routine  will  cause
       unpredictable results.


SEE ALSO

       db_archive(1), db_checkpoint(1), db_deadlock(1), db_dump(1),
       db_load(1), db_recover(1), db_stat(1), db_intro(3),
       db_appinit(3), db_cursor(3), db_dbm(3), db_internal(3),
       db_lock(3), db_log(3), db_mpool(3), db_open(3), db_thread(3),
       db_txn(3)


Man(1) output converted with man2html