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).
This manual page describes interfaces to tune or replace
underlying system functionality used by the DB library.
Few applications should have any need for these
interfaces.
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'') 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'') 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,
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 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 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 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 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.
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'') 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'') 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_RUNLINK
The 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 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 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 all 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 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 all 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 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.
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_MUTEXLOCKS
Grant all requested mutual exclusion mutexes without
testing for their availability. This flag should
never be used for any other purpose than debugging.
DB_REGION_ANON
Setting value to a non-zero value specifies that
shared memory regions are to be created in anonymous
memory, and not backed by a regular file.
DB_REGION_NAME differs from DB_REGION_ANON in that
the former will fail if the shared memory regions
cannot be named, that is, if multiple processes
cannot use them. See DB_FUNC_MAP for more
information.
DB_REGION_INIT
In some applications, the expense of page-faulting
the shared memory regions can affect performance,
e.g., when the page-fault occurs while holding a
lock, other lock requests can convoy and overall
throughput may decrease. Setting value to a non-zero
value specifies that one byte be read from each 4K
page of the shared memory region when the region is
initialized.
DB_REGION_NAME
Setting value to a non-zero value specifies that
shared memory regions are to be created in anonymous
memory, and not backed by a regular file.
DB_REGION_NAME differs from DB_REGION_ANON in that
the former will fail if the shared memory regions
cannot be named, that is, if multiple processes
cannot use them. See DB_FUNC_MAP for more
information.
DB_TSL_SPINS
Specify the number of times mutexes should spin
without blocking.
This value defaults to 1 on uniprocessor systems and
to 50 times the number of processors 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.
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.
On Windows/95, files that are opened by multiple processes
do not share data correctly. To tell 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 DB
files.
On Windows/NT, sharing of data between processes through
the paging file does not work correctly, so you should not
call db_value_set. That will allow DB to use the file
itself for sharing, which works correctly.
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