1.\" $NetBSD: dbopen.3,v 1.19 2010/12/16 12:08:16 jruoho Exp $ 2.\" 3.\" Copyright (c) 1990, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)dbopen.3 8.5 (Berkeley) 1/2/94 31.\" 32.Dd December 16, 2010 33.Dt DBOPEN 3 34.Os 35.Sh NAME 36.Nm dbopen , 37.Nm db 38.Nd database access methods 39.Sh SYNOPSIS 40.In sys/types.h 41.In limits.h 42.In db.h 43.In fcntl.h 44.Ft DB * 45.Fn dbopen "const char *file" "int flags" "mode_t mode" \ 46"DBTYPE type" "const void *openinfo" 47.Sh DESCRIPTION 48.Nm 49is the library interface to database files. 50The supported file formats are btree, hashed, and UNIX file oriented. 51The btree format is a representation of a sorted, balanced tree 52structure. 53The hashed format is an extensible, dynamic hashing scheme. 54The flat-file format is a byte stream file with fixed or variable 55length records. 56The formats and file format specific information are described in 57detail in their respective manual pages 58.Xr btree 3 , 59.Xr hash 3 , 60and 61.Xr recno 3 . 62.Pp 63The 64.Fn dbopen 65function opens 66.Fa file 67for reading and/or writing. 68Files never intended to be preserved on disk may be created by setting 69the file parameter to 70.Dv NULL . 71.Pp 72The 73.Fa flags 74and 75.Fa mode 76arguments are as specified to the 77.Xr open 2 78routine, however, only the 79.Dv O_CREAT , 80.Dv O_EXCL , 81.Dv O_EXLOCK , 82.Dv O_NONBLOCK , 83.Dv O_RDONLY , 84.Dv O_RDWR , 85.Dv O_SHLOCK , 86and 87.Dv O_TRUNC 88flags are meaningful. 89(Note, opening a database file 90.Dv O_WRONLY 91is not possible.) 92.\"Three additional options may be specified by or'ing 93.\"them into the 94.\".Fa flags 95.\"argument. 96.\".Pp 97.\".Dv DB_LOCK 98.\"Do the necessary locking in the database to support concurrent access. 99.\"If concurrent access isn't needed or the database is read-only this 100.\"flag should not be set, as it tends to have an associated performance 101.\"penalty. 102.\".Pp 103.\".Dv DB_SHMEM 104.\"Place the underlying memory pool used by the database in shared 105.\"memory. 106.\"Necessary for concurrent access. 107.\".Pp 108.\".Dv DB_TXN 109.\"Support transactions in the database. 110.\"The 111.\".Dv DB_LOCK 112.\"and 113.\".Dv DB_SHMEM 114.\"flags must be set as well. 115.Pp 116The 117.Fa type 118argument is of type 119.Vt DBTYPE 120(as defined in the 121.In db.h 122include file) and may be set to 123.Dv DB_BTREE , 124.Dv DB_HASH , 125or 126.Dv DB_RECNO . 127.Pp 128The 129.Fa openinfo 130argument is a pointer to an access method specific structure described 131in the access method's manual page. 132If 133.Fa openinfo 134is 135.Dv NULL , 136each access method will use defaults appropriate for the system and 137the access method. 138.Ss The DB Structure 139The 140.Fn dbopen 141function returns a pointer to a DB structure on success and 142.Dv NULL 143on error. 144The DB structure is defined in the 145.In db.h 146include file, and contains at least the following fields: 147.Bd -literal -offset indent 148typedef struct { 149 DBTYPE type; 150 int (*close)(const DB *db); 151 int (*del)(const DB *db, const DBT *key, u_int flags); 152 int (*fd)(const DB *db); 153 int (*get)(const DB *db, DBT *key, DBT *data, u_int flags); 154 int (*put)(const DB *db, DBT *key, const DBT *data, 155 u_int flags); 156 int (*sync)(const DB *db, u_int flags); 157 int (*seq)(const DB *db, DBT *key, DBT *data, u_int flags); 158} DB; 159.Ed 160.Pp 161These elements describe a database type and a set of functions 162performing various actions. 163These functions take a pointer to a structure as returned by 164.Nm , 165and sometimes one or more pointers to key/data structures and a flag 166value. 167.Bl -tag -width closex -offset indent 168.It Fa type 169The type of the underlying access method (and file format). 170.It Fa close 171A pointer to a routine to flush any cached information to disk, free 172any allocated resources, and close the underlying file(s). 173Since key/data pairs may be cached in memory, failing to sync the file 174with a 175.Fa close 176or 177.Fa sync 178function may result in inconsistent or lost information. 179.Fa close 180routines return \-1 on error (setting 181.Va errno ) 182and 0 on success. 183.It Fa del 184A pointer to a routine to remove key/data pairs from the database. 185.Pp 186The parameter 187.Fa flag 188may be set to the following value: 189.Bl -tag -width R_CURSORX 190.It Dv R_CURSOR 191Delete the record referenced by the cursor. 192The cursor must have previously been initialized. 193.El 194.Pp 195.Fa delete 196routines return \-1 on error (setting 197.Va errno ) , 1980 on success, and 1 if the specified 199.Fa key 200was not in the file. 201.It Fa fd 202A pointer to a routine which returns a file descriptor representative 203of the underlying database. 204A file descriptor referencing the same file will be returned to all 205processes which call 206.Nm 207with the same 208.Fa file 209name. 210This file descriptor may be safely used as an argument to the 211.Xr fcntl 2 212and 213.Xr flock 2 214locking functions. 215The file descriptor is not necessarily associated with any of the 216underlying files used by the access method. 217No file descriptor is available for in memory databases. 218.Fa fd 219routines return \-1 on error (setting 220.Va errno ) , 221and the file descriptor on success. 222.It Fa get 223A pointer to a routine which is the interface for keyed retrieval from 224the database. 225The address and length of the data associated with the specified 226.Fa key 227are returned in the structure referenced by 228.Fa data . 229.Fa get 230routines return \-1 on error (setting 231.Va errno ) , 2320 on success, and 1 if the 233.Fa key 234was not in the file. 235.It Fa put 236A pointer to a routine to store key/data pairs in the database. 237.Pp 238The parameter 239.Fa flag 240may be set to one of the following values: 241.Bl -tag -width R_NOOVERWRITEX 242.It Dv R_CURSOR 243Replace the key/data pair referenced by the cursor. 244The cursor must have previously been initialized. 245.It Dv R_IAFTER 246Append the data immediately after the data referenced by 247.Fa key , 248creating a new key/data pair. 249The record number of the appended key/data pair is returned in the 250.Fa key 251structure. 252(Applicable only to the 253.Dv DB_RECNO 254access method.) 255.It Dv R_IBEFORE 256Insert the data immediately before the data referenced by 257.Fa key , 258creating a new key/data pair. 259The record number of the inserted key/data pair is returned in the 260.Fa key 261structure. 262(Applicable only to the 263.Dv DB_RECNO 264access method.) 265.It Dv R_NOOVERWRITE 266Enter the new key/data pair only if the key does not previously 267exist. 268.It Dv R_SETCURSOR 269Store the key/data pair, setting or initializing the position of the 270cursor to reference it. 271(Applicable only to the 272.Dv DB_BTREE 273and 274.Dv DB_RECNO 275access methods.) 276.El 277.Pp 278.Dv R_SETCURSOR 279is available only for the 280.Dv DB_BTREE 281and 282.Dv DB_RECNO 283access methods because it implies that the keys have an inherent order 284which does not change. 285.Pp 286.Dv R_IAFTER 287and 288.Dv R_IBEFORE 289are available only for the 290.Dv DB_RECNO 291access method because they each imply that the access method is able 292to create new keys. 293This is only true if the keys are ordered and independent, record 294numbers for example. 295.Pp 296The default behavior of the 297.Fa put 298routines is to enter the new key/data pair, replacing any previously 299existing key. 300.Pp 301.Fa put 302routines return \-1 on error (setting 303.Va errno ) , 3040 on success, and 1 if the 305.Dv R_NOOVERWRITE 306.Fa flag 307was set and the key already exists in the file. 308.It Fa seq 309A pointer to a routine which is the interface for sequential 310retrieval from the database. 311The address and length of the key are returned in the structure 312referenced by 313.Fa key , 314and the address and length of the data are returned in the 315structure referenced by 316.Fa data . 317.Pp 318Sequential key/data pair retrieval may begin at any time, and the 319position of the 320.Dq cursor 321is not affected by calls to the 322.Fa del , 323.Fa get , 324.Fa put , 325or 326.Fa sync 327routines. 328Modifications to the database during a sequential scan will be 329reflected in the scan, i.e., records inserted behind the cursor will 330not be returned while records inserted in front of the cursor will be 331returned. 332.Pp 333The flag value 334.Em must 335be set to one of the following values: 336.Bl -tag -width R_CURSORX 337.It Dv R_CURSOR 338The data associated with the specified key is returned. 339This differs from the 340.Fa get 341routines in that it sets or initializes the cursor to the location of 342the key as well. 343(Note, for the 344.Dv DB_BTREE 345access method, the returned key is not necessarily an exact match for 346the specified key. 347The returned key is the smallest key greater than or equal to the 348specified key, permitting partial key matches and range searches.) 349.It Dv R_FIRST 350The first key/data pair of the database is returned, and the cursor 351is set or initialized to reference it. 352.It Dv R_LAST 353The last key/data pair of the database is returned, and the cursor 354is set or initialized to reference it. 355(Applicable only to the 356.Dv DB_BTREE 357and 358.Dv DB_RECNO 359access methods.) 360.It Dv R_NEXT 361Retrieve the key/data pair immediately after the cursor. 362If the cursor is not yet set, this is the same as the 363.Dv R_FIRST 364flag. 365.It Dv R_PREV 366Retrieve the key/data pair immediately before the cursor. 367If the cursor is not yet set, this is the same as the 368.Dv R_LAST 369flag. 370(Applicable only to the 371.Dv DB_BTREE 372and 373.Dv DB_RECNO 374access methods.) 375.El 376.Pp 377.Dv R_LAST 378and 379.Dv R_PREV 380are available only for the 381.Dv DB_BTREE 382and 383.Dv DB_RECNO 384access methods because they each imply that the keys have an inherent 385order which does not change. 386.Pp 387.Fa seq 388routines return \-1 on error (setting 389.Va errno ) , 3900 on success and 1 if there are no key/data pairs less than or greater 391than the specified or current key. 392If the 393.Dv DB_RECNO 394access method is being used, and if the database file is a character 395special file and no complete key/data pairs are currently available, 396the 397.Fa seq 398routines return 2. 399.It Fa sync 400A pointer to a routine to flush any cached information to disk. 401If the database is in memory only, the 402.Fa sync 403routine has no effect and will always succeed. 404.Pp 405The flag value may be set to the following value: 406.Bl -tag -width ".Dv R_RECNOSYNC" 407.It Dv R_RECNOSYNC 408If the 409.Dv DB_RECNO 410access method is being used, this flag causes the sync routine to 411apply to the btree file which underlies the recno file, not the recno 412file itself. 413(See the 414.Fa bfname 415field of the 416.Xr recno 3 417manual page for more information.) 418.El 419.Pp 420.Fa sync 421routines return \-1 on error (setting 422.Va errno ) 423and 0 on success. 424.El 425.Ss Key/data Pairs 426Access to all file types is based on key/data pairs. 427Both keys and data are represented by the following data structure: 428.Bd -literal -offset indent 429typedef struct { 430 void *data; 431 size_t size; 432} DBT; 433.Ed 434.Pp 435The elements of the DBT structure are defined as follows: 436.Bl -tag -width datax -offset indent 437.It Fa data 438A pointer to a byte string. 439.It Fa size 440The length of the byte string. 441.El 442.Pp 443Key and data byte strings may reference strings of essentially 444unlimited length although any two of them must fit into available 445memory at the same time. 446It should be noted that the access methods provide no guarantees about 447byte string alignment. 448.Sh ERRORS 449The 450.Nm 451routine may fail and set 452.Va errno 453for any of the errors specified for the library routines 454.Xr open 2 455and 456.Xr malloc 3 457or the following: 458.Bl -tag -width Er 459.It Er EFTYPE 460A file is incorrectly formatted. 461.It Er EINVAL 462A parameter has been specified (hash function, pad byte, etc.) that is 463incompatible with the current file specification or which is not 464meaningful for the function (for example, use of the cursor without 465prior initialization) or there is a mismatch between the version 466number of file and the software. 467.It Er EFBIG 468The key could not be inserted due to limitations in the DB file format 469(e.g., a hash database was out of overflow pages). 470.El 471.Pp 472The 473.Fa close 474routines may fail and set 475.Va errno 476for any of the errors specified for the library routines 477.Xr close 2 , 478.Xr read 2 , 479.Xr write 2 , 480.Xr free 3 , 481or 482.Xr fsync 2 . 483.Pp 484The 485.Fa del , 486.Fa get , 487.Fa put , 488and 489.Fa seq 490routines may fail and set 491.Va errno 492for any of the errors specified for the library routines 493.Xr read 2 , 494.Xr write 2 , 495.Xr free 3 , 496or 497.Xr malloc 3 . 498.Pp 499The 500.Fa fd 501routines will fail and set 502.Va errno 503to 504.Er ENOENT 505for in memory databases. 506.Pp 507The 508.Fa sync 509routines may fail and set 510.Va errno 511for any of the errors specified for the library routine 512.Xr fsync 2 . 513.Sh SEE ALSO 514.Xr btree 3 , 515.Xr hash 3 , 516.Xr mpool 3 , 517.Xr recno 3 518.Pp 519.Rs 520.%T LIBTP: Portable, Modular Transactions for UNIX 521.%A Margo Seltzer 522.%A Michael Olson 523.%I USENIX Association 524.%B Proceedings of the 1992 Winter USENIX Technical Conference 525.%D 1992 526.%P 9-25 527.Re 528.Sh BUGS 529The typedef DBT is a mnemonic for 530.Dq data base thang , 531and was used because no one could think of a reasonable name that 532wasn't already used. 533.Pp 534The file descriptor interface is a kludge and will be deleted in a 535future version of the interface. 536.Pp 537None of the access methods provide any form of concurrent access, 538locking, or transactions. 539