1.\" Copyright (c) 1990, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)dbopen.3 8.5 (Berkeley) 1/2/94 33.\" $FreeBSD$ 34.\" 35.Dd January 2, 1994 36.Dt DBOPEN 3 37.Os 38.Sh NAME 39.Nm dbopen 40.Nd "database access methods" 41.Sh SYNOPSIS 42.In sys/types.h 43.In db.h 44.In fcntl.h 45.In limits.h 46.Ft DB * 47.Fn dbopen "const char *file" "int flags" "int mode" "DBTYPE type" "const void *openinfo" 48.Sh DESCRIPTION 49.Fn Dbopen 50is the library interface to database files. 51The supported file formats are btree, hashed and UNIX file oriented. 52The btree format is a representation of a sorted, balanced tree structure. 53The hashed format is an extensible, dynamic hashing scheme. 54The flat-file format is a byte stream file with fixed or variable length 55records. 56The formats and file format specific information are described in detail 57in their respective manual pages 58.Xr btree 3 , 59.Xr hash 3 60and 61.Xr recno 3 . 62.Pp 63.Fn Dbopen 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 76are as specified to the 77.Xr open 2 78routine, however, only the 79.Dv O_CREAT , O_EXCL , O_EXLOCK , O_NONBLOCK , 80.Dv O_RDONLY , O_RDWR , O_SHLOCK 81and 82.Dv O_TRUNC 83flags are meaningful. 84(Note, opening a database file 85.Dv O_WRONLY 86is not possible.) 87.\"Three additional options may be specified by 88.\".Em or Ns 'ing 89.\"them into the 90.\".Fa flags 91.\"argument. 92.\".Bl -tag -width indent 93.\".It Dv DB_LOCK 94.\"Do the necessary locking in the database to support concurrent access. 95.\"If concurrent access isn't needed or the database is read-only this 96.\"flag should not be set, as it tends to have an associated performance 97.\"penalty. 98.\".It Dv DB_SHMEM 99.\"Place the underlying memory pool used by the database in shared 100.\"memory. 101.\"Necessary for concurrent access. 102.\".It Dv DB_TXN 103.\"Support transactions in the database. 104.\"The 105.\".Dv DB_LOCK 106.\"and 107.\".Dv DB_SHMEM 108.\"flags must be set as well. 109.\".El 110.Pp 111The 112.Fa type 113argument is of type 114.Ft DBTYPE 115(as defined in the 116.Aq Pa db.h 117include file) and 118may be set to 119.Dv DB_BTREE , DB_HASH 120or 121.Dv DB_RECNO . 122.Pp 123The 124.Fa openinfo 125argument is a pointer to an access method specific structure described 126in the access method's manual page. 127If 128.Fa openinfo 129is 130.Dv NULL , 131each access method will use defaults appropriate for the system 132and the access method. 133.Pp 134.Fn Dbopen 135returns a pointer to a 136.Ft DB 137structure on success and 138.Dv NULL 139on error. 140The 141.Ft DB 142structure is defined in the 143.Aq Pa db.h 144include file, and contains at 145least the following fields: 146.Bd -literal 147typedef struct { 148 DBTYPE type; 149 int (*close)(const DB *db); 150 int (*del)(const DB *db, const DBT *key, u_int flags); 151 int (*fd)(const DB *db); 152 int (*get)(const DB *db, DBT *key, DBT *data, u_int flags); 153 int (*put)(const DB *db, DBT *key, const DBT *data, 154 u_int flags); 155 int (*sync)(const DB *db, u_int flags); 156 int (*seq)(const DB *db, DBT *key, DBT *data, u_int flags); 157} DB; 158.Ed 159.Pp 160These elements describe a database type and a set of functions performing 161various actions. 162These functions take a pointer to a structure as returned by 163.Fn dbopen , 164and sometimes one or more pointers to key/data structures and a flag value. 165.Bl -tag -width indent 166.It Va type 167The type of the underlying access method (and file format). 168.It Va close 169A pointer to a routine to flush any cached information to disk, free any 170allocated resources, and close the underlying file(s). 171Since key/data pairs may be cached in memory, failing to sync the file 172with a 173.Va close 174or 175.Va sync 176function may result in inconsistent or lost information. 177.Va Close 178routines return -1 on error (setting 179.Va errno ) 180and 0 on success. 181.It Va del 182A pointer to a routine to remove key/data pairs from the database. 183.Pp 184The parameter 185.Fa flags 186may be set to the following value: 187.Bl -tag -width indent 188.It Dv R_CURSOR 189Delete the record referenced by the cursor. 190The cursor must have previously been initialized. 191.El 192.Pp 193.Va 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 Va 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.Fn dbopen 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.Va \&Fd 217routines return -1 on error (setting 218.Va errno ) , 219and the file descriptor on success. 220.It Va 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.Va 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 Va put 234A pointer to a routine to store key/data pairs in the database. 235.Pp 236The parameter 237.Fa flags 238may be set to one of the following values: 239.Bl -tag -width indent 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 exist. 265.It Dv R_SETCURSOR 266Store the key/data pair, setting or initializing the position of the 267cursor to reference it. 268(Applicable only to the 269.Dv DB_BTREE 270and 271.Dv DB_RECNO 272access methods.) 273.El 274.Pp 275.Dv R_SETCURSOR 276is available only for the 277.Dv DB_BTREE 278and 279.Dv DB_RECNO 280access 281methods 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 to 290create new keys. 291This is only true if the keys are ordered and independent, record numbers 292for example. 293.Pp 294The default behavior of the 295.Va put 296routines is to enter the new key/data pair, replacing any previously 297existing key. 298.Pp 299.Va Put 300routines return -1 on error (setting 301.Va errno ) , 3020 on success, and 1 if the 303.Dv R_NOOVERWRITE 304flag 305was set and the key already exists in the file. 306.It Va 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 314by 315.Fa data . 316.Pp 317Sequential key/data pair retrieval may begin at any time, and the 318position of the 319.Dq cursor 320is not affected by calls to the 321.Va del , 322.Va get , 323.Va put , 324or 325.Va sync 326routines. 327Modifications to the database during a sequential scan will be reflected 328in the scan, i.e. records inserted behind the cursor will not be returned 329while records inserted in front of the cursor will be returned. 330.Pp 331The 332.Fa flags 333value 334.Em must 335be set to one of the following values: 336.Bl -tag -width indent 337.It Dv R_CURSOR 338The data associated with the specified key is returned. 339This differs from the 340.Va 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 346exact match for the specified key. 347The returned key is the smallest key greater than or equal to the specified 348key, 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.Va 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 395is a character special file and no complete key/data pairs are currently 396available, the 397.Va seq 398routines return 2. 399.It Va sync 400A pointer to a routine to flush any cached information to disk. 401If the database is in memory only, the 402.Va sync 403routine has no effect and will always succeed. 404.Pp 405The 406.Fa flags 407value may be set to the following value: 408.Bl -tag -width indent 409.It Dv R_RECNOSYNC 410If the 411.Dv DB_RECNO 412access method is being used, this flag causes 413the 414.Va sync 415routine to apply to the btree file which underlies the 416recno file, not the recno file itself. 417(See the 418.Va bfname 419field of the 420.Xr recno 3 421manual page for more information.) 422.El 423.Pp 424.Va Sync 425routines return -1 on error (setting 426.Va errno ) 427and 0 on success. 428.El 429.Sh "KEY/DATA PAIRS" 430Access to all file types is based on key/data pairs. 431Both keys and data are represented by the following data structure: 432.Bd -literal 433typedef struct { 434 void *data; 435 size_t size; 436} DBT; 437.Ed 438.Pp 439The elements of the 440.Ft DBT 441structure are defined as follows: 442.Bl -tag -width "data" 443.It Va data 444A pointer to a byte string. 445.It Va size 446The length of the byte string. 447.El 448.Pp 449Key and data byte strings may reference strings of essentially unlimited 450length although any two of them must fit into available memory at the same 451time. 452It should be noted that the access methods provide no guarantees about 453byte string alignment. 454.Sh ERRORS 455The 456.Fn dbopen 457routine may fail and set 458.Va errno 459for any of the errors specified for the library routines 460.Xr open 2 461and 462.Xr malloc 3 463or the following: 464.Bl -tag -width Er 465.It Bq Er EFTYPE 466A file is incorrectly formatted. 467.It Bq Er EINVAL 468A parameter has been specified (hash function, pad byte etc.) that is 469incompatible with the current file specification or which is not 470meaningful for the function (for example, use of the cursor without 471prior initialization) or there is a mismatch between the version 472number of file and the software. 473.El 474.Pp 475The 476.Va close 477routines may fail and set 478.Va errno 479for any of the errors specified for the library routines 480.Xr close 2 , 481.Xr read 2 , 482.Xr write 2 , 483.Xr free 3 , 484or 485.Xr fsync 2 . 486.Pp 487The 488.Va del , 489.Va get , 490.Va put 491and 492.Va seq 493routines may fail and set 494.Va errno 495for any of the errors specified for the library routines 496.Xr read 2 , 497.Xr write 2 , 498.Xr free 3 499or 500.Xr malloc 3 . 501.Pp 502The 503.Va fd 504routines will fail and set 505.Va errno 506to 507.Er ENOENT 508for in memory databases. 509.Pp 510The 511.Va sync 512routines may fail and set 513.Va errno 514for any of the errors specified for the library routine 515.Xr fsync 2 . 516.Sh SEE ALSO 517.Xr btree 3 , 518.Xr hash 3 , 519.Xr mpool 3 , 520.Xr recno 3 521.Rs 522.%T "LIBTP: Portable, Modular Transactions for UNIX" 523.%A Margo Seltzer 524.%A Michael Olson 525.%R "USENIX proceedings" 526.%D Winter 1992 527.Re 528.Sh BUGS 529The typedef 530.Ft DBT 531is a mnemonic for 532.Dq "data base thang" , 533and was used 534because noone could think of a reasonable name that wasn't already used. 535.Pp 536The file descriptor interface is a kluge and will be deleted in a 537future version of the interface. 538.Pp 539None of the access methods provide any form of concurrent access, 540locking, or transactions. 541