db_jump
NAME
db_jump_set - replace underlying DB functionality
SYNOPSIS
#include <db.h>
int
db_jump_set(void *func, 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 func-
tions, although some functional groups are explicitly
based on other functional groups (e.g., transactions and
logging). For a general description of the DB package,
see db_intro(3).
db_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 speci-
fies the entry to be replaced by the argument func.
The following values of which are supported:
DB_FUNC_CALLOC
Replace all DB calls to the ANSI C X3.159-1989
(``ANSI C'') standard calloc function with func,
which must conform to the standard interface.
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
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 descrip-
tor on the file.
The ioinfo function must return the size of the file
in the memory location referenced by the sizep argu-
ment, and the appropriate granularity for I/O opera-
tions to the file in the memory location referenced
by the iop argument.
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 fail-
ure 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:
DB_FUNC_SLEEP
The DB library requires the ability to cause a pro-
cess to suspend itself for a period of time, relin-
quishing control of the processor to any other wait-
ing thread of control. The func argument must con-
form 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
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 sub-
sequently, 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 ver-
sions of Solaris before version 5.6, the DB library
uses the sema_wait(3T) call instead of the sema_try-
wait(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.
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 speci-
fying an invalid replacement routine will cause unpre-
dictable 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_jump(3), db_lock(3),
db_log(3), db_mpool(3), db_open(3), db_thread(3), db_txn(3)