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