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