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