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