diff options
Diffstat (limited to 'man3/dbopen.3')
| -rw-r--r-- | man3/dbopen.3 | 536 |
1 files changed, 0 insertions, 536 deletions
diff --git a/man3/dbopen.3 b/man3/dbopen.3 deleted file mode 100644 index 516768b..0000000 --- a/man3/dbopen.3 +++ /dev/null @@ -1,536 +0,0 @@ -.\" Copyright (c) 1990, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" SPDX-License-Identifier: BSD-4-Clause-UC -.\" -.\" @(#)dbopen.3 8.5 (Berkeley) 1/2/94 -.\" -.TH dbopen 3 2023-10-31 "Linux man-pages 6.7" -.UC 7 -.SH NAME -dbopen \- database access methods -.SH LIBRARY -Standard C library -.RI ( libc ", " \-lc ) -.SH SYNOPSIS -.nf -.B #include <sys/types.h> -.B #include <limits.h> -.B #include <db.h> -.B #include <fcntl.h> -.P -.BI "DB *dbopen(const char *" file ", int " flags ", int " mode \ -", DBTYPE " type , -.BI " const void *" openinfo ); -.fi -.SH DESCRIPTION -.IR "Note well" : -This page documents interfaces provided up until glibc 2.1. -Since glibc 2.2, glibc no longer provides these interfaces. -Probably, you are looking for the APIs provided by the -.I libdb -library instead. -.P -.BR dbopen () -is the library interface to database files. -The supported file formats are btree, hashed, and UNIX file oriented. -The btree format is a representation of a sorted, balanced tree structure. -The hashed format is an extensible, dynamic hashing scheme. -The flat-file format is a byte stream file with fixed or variable length -records. -The formats and file-format-specific information are described in detail -in their respective manual pages -.BR btree (3), -.BR hash (3), -and -.BR recno (3). -.P -.BR dbopen () -opens -.I file -for reading and/or writing. -Files never intended to be preserved on disk may be created by setting -the -.I file -argument to NULL. -.P -The -.I flags -and -.I mode -arguments are as specified to the -.BR open (2) -routine, however, only the -.BR O_CREAT , -.BR O_EXCL , -.BR O_EXLOCK , -.BR O_NONBLOCK , -.BR O_RDONLY , -.BR O_RDWR , -.BR O_SHLOCK , -and -.B O_TRUNC -flags are meaningful. -(Note, opening a database file -.B O_WRONLY -is not possible.) -.\"Three additional options may be specified by ORing -.\"them into the -.\".I flags -.\"argument. -.\".TP -.\"DB_LOCK -.\"Do the necessary locking in the database to support concurrent access. -.\"If concurrent access isn't needed or the database is read-only this -.\"flag should not be set, as it tends to have an associated performance -.\"penalty. -.\".TP -.\"DB_SHMEM -.\"Place the underlying memory pool used by the database in shared -.\"memory. -.\"Necessary for concurrent access. -.\".TP -.\"DB_TXN -.\"Support transactions in the database. -.\"The DB_LOCK and DB_SHMEM flags must be set as well. -.P -The -.I type -argument is of type -.I DBTYPE -(as defined in the -.I <db.h> -include file) and -may be set to -.BR DB_BTREE , -.BR DB_HASH , -or -.BR DB_RECNO . -.P -The -.I openinfo -argument is a pointer to an access-method-specific structure described -in the access method's manual page. -If -.I openinfo -is NULL, each access method will use defaults appropriate for the system -and the access method. -.P -.BR dbopen () -returns a pointer to a -.I DB -structure on success and NULL on error. -The -.I DB -structure is defined in the -.I <db.h> -include file, and contains at -least the following fields: -.P -.in +4n -.EX -typedef struct { - DBTYPE type; - int (*close)(const DB *db); - int (*del)(const DB *db, const DBT *key, unsigned int flags); - int (*fd)(const DB *db); - int (*get)(const DB *db, DBT *key, DBT *data, - unsigned int flags); - int (*put)(const DB *db, DBT *key, const DBT *data, - unsigned int flags); - int (*sync)(const DB *db, unsigned int flags); - int (*seq)(const DB *db, DBT *key, DBT *data, - unsigned int flags); -} DB; -.EE -.in -.P -These elements describe a database type and a set of functions performing -various actions. -These functions take a pointer to a structure as returned by -.BR dbopen (), -and sometimes one or more pointers to key/data structures and a flag value. -.TP -.I type -The type of the underlying access method (and file format). -.TP -.I close -A pointer to a routine to flush any cached information to disk, free any -allocated resources, and close the underlying file(s). -Since key/data pairs may be cached in memory, failing to sync the file -with a -.I close -or -.I sync -function may result in inconsistent or lost information. -.I close -routines return \-1 on error (setting -.IR errno ) -and 0 on success. -.TP -.I del -A pointer to a routine to remove key/data pairs from the database. -.IP -The argument -.I flag -may be set to the following value: -.RS -.TP -.B R_CURSOR -Delete the record referenced by the cursor. -The cursor must have previously been initialized. -.RE -.IP -.I delete -routines return \-1 on error (setting -.IR errno ), -0 on success, and 1 if the specified -.I key -was not in the file. -.TP -.I fd -A pointer to a routine which returns a file descriptor representative -of the underlying database. -A file descriptor referencing the same file will be returned to all -processes which call -.BR dbopen () -with the same -.I file -name. -This file descriptor may be safely used as an argument to the -.BR fcntl (2) -and -.BR flock (2) -locking functions. -The file descriptor is not necessarily associated with any of the -underlying files used by the access method. -No file descriptor is available for in memory databases. -.I fd -routines return \-1 on error (setting -.IR errno ), -and the file descriptor on success. -.TP -.I get -A pointer to a routine which is the interface for keyed retrieval from -the database. -The address and length of the data associated with the specified -.I key -are returned in the structure referenced by -.IR data . -.I get -routines return \-1 on error (setting -.IR errno ), -0 on success, and 1 if the -.I key -was not in the file. -.TP -.I put -A pointer to a routine to store key/data pairs in the database. -.IP -The argument -.I flag -may be set to one of the following values: -.RS -.TP -.B R_CURSOR -Replace the key/data pair referenced by the cursor. -The cursor must have previously been initialized. -.TP -.B R_IAFTER -Append the data immediately after the data referenced by -.IR key , -creating a new key/data pair. -The record number of the appended key/data pair is returned in the -.I key -structure. -(Applicable only to the -.B DB_RECNO -access method.) -.TP -.B R_IBEFORE -Insert the data immediately before the data referenced by -.IR key , -creating a new key/data pair. -The record number of the inserted key/data pair is returned in the -.I key -structure. -(Applicable only to the -.B DB_RECNO -access method.) -.TP -.B R_NOOVERWRITE -Enter the new key/data pair only if the key does not previously exist. -.TP -.B R_SETCURSOR -Store the key/data pair, setting or initializing the position of the -cursor to reference it. -(Applicable only to the -.B DB_BTREE -and -.B DB_RECNO -access methods.) -.RE -.IP -.B R_SETCURSOR -is available only for the -.B DB_BTREE -and -.B DB_RECNO -access -methods because it implies that the keys have an inherent order -which does not change. -.IP -.B R_IAFTER -and -.B R_IBEFORE -are available only for the -.B DB_RECNO -access method because they each imply that the access method is able to -create new keys. -This is true only if the keys are ordered and independent, record numbers -for example. -.IP -The default behavior of the -.I put -routines is to enter the new key/data pair, replacing any previously -existing key. -.IP -.I put -routines return \-1 on error (setting -.IR errno ), -0 on success, and 1 if the -.B R_NOOVERWRITE -.I flag -was set and the key already exists in the file. -.TP -.I seq -A pointer to a routine which is the interface for sequential -retrieval from the database. -The address and length of the key are returned in the structure -referenced by -.IR key , -and the address and length of the data are returned in the -structure referenced -by -.IR data . -.IP -Sequential key/data pair retrieval may begin at any time, and the -position of the "cursor" is not affected by calls to the -.IR del , -.IR get , -.IR put , -or -.I sync -routines. -Modifications to the database during a sequential scan will be reflected -in the scan, that is, -records inserted behind the cursor will not be returned -while records inserted in front of the cursor will be returned. -.IP -The flag value -.B must -be set to one of the following values: -.RS -.TP -.B R_CURSOR -The data associated with the specified key is returned. -This differs from the -.I get -routines in that it sets or initializes the cursor to the location of -the key as well. -(Note, for the -.B DB_BTREE -access method, the returned key is not necessarily an -exact match for the specified key. -The returned key is the smallest key greater than or equal to the specified -key, permitting partial key matches and range searches.) -.TP -.B R_FIRST -The first key/data pair of the database is returned, and the cursor -is set or initialized to reference it. -.TP -.B R_LAST -The last key/data pair of the database is returned, and the cursor -is set or initialized to reference it. -(Applicable only to the -.B DB_BTREE -and -.B DB_RECNO -access methods.) -.TP -.B R_NEXT -Retrieve the key/data pair immediately after the cursor. -If the cursor is not yet set, this is the same as the -.B R_FIRST -flag. -.TP -.B R_PREV -Retrieve the key/data pair immediately before the cursor. -If the cursor is not yet set, this is the same as the -.B R_LAST -flag. -(Applicable only to the -.B DB_BTREE -and -.B DB_RECNO -access methods.) -.RE -.IP -.B R_LAST -and -.B R_PREV -are available only for the -.B DB_BTREE -and -.B DB_RECNO -access methods because they each imply that the keys have an inherent -order which does not change. -.IP -.I seq -routines return \-1 on error (setting -.IR errno ), -0 on success and 1 if there are no key/data pairs less than or greater -than the specified or current key. -If the -.B DB_RECNO -access method is being used, and if the database file -is a character special file and no complete key/data pairs are currently -available, the -.I seq -routines return 2. -.TP -.I sync -A pointer to a routine to flush any cached information to disk. -If the database is in memory only, the -.I sync -routine has no effect and will always succeed. -.IP -The flag value may be set to the following value: -.RS -.TP -.B R_RECNOSYNC -If the -.B DB_RECNO -access method is being used, this flag causes -the sync routine to apply to the btree file which underlies the -recno file, not the recno file itself. -(See the -.I bfname -field of the -.BR recno (3) -manual page for more information.) -.RE -.IP -.I sync -routines return \-1 on error (setting -.IR errno ) -and 0 on success. -.SS Key/data pairs -Access to all file types is based on key/data pairs. -Both keys and data are represented by the following data structure: -.P -.in +4n -.EX -typedef struct { - void *data; - size_t size; -} DBT; -.EE -.in -.P -The elements of the -.I DBT -structure are defined as follows: -.TP -.I data -A pointer to a byte string. -.TP -.I size -The length of the byte string. -.P -Key and data byte strings may reference strings of essentially unlimited -length although any two of them must fit into available memory at the same -time. -It should be noted that the access methods provide no guarantees about -byte string alignment. -.SH ERRORS -The -.BR dbopen () -routine may fail and set -.I errno -for any of the errors specified for the library routines -.BR open (2) -and -.BR malloc (3) -or the following: -.TP -.B EFTYPE -A file is incorrectly formatted. -.TP -.B EINVAL -A parameter has been specified (hash function, pad byte, etc.) that is -incompatible with the current file specification or which is not -meaningful for the function (for example, use of the cursor without -prior initialization) or there is a mismatch between the version -number of file and the software. -.P -The -.I close -routines may fail and set -.I errno -for any of the errors specified for the library routines -.BR close (2), -.BR read (2), -.BR write (2), -.BR free (3), -or -.BR fsync (2). -.P -The -.IR del , -.IR get , -.IR put , -and -.I seq -routines may fail and set -.I errno -for any of the errors specified for the library routines -.BR read (2), -.BR write (2), -.BR free (3), -or -.BR malloc (3). -.P -The -.I fd -routines will fail and set -.I errno -to -.B ENOENT -for in memory databases. -.P -The -.I sync -routines may fail and set -.I errno -for any of the errors specified for the library routine -.BR fsync (2). -.SH BUGS -The typedef -.I DBT -is a mnemonic for "data base thang", and was used -because no one could think of a reasonable name that wasn't already used. -.P -The file descriptor interface is a kludge and will be deleted in a -future version of the interface. -.P -None of the access methods provide any form of concurrent access, -locking, or transactions. -.SH SEE ALSO -.BR btree (3), -.BR hash (3), -.BR mpool (3), -.BR recno (3) -.P -.IR "LIBTP: Portable, Modular Transactions for UNIX" , -Margo Seltzer, Michael Olson, USENIX proceedings, Winter 1992. |