Berkeley DB: db_jump_set
Description: Berkeley DB: An embedded database programmatic toolkit.
Keywords: embedded,database,programmatic,toolkit,b+tree,btr ee,hash,hashing,transaction,transactions,locking,logging,access method,access me thods,java,C,C++

# db_jump_set

`

###

    #include <db.h>

    int
    db_jump_set(void *func, int which);

# Description

The db_jump_set function enables applications to replace underlying Berkeley 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.

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

The following values of which are supported:

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

DB_FUNC_DIRFREE
  The Berkeley 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 Berkeley 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 Berkeley 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 Berkeley 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 Berkeley DB calls to the IEEE Std 1003.1b-1993 (POSIX) fsync function with func, which must conform to the standard interface.

DB_FUNC_IOINFO
  The Berkeley 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,
          u_int32_t *mbytesp, u_int32_t *bytesp, u_int32_t *iosizep);

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

  If the mbytesp and bytesp arguments are non-NULL, the ioinfo function must return in them the size of the file: the number of megabytes in the file into the memory location referenced by the mbytesp argument, and the number of bytes over and above that number of megabytes into the memory location referenced by the bytesp argument.

  In addition, if the iosizep argument is non-NULL, the ioinfo function must return the optimum granularity for I/O operations to the file in the memory location referenced by it.

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

DB_FUNC_MALLOC
  Replace Berkeley 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 Berkeley DB library requires the ability to map a file into memory and to create shared memory regions (which may or may not be backed by files). The func argument must conform to the following interface:

      int map(char *path, int fd, size_t len,
          int is_region, int is_anonymous, int is_rdonly,
          void **addr);

  The path argument is the name of a file. The fd argument is an open file descriptor on that file.

  The is_region argument will be zero if the intention is to map a file into shared memory. In this case, the map function must map the first len bytes of the file into memory and return a pointer to the mapped location in the memory location referenced by the argument addr. In this case, the is_anonymous argument will always be zero. The is_rdonly argument will be non-zero if the file is considered read-only by the caller.

  The is_region argument will be non-zero if the memory is intended to be used as a shared memory region for synchronization between Berkeley DB threads/processes. In this case, the returned memory may be of any kind (e.g., anonymous), but must be able to support semaphores. If the application has previously specified that regions are to be instantiated in anonymous memory (see DB_REGION_ANON below), or the region is being joined and is believed to have been allocated in anonymous shared memory, the is_anonymous argument will be non-zero. Additionally, the path and fd arguments may be ignored (although future map calls using the same path must return the same memory), and the is_rdonly argument will always be zero.

  By default, on UNIX systems, the Berkeley DB library will use the IEEE Std 1003.1b-1993 (POSIX) mmap(2) interface to both map regular files into shared memory and create shared memory regions. If the application specifies that shared memory regions be instantiated in anonymous memory (see DB_REGION_ANON below), the shmget(2) shared memory segment interface will be used, where available, and the MAP_ANON or MAP_ANONYMOUS options to mmap(2) when shmget(2) is not available.

  When using shmget 2(), shared memory regions are named, and so multiple processes may share them. When using the mmap MAP_ANON or MAP_ANONYMOUS options, shared memory regions are not named, and so may only be accessed by a single process and its threads.

  HP/UX note:
    The shmget(2) interfaces are not used on HP/UX, even though they exist, as anonymous memory allocated using shmget(2) cannot be used to store semaphores.

  SunOS note:
    The shmget(2) interfaces are not used on SunOS, even though they apparently exist, as the distributed include files did not allow them to be compiled.

  Ultrix note:
    The mmap(2) interfaces are not used on Ultrix, even though they exist, as they do not work correctly.

  Windows/95 note:
    On Windows/95, files that are opened by multiple processes do not share data correctly. To cause Berkeley DB to use a named region of the paging file to share memory instead, use:

        db_value_set(1, DB_REGION_NAME);

    You do not need to do this if your application can guarantee that only one process will be accessing Berkeley DB files.

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

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

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

DB_FUNC_REALLOC
  Replace Berkeley 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_RUNLINK
  The Berkeley DB library requires the ability to remove shared memory regions from the system, whether or not they are backed by regular files. The func argument must conform to the following interface:

      int runlink(char *path);

  The path argument is the path argument specified to the DB_FUNC_MAP function when the region was mapped into memory.

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

DB_FUNC_SEEK
  The Berkeley DB library requires the ability to specify that a subsequent read from or write to a file will occur at 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_int32_t relative, int rewind, int whence);

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

      (pgsize * pageno) + relative

  If rewind is non-zero, the byte offset is treated as a backwards seek, not a forwards one.

  The whence argument specifies where in the file the byte offset is relative to, as described by the IEEE Std 1003.1b-1993 (POSIX) lseek system call.

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

DB_FUNC_SLEEP
  The Berkeley 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_UNLINK
  Replace Berkeley DB calls to the IEEE Std 1003.1b-1993 (POSIX) unlink function with func, which must conform to the standard interface.

DB_FUNC_UNMAP
  The Berkeley DB library requires the ability to unmap a file or shared memory region 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 or region 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 or region was mapped into memory.

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

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

DB_FUNC_YIELD
  The Berkeley 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 Berkeley 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 Berkeley 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 note:
    Because of bugs in the Solaris C library, the Berkeley DB library uses the undocumented _lock_try and _lock_clear function calls instead of either the sema_trywait(3T) or sema_wait(3T) function calls.

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

Applications should be careful to replace related functions as a group and at the same time. Replacing DB_FUNC_MALLOC without replacing DB_FUNC_REALLOC is likely to result in unpredictable results.

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

# Errors

If a fatal error occurs in Berkeley DB, the db_jump_set function may fail and return DB_RUNRECOVERY, at which point all subsequent database calls will also return DB_RUNRECOVERY.

EINVAL
  An invalid flag value or parameter was specified.

# See Also

db_value_set`