NNAAMMEE db_jump_set, db_value_set - replace underlying DB func- tionality SSYYNNOOPPSSIISS ##iinncclluuddee <> iinntt ddbb__jjuummpp__sseett((vvooiidd **ffuunncc,, iinntt wwhhiicchh));; iinntt ddbb__vvaalluuee__sseett((iinntt vvaalluuee,, iinntt wwhhiicchh));; DDEESSCCRRIIPPTTIIOONN 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 _d_b___i_n_t_r_o(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 inter- faces. _d_b___j_u_m_p___s_e_t The _d_b___j_u_m_p___s_e_t function enables applications to replace underlying DB library functionality by replacing entries in a function call jump table. The _w_h_i_c_h argument speci- fies the entry to be replaced by the argument _f_u_n_c. The following values of _w_h_i_c_h are supported: DB_FUNC_CLOSE Replace all DB calls to the IEEE Std 1003.1b-1993 (``POSIX'') _c_l_o_s_e function with _f_u_n_c, which must con- form 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 _f_u_n_c argument must conform to the following interface: int dirfree(char **namesp, int cnt); The _n_a_m_e_s_p and _c_n_t arguments are the same values as were returned by the DB_FUNC_DIRLIST function. The _d_i_r_f_r_e_e function returns the value of _e_r_r_n_o 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 _f_u_n_c argument must conform to the following interface: int dirlist(const char *dir, char ***namesp, int *cntp); The _d_i_r 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 _n_a_m_e_s_p, and a count of the number of elements in the array in the memory location referenced by _c_n_t_p. The _d_i_r_l_i_s_t function returns the value of _e_r_r_n_o 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 _f_u_n_c argument must conform to the following interface: int exists(const char *path, int *isdirp); The _p_a_t_h argument is the pathname of the file to be checked. If the _i_s_d_i_r_p argument is non-NULL, it must be set to non-0 if _p_a_t_h is a directory, and 0 if _p_a_t_h is not a directory. The _e_x_i_s_t_s function returns the value of _e_r_r_n_o on failure and 0 on success. DB_FUNC_FREE Replace all DB calls to the ANSI C X3.159-1989 (``ANSI C'') standard _f_r_e_e function with _f_u_n_c, which must conform to the standard interface. DB_FUNC_FSYNC Replace all DB calls to the IEEE Std 1003.1b-1993 (``POSIX'') _f_s_y_n_c function with _f_u_n_c, which must con- form 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 _f_u_n_c 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 _p_a_t_h argument is the pathname of the file to be checked, and the _f_d argument is an open file descrip- tor on the file. If the _m_b_y_t_e_s_p and _b_y_t_e_s_p arguments are non-NULL, the _i_o_i_n_f_o function must return in them the size of the file: the number of megabytes in the file into the memory location referenced by the _m_b_y_t_e_s_p argument, and the number of bytes over and above that number of megabytes into the memory location referenced by the _b_y_t_e_s_p argument. In addition, if the _i_o_s_i_z_e_p argument is non-NULL, the _i_o_i_n_f_o function must return the optimum granularity for I/O operations to the file in the memory location referenced by it. The _i_o_i_n_f_o function returns the value of _e_r_r_n_o on failure and 0 on success. DB_FUNC_MALLOC Replace all DB calls to the ANSI C X3.159-1989 (``ANSI C'') standard _m_a_l_l_o_c function with _f_u_n_c, 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 _f_u_n_c 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 _p_a_t_h argument is the name of a file. The _f_d argument is an open file descriptor on that file. The _i_s___r_e_g_i_o_n argument will be zero if the intention is to map a file into shared memory. In this case, the _m_a_p function must map the first _l_e_n bytes of the file into memory and return a pointer to the mapped location in the memory location referenced by the argument _a_d_d_r. In this case, the _i_s___a_n_o_n_y_m_o_u_s argu- ment will always be zero. The _i_s___r_d_o_n_l_y argument will be non-zero if the file is considered read-only by the caller. The _i_s___r_e_g_i_o_n 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 speci- fied 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 _i_s___a_n_o_n_y_m_o_u_s argument will be non-zero. Additionally, the _p_a_t_h and _f_d arguments may be ignored (although future _m_a_p calls using the same _p_a_t_h must return the same memory), and the _i_s___r_d_o_n_l_y argument will always be zero. By default, on UNIX systems, the DB library will use the IEEE Std 1003.1b-1993 (``POSIX'') _m_m_a_p(2) inter- face 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 _s_h_m_g_e_t(2) shared memory segment interface will be used, where available, and the MAP_ANON or MAP_ANONY- MOUS options to _m_m_a_p(2) when _s_h_m_g_e_t(2) is not avail- able. When using _s_h_m_g_e_t(2), shared memory regions are named, and so multiple processes may share them. When using the _m_m_a_p MAP_ANON or MAP_ANONYMOUS options, shared memory regions are nnoott named, and so may only be accessed by a single process and its threads. HP/UX note: The _s_h_m_g_e_t(2) interfaces are not used on HP/UX, even though they exist, as anonymous memory allocated using _s_h_m_g_e_t(2) cannot be used to store semaphores. The _m_a_p function returns the value of _e_r_r_n_o on failure and 0 on success. DB_FUNC_OPEN Replace all DB calls to the IEEE Std 1003.1b-1993 (``POSIX'') _o_p_e_n function with _f_u_n_c, which must con- form to the standard interface. DB_FUNC_READ Replace all DB calls to the IEEE Std 1003.1b-1993 (``POSIX'') _r_e_a_d function with _f_u_n_c, which must con- form to the standard interface. DB_FUNC_REALLOC Replace all DB calls to the ANSI C X3.159-1989 (``ANSI C'') standard _r_e_a_l_l_o_c function with _f_u_n_c, 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 _f_u_n_c argument must conform to the following interface: int runlink(char *path); The _p_a_t_h argument is the path argument specified to the DB_FUNC_MAP function when the region was mapped into memory. The _r_u_n_l_i_n_k function returns the value of _e_r_r_n_o 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 _f_u_n_c 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 _f_d argument is an open file descriptor on the file. The _s_e_e_k 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 _r_e_w_i_n_d is non-zero, the byte offset is treated as a backwards seek, not a forwards one. The _w_h_e_n_c_e argument specifies where in the file the byte offset is relative to, as described by the IEEE Std 1003.1b-1993 (``POSIX'') _l_s_e_e_k system call. The _s_e_e_k function returns the value of _e_r_r_n_o on fail- ure and 0 on success. 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 _f_u_n_c argument must con- form to the following interface: int sleep(u_long seconds, u_long microseconds); The _s_e_c_o_n_d_s and _m_i_c_r_o_s_e_c_o_n_d_s arguments specify the amount of time to wait until the suspending thread of control should run again. The _s_e_c_o_n_d_s and _m_i_c_r_o_s_e_c_o_n_d_s arguments may not be normalized when the _s_l_e_e_p function is called, i.e., the _m_i_c_r_o_s_e_c_o_n_d_s argument may be greater than 1000000. The _s_l_e_e_p function returns the value of _e_r_r_n_o on failure and 0 on success. DB_FUNC_UNLINK Replace all DB calls to the IEEE Std 1003.1b-1993 (``POSIX'') _u_n_l_i_n_k function with _f_u_n_c, 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 _f_u_n_c argu- ment must conform to the following interface: int unmap(void *addr, size_t len); The _a_d_d_r argument is the argument returned by the DB_FUNC_MAP function when the file or region was mapped into memory, and the _l_e_n argument is the same as the _l_e_n argument specified to the DB_FUNC_MAP function when the file or region was mapped into mem- ory. The _u_n_m_a_p function returns the value of _e_r_r_n_o on failure and 0 on success. DB_FUNC_WRITE Replace all DB calls to the IEEE Std 1003.1b-1993 (``POSIX'') _w_r_i_t_e function with _f_u_n_c, which must con- form to the standard interface. DB_FUNC_YIELD The DB library requires the ability to yield the pro- cessor from the current thread of control to any other waiting threads of control. The _f_u_n_c argument must conform to the following interface: int yield(void); The _y_i_e_l_d function must be able to cause the rescheduling all participants in the current DB envi- ronment, whether threaded or not. It may be incor- rect to supply a thread _y_i_e_l_d 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 _y_i_e_l_d function is specified, or if the _y_i_e_l_d function returns an error, the function specified by the DB_FUNC_SLEEP entry will be used instead or sub- sequently, i.e., if no _y_i_e_l_d function is specified, or it is possible for the _y_i_e_l_d function to fail, the _s_l_e_e_p function mmuusstt cause the processor to reschedule any waiting threads of control for execution. The _y_i_e_l_d function returns the value of _e_r_r_n_o on failure and 0 on success. The _d_b___j_u_m_p___s_e_t function returns the value of _e_r_r_n_o on failure and 0 on success. _d_b___v_a_l_u_e___s_e_t The _d_b___v_a_l_u_e___s_e_t function enables applications to specify underlying DB library functionality. The _w_h_i_c_h argument specifies the information being set by the argument _v_a_l_u_e. The following values of _w_h_i_c_h 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 _v_a_l_u_e 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 can- not 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 _v_a_l_u_e 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 _v_a_l_u_e 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 informa- tion. DB_TSL_SPINS Specify the number of times mutexes should spin with- out blocking. This value defaults to 1 on uniprocessor systems and to 50 times the number of processors on multiproces- sor systems. The _d_b___v_a_l_u_e___s_e_t function returns the value of _e_r_r_n_o on failure and 0 on success. EERRRROORRSS The _d_b___j_u_m_p___s_e_t function may fail and return _e_r_r_n_o for the following conditions: [EINVAL] An invalid flag value or parameter was specified. BBUUGGSS No type checking is done of the _f_u_n_c argument, and speci- fying an invalid replacement routine will cause unpre- dictable results. Applications should be careful to replace related func- tions 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 guaran- tee 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 _d_b___v_a_l_u_e___s_e_t. That will allow DB to use the file itself for sharing, which works correctly. SSEEEE AALLSSOO _d_b___a_r_c_h_i_v_e(1), _d_b___c_h_e_c_k_p_o_i_n_t(1), _d_b___d_e_a_d_l_o_c_k(1), _d_b___d_u_m_p(1), _d_b___l_o_a_d(1), _d_b___r_e_c_o_v_e_r(1), _d_b___s_t_a_t(1), _d_b___i_n_t_r_o(3), _d_b___a_p_p_i_n_i_t(3), _d_b___c_u_r_s_o_r(3), _d_b___d_b_m(3), _d_b___i_n_t_e_r_n_a_l(3), _d_b___l_o_c_k(3), _d_b___l_o_g(3), _d_b___m_p_o_o_l(3), _d_b___o_p_e_n(3), _d_b___t_h_r_e_a_d(3), _d_b___t_x_n(3)