2I'Berkeley DB: db_jump_set[P

db_jump_set





#include <db.h>

int#db_jump_set(void *func, int which);





Description



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

JNo type checking is done of the func argument, and specifying anIinvalid replacement routine is likely to cause unpredictable results.

3The following values of which are supported:



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

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

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



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

HThe dirfree function returns the value of errno on failureand 0 on success.m

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

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



DThe dir argument is the name of the directory to be searched.EThe function must return a pointer to an array of nul-terminated fileFnames in the memory location referenced by the argument namesp,Iand a count of the number of elements in the array in the memory locationreferenced by cntp.

HThe dirlist function returns the value of errno on failureand 0 on success.d

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

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

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

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

GThe exists function returns the value of errno on failureand 0 on success.

DB_FUNC_FREE
EReplace Berkeley DB calls to the ANSI C X3.159-1989 (ANSI C) standardIfree function with func, which must conform to the standard interface.

DB_FUNC_FSYNC
TReplace Berkeley DB calls to the IEEE Std 1003.1b-1993 (POSIX) fsync function?with func, which must conform to the standard interface.c

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

    $int ioinfo(const char *path, int fd,M    u_int32_t *mbytesp, u_int32_t *bytesp, u_int32_t *iosizep);



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

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

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

GThe ioinfo function returns the value of errno on failureand 0 on success.

DB_FUNC_MALLOC
EReplace Berkeley DB calls to the ANSI C X3.159-1989 (ANSI C) standardKmalloc function with func, which must conform to the standard interface.c

DB_FUNC_MAP
The Berkeley DB library requires the ability to map a file into memory and toGcreate shared memory regions (which may or may not be backed by files).AThe func argument must conform to the following interface:

    'int map(char *path, int fd, size_t len,3    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.

EThe is_region argument will be zero if the intention is to mapa file into shared memory.CIn this case, the map function must map the first len@bytes of the file into memory and return a pointer to the mappedGlocation in the memory location referenced by the argument addr.CIn this case, the is_anonymous argument will always be zero.HThe is_rdonly argument will be non-zero if the file is consideredread-only by the caller.

HThe is_region argument will be non-zero if the memory is intendedLto be used as a shared memory region for synchronization between Berkeley DBthreads/processes.GIn this case, the returned memory may be of any kind (e.g., anonymous),'but must be able to support semaphores.BIf the application has previously specified that regions are to be<instantiated in anonymous memory (see DB_REGION_ANON below),Dor the region is being joined and is believed to have been allocatedDin anonymous shared memory, the is_anonymous argument will be non-zero.DAdditionally, the path and fd arguments may be ignoredA(although future map calls using the same path mustFreturn the same memory), and the is_rdonly argument will alwaysbe zero.

_By default, on UNIX systems, the Berkeley DB library will use the IEEE Std 1003.1b-1993 (POSIX)Emmap(2) interface to both map regular files into shared memory!and create shared memory regions.GIf the application specifies that shared memory regions be instantiated3in anonymous memory (see DB_REGION_ANON below), theDshmget(2) shared memory segment interface will be used, where7available, and the MAP_ANON or MAP_ANONYMOUS options to6mmap(2) when shmget(2) is not available.

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

X

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

SunOS note:
The shmget(2) interfaces are not used on SunOS, even thoughJthey apparently exist, as the distributed include files did not allow themto be compiled.yX

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

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

    db_value_set(1, DB_REGION_NAME);



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

j

eDThe map function returns the value of errno on failureand 0 on success.un

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

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

DB_FUNC_REALLOC
EReplace Berkeley DB calls to the ANSI C X3.159-1989 (ANSI C) standardyLrealloc function with func, which must conform to the standard interface.k

DB_FUNC_RUNLINK
The Berkeley DB library requires the ability to remove shared memory regions froma<the system, whether or not they are backed by regular files.AThe func argument must conform to the following interface:t2

    int runlink(char *path);



bJThe path argument is the path argument specified to the DB_FUNC_MAP0function when the region was mapped into memory.

HThe runlink function returns the value of errno on failureand 0 on success.Nj

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

    1int seek(int fd, size_t pgsize, db_pgno_t pageno,e>    u_int32_t relative, int rewind, int whence);

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

    (pgsize * pageno) + relative



gGIf rewind is non-zero, the byte offset is treated as a backwardsiseek, not a forwards one.e

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

TEThe seek function returns the value of errno on failuretand 0 on success. i

DB_FUNC_SLEEP
The Berkeley DB library requires the ability to cause a process to suspend itselfcIfor a period of time, relinquishing control of the processor to any otherhwaiting thread of control.AThe func argument must conform to the following interface:eI

    int sleep(u_long seconds, u_long microseconds);

i

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

JThe seconds and microseconds arguments may not be normalizedGwhen the sleep function is called, i.e., the microseconds%argument may be greater than 1000000.p

DFThe sleep function returns the value of errno on failureand 0 on success.b>

DB_FUNC_UNLINK
UReplace Berkeley DB calls to the IEEE Std 1003.1b-1993 (POSIX) unlink function ?with func, which must conform to the standard interface.hl

DB_FUNC_UNMAP
The Berkeley DB library requires the ability to unmap a file or shared memory region from memory.AThe func argument must conform to the following interface:u<

    int unmap(void *addr, size_t len);



tMThe addr argument is the argument returned by the DB_FUNC_MAP functionlKwhen the file or region was mapped into memory, and the len argumentLis the same as the len argument specified to the DB_FUNC_MAP function/when the file or region was mapped into memory.n

rFThe unmap function returns the value of errno on failureand 0 on success.

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

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.AThe func argument must conform to the following interface: *

    int yield(void);



mDThe yield function must be able to cause the rescheduling allMparticipants in the current Berkeley DB environment, whether threaded or not.iDIt may be incorrect to supply a thread yield function if moreBthan a single process is operating in the Berkeley DB environment.JThis is because many thread-yield functions will not allow other processesEto run, and the contested lock may be held by another process, not by_another thread._

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

b

Solaris note:
Because of bugs in the Solaris C library, the Berkeley DB library uses the=undocumented _lock_try and _lock_clear function-6calls instead of either the sema_trywait(3T) or$sema_wait(3T) function calls.


eFThe yield function returns the value of errno on failureand 0 on success.e

e

BFApplications should be careful to replace related functions as a groupand at the same time.DReplacing DB_FUNC_MALLOC without replacing DB_FUNC_REALLOC is likely#to result in unpredictable results.e

tThe db_jump_setmHfunction returns the value of errno on failure, and 0 on success.

l

Errors

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

<

a

B

EINVAL
An invalid flag value or parameter was specified.



t



See Also

pA
db_value_seth
SbSÿÿ)Emmap(2) interfa