+++ /dev/null
-.\" Copyright (c) 1990, 1993
-.\" The Regents of the University of California. All rights reserved.
-.\"
-.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
-.\" Redistribution and use in source and binary forms, with or without
-.\" modification, are permitted provided that the following conditions
-.\" are met:
-.\" 1. Redistributions of source code must retain the above copyright
-.\" notice, this list of conditions and the following disclaimer.
-.\" 2. Redistributions in binary form must reproduce the above copyright
-.\" notice, this list of conditions and the following disclaimer in the
-.\" documentation and/or other materials provided with the distribution.
-.\" 3. All advertising materials mentioning features or use of this software
-.\" must display the following acknowledgement:
-.\" This product includes software developed by the University of
-.\" California, Berkeley and its contributors.
-.\" 4. Neither the name of the University nor the names of its contributors
-.\" may be used to endorse or promote products derived from this software
-.\" without specific prior written permission.
-.\"
-.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
-.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
-.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
-.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
-.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
-.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
-.\" SUCH DAMAGE.
-.\" %%%LICENSE_END
-.\"
-.\" @(#)dbopen.3 8.5 (Berkeley) 1/2/94
-.\"
-.TH DBOPEN 3 2012-05-04 "" "Linux Programmer's Manual"
-.UC 7
-.SH NAME
-dbopen \- database access methods
-.SH SYNOPSIS
-.nf
-.B #include <sys/types.h>
-.B #include <limits.h>
-.B #include <db.h>
-.B #include <fcntl.h>
-
-.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 in glibc up until version 2.1.
-Since version 2.2, glibc no longer provides these interfaces.
-Probably, you are looking for the APIs provided by the
-.I libdb
-library instead.
-
-.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:
-.sp
-.in +4n
-.nf
-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;
-.fi
-.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:
-.in +4n
-.nf
-
-typedef struct {
- void *data;
- size_t size;
-} DBT;
-.fi
-.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)
-
-.IR "LIBTP: Portable, Modular Transactions for UNIX" ,
-Margo Seltzer, Michael Olson, USENIX proceedings, Winter 1992.
-.SH COLOPHON
-This page is part of release 3.79 of the Linux
-.I man-pages
-project.
-A description of the project,
-information about reporting bugs,
-and the latest version of this page,
-can be found at
-\%http://www.kernel.org/doc/man\-pages/.
OSDN Git Service
