1*2fe8fb19SBen Gras.\" $NetBSD: dbopen.3,v 1.19 2010/12/16 12:08:16 jruoho Exp $ 22639ae9bSBen Gras.\" 32639ae9bSBen Gras.\" Copyright (c) 1990, 1993 42639ae9bSBen Gras.\" The Regents of the University of California. All rights reserved. 52639ae9bSBen Gras.\" 62639ae9bSBen Gras.\" Redistribution and use in source and binary forms, with or without 72639ae9bSBen Gras.\" modification, are permitted provided that the following conditions 82639ae9bSBen Gras.\" are met: 92639ae9bSBen Gras.\" 1. Redistributions of source code must retain the above copyright 102639ae9bSBen Gras.\" notice, this list of conditions and the following disclaimer. 112639ae9bSBen Gras.\" 2. Redistributions in binary form must reproduce the above copyright 122639ae9bSBen Gras.\" notice, this list of conditions and the following disclaimer in the 132639ae9bSBen Gras.\" documentation and/or other materials provided with the distribution. 142639ae9bSBen Gras.\" 3. Neither the name of the University nor the names of its contributors 152639ae9bSBen Gras.\" may be used to endorse or promote products derived from this software 162639ae9bSBen Gras.\" without specific prior written permission. 172639ae9bSBen Gras.\" 182639ae9bSBen Gras.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 192639ae9bSBen Gras.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 202639ae9bSBen Gras.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 212639ae9bSBen Gras.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 222639ae9bSBen Gras.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 232639ae9bSBen Gras.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 242639ae9bSBen Gras.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 252639ae9bSBen Gras.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 262639ae9bSBen Gras.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 272639ae9bSBen Gras.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 282639ae9bSBen Gras.\" SUCH DAMAGE. 292639ae9bSBen Gras.\" 302639ae9bSBen Gras.\" @(#)dbopen.3 8.5 (Berkeley) 1/2/94 312639ae9bSBen Gras.\" 32*2fe8fb19SBen Gras.Dd December 16, 2010 332639ae9bSBen Gras.Dt DBOPEN 3 342639ae9bSBen Gras.Os 352639ae9bSBen Gras.Sh NAME 362639ae9bSBen Gras.Nm dbopen , 372639ae9bSBen Gras.Nm db 382639ae9bSBen Gras.Nd database access methods 392639ae9bSBen Gras.Sh SYNOPSIS 402639ae9bSBen Gras.In sys/types.h 412639ae9bSBen Gras.In limits.h 422639ae9bSBen Gras.In db.h 432639ae9bSBen Gras.In fcntl.h 442639ae9bSBen Gras.Ft DB * 452639ae9bSBen Gras.Fn dbopen "const char *file" "int flags" "mode_t mode" \ 462639ae9bSBen Gras"DBTYPE type" "const void *openinfo" 472639ae9bSBen Gras.Sh DESCRIPTION 482639ae9bSBen Gras.Nm 492639ae9bSBen Grasis the library interface to database files. 502639ae9bSBen GrasThe supported file formats are btree, hashed, and UNIX file oriented. 512639ae9bSBen GrasThe btree format is a representation of a sorted, balanced tree 522639ae9bSBen Grasstructure. 532639ae9bSBen GrasThe hashed format is an extensible, dynamic hashing scheme. 542639ae9bSBen GrasThe flat-file format is a byte stream file with fixed or variable 552639ae9bSBen Graslength records. 562639ae9bSBen GrasThe formats and file format specific information are described in 572639ae9bSBen Grasdetail in their respective manual pages 582639ae9bSBen Gras.Xr btree 3 , 592639ae9bSBen Gras.Xr hash 3 , 602639ae9bSBen Grasand 612639ae9bSBen Gras.Xr recno 3 . 622639ae9bSBen Gras.Pp 63*2fe8fb19SBen GrasThe 64*2fe8fb19SBen Gras.Fn dbopen 65*2fe8fb19SBen Grasfunction opens 662639ae9bSBen Gras.Fa file 672639ae9bSBen Grasfor reading and/or writing. 682639ae9bSBen GrasFiles never intended to be preserved on disk may be created by setting 692639ae9bSBen Grasthe file parameter to 702639ae9bSBen Gras.Dv NULL . 712639ae9bSBen Gras.Pp 722639ae9bSBen GrasThe 732639ae9bSBen Gras.Fa flags 742639ae9bSBen Grasand 752639ae9bSBen Gras.Fa mode 762639ae9bSBen Grasarguments are as specified to the 772639ae9bSBen Gras.Xr open 2 782639ae9bSBen Grasroutine, however, only the 792639ae9bSBen Gras.Dv O_CREAT , 802639ae9bSBen Gras.Dv O_EXCL , 812639ae9bSBen Gras.Dv O_EXLOCK , 822639ae9bSBen Gras.Dv O_NONBLOCK , 832639ae9bSBen Gras.Dv O_RDONLY , 842639ae9bSBen Gras.Dv O_RDWR , 852639ae9bSBen Gras.Dv O_SHLOCK , 862639ae9bSBen Grasand 872639ae9bSBen Gras.Dv O_TRUNC 882639ae9bSBen Grasflags are meaningful. 892639ae9bSBen Gras(Note, opening a database file 902639ae9bSBen Gras.Dv O_WRONLY 912639ae9bSBen Grasis not possible.) 922639ae9bSBen Gras.\"Three additional options may be specified by or'ing 932639ae9bSBen Gras.\"them into the 942639ae9bSBen Gras.\".Fa flags 952639ae9bSBen Gras.\"argument. 962639ae9bSBen Gras.\".Pp 972639ae9bSBen Gras.\".Dv DB_LOCK 982639ae9bSBen Gras.\"Do the necessary locking in the database to support concurrent access. 992639ae9bSBen Gras.\"If concurrent access isn't needed or the database is read-only this 1002639ae9bSBen Gras.\"flag should not be set, as it tends to have an associated performance 1012639ae9bSBen Gras.\"penalty. 1022639ae9bSBen Gras.\".Pp 1032639ae9bSBen Gras.\".Dv DB_SHMEM 1042639ae9bSBen Gras.\"Place the underlying memory pool used by the database in shared 1052639ae9bSBen Gras.\"memory. 1062639ae9bSBen Gras.\"Necessary for concurrent access. 1072639ae9bSBen Gras.\".Pp 1082639ae9bSBen Gras.\".Dv DB_TXN 1092639ae9bSBen Gras.\"Support transactions in the database. 1102639ae9bSBen Gras.\"The 1112639ae9bSBen Gras.\".Dv DB_LOCK 1122639ae9bSBen Gras.\"and 1132639ae9bSBen Gras.\".Dv DB_SHMEM 1142639ae9bSBen Gras.\"flags must be set as well. 1152639ae9bSBen Gras.Pp 1162639ae9bSBen GrasThe 1172639ae9bSBen Gras.Fa type 1182639ae9bSBen Grasargument is of type 1192639ae9bSBen Gras.Vt DBTYPE 1202639ae9bSBen Gras(as defined in the 1212639ae9bSBen Gras.In db.h 1222639ae9bSBen Grasinclude file) and may be set to 1232639ae9bSBen Gras.Dv DB_BTREE , 1242639ae9bSBen Gras.Dv DB_HASH , 1252639ae9bSBen Grasor 1262639ae9bSBen Gras.Dv DB_RECNO . 1272639ae9bSBen Gras.Pp 1282639ae9bSBen GrasThe 1292639ae9bSBen Gras.Fa openinfo 1302639ae9bSBen Grasargument is a pointer to an access method specific structure described 1312639ae9bSBen Grasin the access method's manual page. 1322639ae9bSBen GrasIf 1332639ae9bSBen Gras.Fa openinfo 1342639ae9bSBen Grasis 1352639ae9bSBen Gras.Dv NULL , 1362639ae9bSBen Graseach access method will use defaults appropriate for the system and 1372639ae9bSBen Grasthe access method. 138*2fe8fb19SBen Gras.Ss The DB Structure 139*2fe8fb19SBen GrasThe 140*2fe8fb19SBen Gras.Fn dbopen 141*2fe8fb19SBen Grasfunction returns a pointer to a DB structure on success and 1422639ae9bSBen Gras.Dv NULL 1432639ae9bSBen Grason error. 1442639ae9bSBen GrasThe DB structure is defined in the 1452639ae9bSBen Gras.In db.h 1462639ae9bSBen Grasinclude file, and contains at least the following fields: 147*2fe8fb19SBen Gras.Bd -literal -offset indent 1482639ae9bSBen Grastypedef struct { 1492639ae9bSBen Gras DBTYPE type; 1502639ae9bSBen Gras int (*close)(const DB *db); 1512639ae9bSBen Gras int (*del)(const DB *db, const DBT *key, u_int flags); 1522639ae9bSBen Gras int (*fd)(const DB *db); 1532639ae9bSBen Gras int (*get)(const DB *db, DBT *key, DBT *data, u_int flags); 1542639ae9bSBen Gras int (*put)(const DB *db, DBT *key, const DBT *data, 1552639ae9bSBen Gras u_int flags); 1562639ae9bSBen Gras int (*sync)(const DB *db, u_int flags); 1572639ae9bSBen Gras int (*seq)(const DB *db, DBT *key, DBT *data, u_int flags); 1582639ae9bSBen Gras} DB; 1592639ae9bSBen Gras.Ed 1602639ae9bSBen Gras.Pp 1612639ae9bSBen GrasThese elements describe a database type and a set of functions 1622639ae9bSBen Grasperforming various actions. 1632639ae9bSBen GrasThese functions take a pointer to a structure as returned by 1642639ae9bSBen Gras.Nm , 1652639ae9bSBen Grasand sometimes one or more pointers to key/data structures and a flag 1662639ae9bSBen Grasvalue. 167*2fe8fb19SBen Gras.Bl -tag -width closex -offset indent 1682639ae9bSBen Gras.It Fa type 1692639ae9bSBen GrasThe type of the underlying access method (and file format). 1702639ae9bSBen Gras.It Fa close 1712639ae9bSBen GrasA pointer to a routine to flush any cached information to disk, free 1722639ae9bSBen Grasany allocated resources, and close the underlying file(s). 1732639ae9bSBen GrasSince key/data pairs may be cached in memory, failing to sync the file 1742639ae9bSBen Graswith a 1752639ae9bSBen Gras.Fa close 1762639ae9bSBen Grasor 1772639ae9bSBen Gras.Fa sync 1782639ae9bSBen Grasfunction may result in inconsistent or lost information. 1792639ae9bSBen Gras.Fa close 1802639ae9bSBen Grasroutines return \-1 on error (setting 1812639ae9bSBen Gras.Va errno ) 1822639ae9bSBen Grasand 0 on success. 1832639ae9bSBen Gras.It Fa del 1842639ae9bSBen GrasA pointer to a routine to remove key/data pairs from the database. 1852639ae9bSBen Gras.Pp 1862639ae9bSBen GrasThe parameter 1872639ae9bSBen Gras.Fa flag 1882639ae9bSBen Grasmay be set to the following value: 1892639ae9bSBen Gras.Bl -tag -width R_CURSORX 1902639ae9bSBen Gras.It Dv R_CURSOR 1912639ae9bSBen GrasDelete the record referenced by the cursor. 1922639ae9bSBen GrasThe cursor must have previously been initialized. 1932639ae9bSBen Gras.El 1942639ae9bSBen Gras.Pp 1952639ae9bSBen Gras.Fa delete 1962639ae9bSBen Grasroutines return \-1 on error (setting 1972639ae9bSBen Gras.Va errno ) , 1982639ae9bSBen Gras0 on success, and 1 if the specified 1992639ae9bSBen Gras.Fa key 2002639ae9bSBen Graswas not in the file. 2012639ae9bSBen Gras.It Fa fd 2022639ae9bSBen GrasA pointer to a routine which returns a file descriptor representative 2032639ae9bSBen Grasof the underlying database. 2042639ae9bSBen GrasA file descriptor referencing the same file will be returned to all 2052639ae9bSBen Grasprocesses which call 2062639ae9bSBen Gras.Nm 2072639ae9bSBen Graswith the same 2082639ae9bSBen Gras.Fa file 2092639ae9bSBen Grasname. 2102639ae9bSBen GrasThis file descriptor may be safely used as an argument to the 2112639ae9bSBen Gras.Xr fcntl 2 2122639ae9bSBen Grasand 2132639ae9bSBen Gras.Xr flock 2 2142639ae9bSBen Graslocking functions. 2152639ae9bSBen GrasThe file descriptor is not necessarily associated with any of the 2162639ae9bSBen Grasunderlying files used by the access method. 2172639ae9bSBen GrasNo file descriptor is available for in memory databases. 2182639ae9bSBen Gras.Fa fd 2192639ae9bSBen Grasroutines return \-1 on error (setting 2202639ae9bSBen Gras.Va errno ) , 2212639ae9bSBen Grasand the file descriptor on success. 2222639ae9bSBen Gras.It Fa get 2232639ae9bSBen GrasA pointer to a routine which is the interface for keyed retrieval from 2242639ae9bSBen Grasthe database. 2252639ae9bSBen GrasThe address and length of the data associated with the specified 2262639ae9bSBen Gras.Fa key 2272639ae9bSBen Grasare returned in the structure referenced by 2282639ae9bSBen Gras.Fa data . 2292639ae9bSBen Gras.Fa get 2302639ae9bSBen Grasroutines return \-1 on error (setting 2312639ae9bSBen Gras.Va errno ) , 2322639ae9bSBen Gras0 on success, and 1 if the 2332639ae9bSBen Gras.Fa key 2342639ae9bSBen Graswas not in the file. 2352639ae9bSBen Gras.It Fa put 2362639ae9bSBen GrasA pointer to a routine to store key/data pairs in the database. 2372639ae9bSBen Gras.Pp 2382639ae9bSBen GrasThe parameter 2392639ae9bSBen Gras.Fa flag 2402639ae9bSBen Grasmay be set to one of the following values: 2412639ae9bSBen Gras.Bl -tag -width R_NOOVERWRITEX 2422639ae9bSBen Gras.It Dv R_CURSOR 2432639ae9bSBen GrasReplace the key/data pair referenced by the cursor. 2442639ae9bSBen GrasThe cursor must have previously been initialized. 2452639ae9bSBen Gras.It Dv R_IAFTER 2462639ae9bSBen GrasAppend the data immediately after the data referenced by 2472639ae9bSBen Gras.Fa key , 2482639ae9bSBen Grascreating a new key/data pair. 2492639ae9bSBen GrasThe record number of the appended key/data pair is returned in the 2502639ae9bSBen Gras.Fa key 2512639ae9bSBen Grasstructure. 2522639ae9bSBen Gras(Applicable only to the 2532639ae9bSBen Gras.Dv DB_RECNO 2542639ae9bSBen Grasaccess method.) 2552639ae9bSBen Gras.It Dv R_IBEFORE 2562639ae9bSBen GrasInsert the data immediately before the data referenced by 2572639ae9bSBen Gras.Fa key , 2582639ae9bSBen Grascreating a new key/data pair. 2592639ae9bSBen GrasThe record number of the inserted key/data pair is returned in the 2602639ae9bSBen Gras.Fa key 2612639ae9bSBen Grasstructure. 2622639ae9bSBen Gras(Applicable only to the 2632639ae9bSBen Gras.Dv DB_RECNO 2642639ae9bSBen Grasaccess method.) 2652639ae9bSBen Gras.It Dv R_NOOVERWRITE 2662639ae9bSBen GrasEnter the new key/data pair only if the key does not previously 2672639ae9bSBen Grasexist. 2682639ae9bSBen Gras.It Dv R_SETCURSOR 2692639ae9bSBen GrasStore the key/data pair, setting or initializing the position of the 2702639ae9bSBen Grascursor to reference it. 2712639ae9bSBen Gras(Applicable only to the 2722639ae9bSBen Gras.Dv DB_BTREE 2732639ae9bSBen Grasand 2742639ae9bSBen Gras.Dv DB_RECNO 2752639ae9bSBen Grasaccess methods.) 2762639ae9bSBen Gras.El 2772639ae9bSBen Gras.Pp 2782639ae9bSBen Gras.Dv R_SETCURSOR 2792639ae9bSBen Grasis available only for the 2802639ae9bSBen Gras.Dv DB_BTREE 2812639ae9bSBen Grasand 2822639ae9bSBen Gras.Dv DB_RECNO 2832639ae9bSBen Grasaccess methods because it implies that the keys have an inherent order 2842639ae9bSBen Graswhich does not change. 2852639ae9bSBen Gras.Pp 2862639ae9bSBen Gras.Dv R_IAFTER 2872639ae9bSBen Grasand 2882639ae9bSBen Gras.Dv R_IBEFORE 2892639ae9bSBen Grasare available only for the 2902639ae9bSBen Gras.Dv DB_RECNO 2912639ae9bSBen Grasaccess method because they each imply that the access method is able 2922639ae9bSBen Grasto create new keys. 2932639ae9bSBen GrasThis is only true if the keys are ordered and independent, record 2942639ae9bSBen Grasnumbers for example. 2952639ae9bSBen Gras.Pp 2962639ae9bSBen GrasThe default behavior of the 2972639ae9bSBen Gras.Fa put 2982639ae9bSBen Grasroutines is to enter the new key/data pair, replacing any previously 2992639ae9bSBen Grasexisting key. 3002639ae9bSBen Gras.Pp 3012639ae9bSBen Gras.Fa put 3022639ae9bSBen Grasroutines return \-1 on error (setting 3032639ae9bSBen Gras.Va errno ) , 3042639ae9bSBen Gras0 on success, and 1 if the 3052639ae9bSBen Gras.Dv R_NOOVERWRITE 3062639ae9bSBen Gras.Fa flag 3072639ae9bSBen Graswas set and the key already exists in the file. 3082639ae9bSBen Gras.It Fa seq 3092639ae9bSBen GrasA pointer to a routine which is the interface for sequential 3102639ae9bSBen Grasretrieval from the database. 3112639ae9bSBen GrasThe address and length of the key are returned in the structure 3122639ae9bSBen Grasreferenced by 3132639ae9bSBen Gras.Fa key , 3142639ae9bSBen Grasand the address and length of the data are returned in the 3152639ae9bSBen Grasstructure referenced by 3162639ae9bSBen Gras.Fa data . 3172639ae9bSBen Gras.Pp 3182639ae9bSBen GrasSequential key/data pair retrieval may begin at any time, and the 3192639ae9bSBen Grasposition of the 3202639ae9bSBen Gras.Dq cursor 3212639ae9bSBen Grasis not affected by calls to the 3222639ae9bSBen Gras.Fa del , 3232639ae9bSBen Gras.Fa get , 3242639ae9bSBen Gras.Fa put , 3252639ae9bSBen Grasor 3262639ae9bSBen Gras.Fa sync 3272639ae9bSBen Grasroutines. 3282639ae9bSBen GrasModifications to the database during a sequential scan will be 3292639ae9bSBen Grasreflected in the scan, i.e., records inserted behind the cursor will 3302639ae9bSBen Grasnot be returned while records inserted in front of the cursor will be 3312639ae9bSBen Grasreturned. 3322639ae9bSBen Gras.Pp 3332639ae9bSBen GrasThe flag value 3342639ae9bSBen Gras.Em must 3352639ae9bSBen Grasbe set to one of the following values: 3362639ae9bSBen Gras.Bl -tag -width R_CURSORX 3372639ae9bSBen Gras.It Dv R_CURSOR 3382639ae9bSBen GrasThe data associated with the specified key is returned. 3392639ae9bSBen GrasThis differs from the 3402639ae9bSBen Gras.Fa get 3412639ae9bSBen Grasroutines in that it sets or initializes the cursor to the location of 3422639ae9bSBen Grasthe key as well. 3432639ae9bSBen Gras(Note, for the 3442639ae9bSBen Gras.Dv DB_BTREE 3452639ae9bSBen Grasaccess method, the returned key is not necessarily an exact match for 3462639ae9bSBen Grasthe specified key. 3472639ae9bSBen GrasThe returned key is the smallest key greater than or equal to the 3482639ae9bSBen Grasspecified key, permitting partial key matches and range searches.) 3492639ae9bSBen Gras.It Dv R_FIRST 3502639ae9bSBen GrasThe first key/data pair of the database is returned, and the cursor 3512639ae9bSBen Grasis set or initialized to reference it. 3522639ae9bSBen Gras.It Dv R_LAST 3532639ae9bSBen GrasThe last key/data pair of the database is returned, and the cursor 3542639ae9bSBen Grasis set or initialized to reference it. 3552639ae9bSBen Gras(Applicable only to the 3562639ae9bSBen Gras.Dv DB_BTREE 3572639ae9bSBen Grasand 3582639ae9bSBen Gras.Dv DB_RECNO 3592639ae9bSBen Grasaccess methods.) 3602639ae9bSBen Gras.It Dv R_NEXT 3612639ae9bSBen GrasRetrieve the key/data pair immediately after the cursor. 3622639ae9bSBen GrasIf the cursor is not yet set, this is the same as the 3632639ae9bSBen Gras.Dv R_FIRST 3642639ae9bSBen Grasflag. 3652639ae9bSBen Gras.It Dv R_PREV 3662639ae9bSBen GrasRetrieve the key/data pair immediately before the cursor. 3672639ae9bSBen GrasIf the cursor is not yet set, this is the same as the 3682639ae9bSBen Gras.Dv R_LAST 3692639ae9bSBen Grasflag. 3702639ae9bSBen Gras(Applicable only to the 3712639ae9bSBen Gras.Dv DB_BTREE 3722639ae9bSBen Grasand 3732639ae9bSBen Gras.Dv DB_RECNO 3742639ae9bSBen Grasaccess methods.) 3752639ae9bSBen Gras.El 3762639ae9bSBen Gras.Pp 3772639ae9bSBen Gras.Dv R_LAST 3782639ae9bSBen Grasand 3792639ae9bSBen Gras.Dv R_PREV 3802639ae9bSBen Grasare available only for the 3812639ae9bSBen Gras.Dv DB_BTREE 3822639ae9bSBen Grasand 3832639ae9bSBen Gras.Dv DB_RECNO 3842639ae9bSBen Grasaccess methods because they each imply that the keys have an inherent 3852639ae9bSBen Grasorder which does not change. 3862639ae9bSBen Gras.Pp 3872639ae9bSBen Gras.Fa seq 3882639ae9bSBen Grasroutines return \-1 on error (setting 3892639ae9bSBen Gras.Va errno ) , 3902639ae9bSBen Gras0 on success and 1 if there are no key/data pairs less than or greater 3912639ae9bSBen Grasthan the specified or current key. 3922639ae9bSBen GrasIf the 3932639ae9bSBen Gras.Dv DB_RECNO 3942639ae9bSBen Grasaccess method is being used, and if the database file is a character 3952639ae9bSBen Grasspecial file and no complete key/data pairs are currently available, 3962639ae9bSBen Grasthe 3972639ae9bSBen Gras.Fa seq 3982639ae9bSBen Grasroutines return 2. 3992639ae9bSBen Gras.It Fa sync 4002639ae9bSBen GrasA pointer to a routine to flush any cached information to disk. 4012639ae9bSBen GrasIf the database is in memory only, the 4022639ae9bSBen Gras.Fa sync 4032639ae9bSBen Grasroutine has no effect and will always succeed. 4042639ae9bSBen Gras.Pp 4052639ae9bSBen GrasThe flag value may be set to the following value: 4062639ae9bSBen Gras.Bl -tag -width ".Dv R_RECNOSYNC" 4072639ae9bSBen Gras.It Dv R_RECNOSYNC 4082639ae9bSBen GrasIf the 4092639ae9bSBen Gras.Dv DB_RECNO 4102639ae9bSBen Grasaccess method is being used, this flag causes the sync routine to 4112639ae9bSBen Grasapply to the btree file which underlies the recno file, not the recno 4122639ae9bSBen Grasfile itself. 4132639ae9bSBen Gras(See the 4142639ae9bSBen Gras.Fa bfname 4152639ae9bSBen Grasfield of the 4162639ae9bSBen Gras.Xr recno 3 4172639ae9bSBen Grasmanual page for more information.) 4182639ae9bSBen Gras.El 4192639ae9bSBen Gras.Pp 4202639ae9bSBen Gras.Fa sync 4212639ae9bSBen Grasroutines return \-1 on error (setting 4222639ae9bSBen Gras.Va errno ) 4232639ae9bSBen Grasand 0 on success. 4242639ae9bSBen Gras.El 425*2fe8fb19SBen Gras.Ss Key/data Pairs 4262639ae9bSBen GrasAccess to all file types is based on key/data pairs. 4272639ae9bSBen GrasBoth keys and data are represented by the following data structure: 428*2fe8fb19SBen Gras.Bd -literal -offset indent 4292639ae9bSBen Grastypedef struct { 4302639ae9bSBen Gras void *data; 4312639ae9bSBen Gras size_t size; 4322639ae9bSBen Gras} DBT; 4332639ae9bSBen Gras.Ed 4342639ae9bSBen Gras.Pp 4352639ae9bSBen GrasThe elements of the DBT structure are defined as follows: 436*2fe8fb19SBen Gras.Bl -tag -width datax -offset indent 4372639ae9bSBen Gras.It Fa data 4382639ae9bSBen GrasA pointer to a byte string. 4392639ae9bSBen Gras.It Fa size 4402639ae9bSBen GrasThe length of the byte string. 4412639ae9bSBen Gras.El 4422639ae9bSBen Gras.Pp 4432639ae9bSBen GrasKey and data byte strings may reference strings of essentially 4442639ae9bSBen Grasunlimited length although any two of them must fit into available 4452639ae9bSBen Grasmemory at the same time. 4462639ae9bSBen GrasIt should be noted that the access methods provide no guarantees about 4472639ae9bSBen Grasbyte string alignment. 4482639ae9bSBen Gras.Sh ERRORS 4492639ae9bSBen GrasThe 4502639ae9bSBen Gras.Nm 4512639ae9bSBen Grasroutine may fail and set 4522639ae9bSBen Gras.Va errno 4532639ae9bSBen Grasfor any of the errors specified for the library routines 4542639ae9bSBen Gras.Xr open 2 4552639ae9bSBen Grasand 4562639ae9bSBen Gras.Xr malloc 3 4572639ae9bSBen Grasor the following: 4582639ae9bSBen Gras.Bl -tag -width Er 4592639ae9bSBen Gras.It Er EFTYPE 4602639ae9bSBen GrasA file is incorrectly formatted. 4612639ae9bSBen Gras.It Er EINVAL 4622639ae9bSBen GrasA parameter has been specified (hash function, pad byte, etc.) that is 4632639ae9bSBen Grasincompatible with the current file specification or which is not 4642639ae9bSBen Grasmeaningful for the function (for example, use of the cursor without 4652639ae9bSBen Grasprior initialization) or there is a mismatch between the version 4662639ae9bSBen Grasnumber of file and the software. 4672639ae9bSBen Gras.It Er EFBIG 4682639ae9bSBen GrasThe key could not be inserted due to limitations in the DB file format 4692639ae9bSBen Gras(e.g., a hash database was out of overflow pages). 4702639ae9bSBen Gras.El 4712639ae9bSBen Gras.Pp 4722639ae9bSBen GrasThe 4732639ae9bSBen Gras.Fa close 4742639ae9bSBen Grasroutines may fail and set 4752639ae9bSBen Gras.Va errno 4762639ae9bSBen Grasfor any of the errors specified for the library routines 4772639ae9bSBen Gras.Xr close 2 , 4782639ae9bSBen Gras.Xr read 2 , 4792639ae9bSBen Gras.Xr write 2 , 4802639ae9bSBen Gras.Xr free 3 , 4812639ae9bSBen Grasor 4822639ae9bSBen Gras.Xr fsync 2 . 4832639ae9bSBen Gras.Pp 4842639ae9bSBen GrasThe 4852639ae9bSBen Gras.Fa del , 4862639ae9bSBen Gras.Fa get , 4872639ae9bSBen Gras.Fa put , 4882639ae9bSBen Grasand 4892639ae9bSBen Gras.Fa seq 4902639ae9bSBen Grasroutines may fail and set 4912639ae9bSBen Gras.Va errno 4922639ae9bSBen Grasfor any of the errors specified for the library routines 4932639ae9bSBen Gras.Xr read 2 , 4942639ae9bSBen Gras.Xr write 2 , 4952639ae9bSBen Gras.Xr free 3 , 4962639ae9bSBen Grasor 4972639ae9bSBen Gras.Xr malloc 3 . 4982639ae9bSBen Gras.Pp 4992639ae9bSBen GrasThe 5002639ae9bSBen Gras.Fa fd 5012639ae9bSBen Grasroutines will fail and set 5022639ae9bSBen Gras.Va errno 5032639ae9bSBen Grasto 5042639ae9bSBen Gras.Er ENOENT 5052639ae9bSBen Grasfor in memory databases. 5062639ae9bSBen Gras.Pp 5072639ae9bSBen GrasThe 5082639ae9bSBen Gras.Fa sync 5092639ae9bSBen Grasroutines may fail and set 5102639ae9bSBen Gras.Va errno 5112639ae9bSBen Grasfor any of the errors specified for the library routine 5122639ae9bSBen Gras.Xr fsync 2 . 5132639ae9bSBen Gras.Sh SEE ALSO 5142639ae9bSBen Gras.Xr btree 3 , 5152639ae9bSBen Gras.Xr hash 3 , 5162639ae9bSBen Gras.Xr mpool 3 , 5172639ae9bSBen Gras.Xr recno 3 5182639ae9bSBen Gras.Pp 5192639ae9bSBen Gras.Rs 520*2fe8fb19SBen Gras.%T LIBTP: Portable, Modular Transactions for UNIX 5212639ae9bSBen Gras.%A Margo Seltzer 5222639ae9bSBen Gras.%A Michael Olson 523*2fe8fb19SBen Gras.%I USENIX Association 524*2fe8fb19SBen Gras.%B Proceedings of the 1992 Winter USENIX Technical Conference 525*2fe8fb19SBen Gras.%D 1992 526*2fe8fb19SBen Gras.%P 9-25 5272639ae9bSBen Gras.Re 5282639ae9bSBen Gras.Sh BUGS 5292639ae9bSBen GrasThe typedef DBT is a mnemonic for 5302639ae9bSBen Gras.Dq data base thang , 5312639ae9bSBen Grasand was used because no one could think of a reasonable name that 5322639ae9bSBen Graswasn't already used. 5332639ae9bSBen Gras.Pp 5342639ae9bSBen GrasThe file descriptor interface is a kludge and will be deleted in a 5352639ae9bSBen Grasfuture version of the interface. 5362639ae9bSBen Gras.Pp 5372639ae9bSBen GrasNone of the access methods provide any form of concurrent access, 5382639ae9bSBen Graslocking, or transactions. 539