| .\" 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 2017-09-15 "" "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> |
| .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 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. |
| .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. |