Adding upstream version 6.05.01.upstream/6.05.01

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 536 insertions, 0 deletions

diff --git a/man3/dbopen.3 b/man3/dbopen.3
new file mode 100644
index 0000000..a6d418a
--- /dev/null
+++ b/man3/dbopen.3
@@ -0,0 +1,536 @@
+.\" 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 2022-12-04 "Linux man-pages 6.05.01"
+.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>
+.PP
+.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.
+.PP
+.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).
+.PP
+.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.
+.PP
+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.
+.PP
+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 .
+.PP
+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.
+.PP
+.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:
+.PP
+.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
+.PP
+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:
+.PP
+.in +4n
+.EX
+typedef struct {
+    void  *data;
+    size_t size;
+} DBT;
+.EE
+.in
+.PP
+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.
+.PP
+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.
+.PP
+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).
+.PP
+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).
+.PP
+The
+.I fd
+routines will fail and set
+.I errno
+to
+.B ENOENT
+for in memory databases.
+.PP
+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.
+.PP
+The file descriptor interface is a kludge and will be deleted in a
+future version of the interface.
+.PP
+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)
+.PP
+.IR "LIBTP: Portable, Modular Transactions for UNIX" ,
+Margo Seltzer, Michael Olson, USENIX proceedings, Winter 1992.