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