xref: /minix3/lib/libc/db/man/dbopen.3 (revision 2fe8fb192fe7e8720e3e7a77f928da545e872a6a)
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