Convert to mdoc.
This commit is contained in:
wiz
parent
5b38542fe2
commit
6fa350b93d
@ -1,4 +1,4 @@
|
||||
.\" $NetBSD: dbopen.3,v 1.11 2002/02/07 07:00:10 ross Exp $
|
||||
.\" $NetBSD: dbopen.3,v 1.12 2003/04/17 18:48:28 wiz Exp $
|
||||
.\"
|
||||
.\" Copyright (c) 1990, 1993
|
||||
.\" The Regents of the University of California. All rights reserved.
|
||||
@ -33,451 +33,505 @@
|
||||
.\"
|
||||
.\" @(#)dbopen.3 8.5 (Berkeley) 1/2/94
|
||||
.\"
|
||||
.TH DBOPEN 3 "January 2, 1994"
|
||||
.UC 7
|
||||
.SH NAME
|
||||
dbopen, db \- database access methods
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
.ft B
|
||||
#include \*[Lt]sys/types.h\*[Gt]
|
||||
#include \*[Lt]limits.h\*[Gt]
|
||||
#include \*[Lt]db.h\*[Gt]
|
||||
#include \*[Lt]fcntl.h\*[Gt]
|
||||
|
||||
DB *
|
||||
dbopen(const char *file, int flags, mode_t mode, DBTYPE type,
|
||||
.ti +5
|
||||
const void *openinfo);
|
||||
.ft R
|
||||
.fi
|
||||
.SH DESCRIPTION
|
||||
.IR Dbopen
|
||||
.Dd April 17, 2003
|
||||
.Dt DBOPEN 3
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm dbopen ,
|
||||
.Nm db
|
||||
.Nd database access methods
|
||||
.Sh SYNOPSIS
|
||||
.In sys/types.h
|
||||
.In limits.h
|
||||
.In db.h
|
||||
.In fcntl.h
|
||||
.Ft DB *
|
||||
.Fn dbopen "const char *file" "int flags" "mode_t mode" \
|
||||
"DBTYPE type" "const void *openinfo"
|
||||
.Sh DESCRIPTION
|
||||
.Nm
|
||||
is the library interface to database files.
|
||||
The supported file formats are btree, hashed and UNIX file oriented.
|
||||
The btree format is a representation of a sorted, balanced tree structure.
|
||||
The supported file formats are btree, hashed, and UNIX file oriented.
|
||||
The btree format is a representation of a sorted, balanced tree
|
||||
structure.
|
||||
The hashed format is an extensible, dynamic hashing scheme.
|
||||
The flat-file format is a byte stream file with fixed or variable length
|
||||
records.
|
||||
The formats and file format specific information are described in detail
|
||||
in their respective manual pages
|
||||
.IR btree (3),
|
||||
.IR hash (3)
|
||||
The flat-file format is a byte stream file with fixed or variable
|
||||
length records.
|
||||
The formats and file format specific information are described in
|
||||
detail in their respective manual pages
|
||||
.Xr btree 3 ,
|
||||
.Xr hash 3 ,
|
||||
and
|
||||
.IR recno (3).
|
||||
.PP
|
||||
Dbopen opens
|
||||
.I file
|
||||
.Xr recno 3 .
|
||||
.Pp
|
||||
.Nm
|
||||
opens
|
||||
.Fa file
|
||||
for reading and/or writing.
|
||||
Files never intended to be preserved on disk may be created by setting
|
||||
the file parameter to NULL.
|
||||
.PP
|
||||
the file parameter to
|
||||
.Dv NULL .
|
||||
.Pp
|
||||
The
|
||||
.I flags
|
||||
.Fa flags
|
||||
and
|
||||
.I mode arguments
|
||||
are as specified to the
|
||||
.IR open (2)
|
||||
routine, however, only the O_CREAT, O_EXCL, O_EXLOCK, O_NONBLOCK,
|
||||
O_RDONLY, O_RDWR, O_SHLOCK and O_TRUNC flags are meaningful.
|
||||
(Note, opening a database file O_WRONLY is not possible.)
|
||||
.\"Three additional options may be specified by
|
||||
.\".IR or 'ing
|
||||
.Fa mode
|
||||
arguments are as specified to the
|
||||
.Xr open 2
|
||||
routine, however, only the
|
||||
.Dv O_CREAT ,
|
||||
.Dv O_EXCL ,
|
||||
.Dv O_EXLOCK ,
|
||||
.Dv O_NONBLOCK ,
|
||||
.Dv O_RDONLY ,
|
||||
.Dv O_RDWR ,
|
||||
.Dv O_SHLOCK ,
|
||||
and
|
||||
.Dv O_TRUNC
|
||||
flags are meaningful.
|
||||
(Note, opening a database file
|
||||
.Dv O_WRONLY
|
||||
is not possible.)
|
||||
.\"Three additional options may be specified by or'ing
|
||||
.\"them into the
|
||||
.\".I flags
|
||||
.\".Fa flags
|
||||
.\"argument.
|
||||
.\".TP
|
||||
.\"DB_LOCK
|
||||
.\".Pp
|
||||
.\".Dv DB_LOCK
|
||||
.\"Do the necessary locking in the database to support concurrent access.
|
||||
.\"If concurrent access isn't needed or the database is read-only this
|
||||
.\"flag should not be set, as it tends to have an associated performance
|
||||
.\"penalty.
|
||||
.\".TP
|
||||
.\"DB_SHMEM
|
||||
.\".Pp
|
||||
.\".Dv DB_SHMEM
|
||||
.\"Place the underlying memory pool used by the database in shared
|
||||
.\"memory.
|
||||
.\"Necessary for concurrent access.
|
||||
.\".TP
|
||||
.\"DB_TXN
|
||||
.\".Pp
|
||||
.\".Dv DB_TXN
|
||||
.\"Support transactions in the database.
|
||||
.\"The DB_LOCK and DB_SHMEM flags must be set as well.
|
||||
.PP
|
||||
.\"The
|
||||
.\".Dv DB_LOCK
|
||||
.\"and
|
||||
.\".Dv DB_SHMEM
|
||||
.\"flags must be set as well.
|
||||
.Pp
|
||||
The
|
||||
.I type
|
||||
argument is of type DBTYPE (as defined in the \*[Lt]db.h\*[Gt] include file) and
|
||||
may be set to DB_BTREE, DB_HASH or DB_RECNO.
|
||||
.PP
|
||||
.Fa type
|
||||
argument is of type
|
||||
.Vt DBTYPE
|
||||
(as defined in the
|
||||
.Aq Pa db.h
|
||||
include file) and may be set to
|
||||
.Dv DB_BTREE ,
|
||||
.Dv DB_HASH ,
|
||||
or
|
||||
.Dv DB_RECNO .
|
||||
.Pp
|
||||
The
|
||||
.I openinfo
|
||||
.Fa openinfo
|
||||
argument is a pointer to an access method specific structure described
|
||||
in the access method's manual page.
|
||||
If
|
||||
.I openinfo
|
||||
is NULL, each access method will use defaults appropriate for the system
|
||||
and the access method.
|
||||
.PP
|
||||
.I Dbopen
|
||||
returns a pointer to a DB structure on success and NULL on error.
|
||||
The DB structure is defined in the \*[Lt]db.h\*[Gt] include file, and contains at
|
||||
least the following fields:
|
||||
.sp
|
||||
.nf
|
||||
.Fa openinfo
|
||||
is
|
||||
.Dv NULL ,
|
||||
each access method will use defaults appropriate for the system and
|
||||
the access method.
|
||||
.Pp
|
||||
.Nm
|
||||
returns a pointer to a DB structure on success and
|
||||
.Dv NULL
|
||||
on error.
|
||||
The DB structure is defined in the
|
||||
.Aq Pa db.h
|
||||
include file, and contains at least the following fields:
|
||||
.Bd -literal
|
||||
typedef struct {
|
||||
.RS
|
||||
DBTYPE type;
|
||||
int (*close)(const DB *db);
|
||||
int (*del)(const DB *db, const DBT *key, u_int flags);
|
||||
int (*fd)(const DB *db);
|
||||
int (*get)(const DB *db, DBT *key, DBT *data, u_int flags);
|
||||
int (*put)(const DB *db, DBT *key, const DBT *data,
|
||||
.ti +5
|
||||
u_int flags);
|
||||
int (*sync)(const DB *db, u_int flags);
|
||||
int (*seq)(const DB *db, DBT *key, DBT *data, u_int flags);
|
||||
.RE
|
||||
DBTYPE type;
|
||||
int (*close)(const DB *db);
|
||||
int (*del)(const DB *db, const DBT *key, u_int flags);
|
||||
int (*fd)(const DB *db);
|
||||
int (*get)(const DB *db, DBT *key, DBT *data, u_int flags);
|
||||
int (*put)(const DB *db, DBT *key, const DBT *data,
|
||||
u_int flags);
|
||||
int (*sync)(const DB *db, u_int flags);
|
||||
int (*seq)(const DB *db, DBT *key, DBT *data, u_int flags);
|
||||
} DB;
|
||||
.fi
|
||||
.PP
|
||||
These elements describe a database type and a set of functions performing
|
||||
various actions.
|
||||
.Ed
|
||||
.Pp
|
||||
These elements describe a database type and a set of functions
|
||||
performing various actions.
|
||||
These functions take a pointer to a structure as returned by
|
||||
.IR dbopen ,
|
||||
and sometimes one or more pointers to key/data structures and a flag value.
|
||||
.TP
|
||||
type
|
||||
.Nm ,
|
||||
and sometimes one or more pointers to key/data structures and a flag
|
||||
value.
|
||||
.Bl -tag -width closex
|
||||
.It Fa type
|
||||
The type of the underlying access method (and file format).
|
||||
.TP
|
||||
close
|
||||
A pointer to a routine to flush any cached information to disk, free any
|
||||
allocated resources, and close the underlying file(s).
|
||||
.It Fa close
|
||||
A pointer to a routine to flush any cached information to disk, free
|
||||
any allocated resources, and close the underlying file(s).
|
||||
Since key/data pairs may be cached in memory, failing to sync the file
|
||||
with a
|
||||
.I close
|
||||
.Fa close
|
||||
or
|
||||
.I sync
|
||||
.Fa sync
|
||||
function may result in inconsistent or lost information.
|
||||
.I Close
|
||||
routines return -1 on error (setting
|
||||
.IR errno )
|
||||
.Fa close
|
||||
routines return \-1 on error (setting
|
||||
.Va errno )
|
||||
and 0 on success.
|
||||
.TP
|
||||
del
|
||||
.It Fa del
|
||||
A pointer to a routine to remove key/data pairs from the database.
|
||||
.IP
|
||||
.Pp
|
||||
The parameter
|
||||
.I flag
|
||||
.Fa flag
|
||||
may be set to the following value:
|
||||
.RS
|
||||
.TP
|
||||
R_CURSOR
|
||||
.Bl -tag -width R_CURSORX
|
||||
.It Dv R_CURSOR
|
||||
Delete the record referenced by the cursor.
|
||||
The cursor must have previously been initialized.
|
||||
.RE
|
||||
.IP
|
||||
.I Delete
|
||||
routines return -1 on error (setting
|
||||
.IR errno ),
|
||||
.El
|
||||
.Pp
|
||||
.Fa delete
|
||||
routines return \-1 on error (setting
|
||||
.Va errno ),
|
||||
0 on success, and 1 if the specified
|
||||
.I key
|
||||
.Fa key
|
||||
was not in the file.
|
||||
.TP
|
||||
fd
|
||||
.It Fa fd
|
||||
A pointer to a routine which returns a file descriptor representative
|
||||
of the underlying database.
|
||||
A file descriptor referencing the same file will be returned to all
|
||||
processes which call
|
||||
.I dbopen
|
||||
.Nm
|
||||
with the same
|
||||
.I file
|
||||
.Fa file
|
||||
name.
|
||||
This file descriptor may be safely used as an argument to the
|
||||
.IR fcntl (2)
|
||||
.Xr fcntl 2
|
||||
and
|
||||
.IR flock (2)
|
||||
.Xr flock 2
|
||||
locking functions.
|
||||
The file descriptor is not necessarily associated with any of the
|
||||
underlying files used by the access method.
|
||||
No file descriptor is available for in memory databases.
|
||||
.I Fd
|
||||
routines return -1 on error (setting
|
||||
.IR errno ),
|
||||
.Fa fd
|
||||
routines return \-1 on error (setting
|
||||
.Va errno ) ,
|
||||
and the file descriptor on success.
|
||||
.TP
|
||||
get
|
||||
.It Fa get
|
||||
A pointer to a routine which is the interface for keyed retrieval from
|
||||
the database.
|
||||
The address and length of the data associated with the specified
|
||||
.I key
|
||||
.Fa key
|
||||
are returned in the structure referenced by
|
||||
.IR data .
|
||||
.I Get
|
||||
routines return -1 on error (setting
|
||||
.IR errno ),
|
||||
.Fa data .
|
||||
.Fa get
|
||||
routines return \-1 on error (setting
|
||||
.Va errno ) ,
|
||||
0 on success, and 1 if the
|
||||
.I key
|
||||
.Fa key
|
||||
was not in the file.
|
||||
.TP
|
||||
put
|
||||
.It Fa put
|
||||
A pointer to a routine to store key/data pairs in the database.
|
||||
.IP
|
||||
.Pp
|
||||
The parameter
|
||||
.I flag
|
||||
.Fa flag
|
||||
may be set to one of the following values:
|
||||
.RS
|
||||
.TP
|
||||
R_CURSOR
|
||||
.Bl -tag -width R_NOOVERWRITEX
|
||||
.It Dv R_CURSOR
|
||||
Replace the key/data pair referenced by the cursor.
|
||||
The cursor must have previously been initialized.
|
||||
.TP
|
||||
R_IAFTER
|
||||
.It Dv R_IAFTER
|
||||
Append the data immediately after the data referenced by
|
||||
.IR key ,
|
||||
.Fa key ,
|
||||
creating a new key/data pair.
|
||||
The record number of the appended key/data pair is returned in the
|
||||
.I key
|
||||
.Fa key
|
||||
structure.
|
||||
(Applicable only to the DB_RECNO access method.)
|
||||
.TP
|
||||
R_IBEFORE
|
||||
(Applicable only to the
|
||||
.Dv DB_RECNO
|
||||
access method.)
|
||||
.It Dv R_IBEFORE
|
||||
Insert the data immediately before the data referenced by
|
||||
.IR key ,
|
||||
.Fa key ,
|
||||
creating a new key/data pair.
|
||||
The record number of the inserted key/data pair is returned in the
|
||||
.I key
|
||||
.Fa key
|
||||
structure.
|
||||
(Applicable only to the DB_RECNO access method.)
|
||||
.TP
|
||||
R_NOOVERWRITE
|
||||
Enter the new key/data pair only if the key does not previously exist.
|
||||
.TP
|
||||
R_SETCURSOR
|
||||
(Applicable only to the
|
||||
.Dv DB_RECNO
|
||||
access method.)
|
||||
.It Dv R_NOOVERWRITE
|
||||
Enter the new key/data pair only if the key does not previously
|
||||
exist.
|
||||
.It Dv R_SETCURSOR
|
||||
Store the key/data pair, setting or initializing the position of the
|
||||
cursor to reference it.
|
||||
(Applicable only to the DB_BTREE and DB_RECNO access methods.)
|
||||
.RE
|
||||
.IP
|
||||
R_SETCURSOR is available only for the DB_BTREE and DB_RECNO access
|
||||
methods because it implies that the keys have an inherent order
|
||||
(Applicable only to the
|
||||
.Dv DB_BTREE
|
||||
and
|
||||
.Dv DB_RECNO
|
||||
access methods.)
|
||||
.El
|
||||
.Pp
|
||||
.Dv R_SETCURSOR
|
||||
is available only for the
|
||||
.Dv DB_BTREE
|
||||
and
|
||||
.Dv DB_RECNO
|
||||
access methods because it implies that the keys have an inherent order
|
||||
which does not change.
|
||||
.IP
|
||||
R_IAFTER and R_IBEFORE are available only for the DB_RECNO
|
||||
access method because they each imply that the access method is able to
|
||||
create new keys.
|
||||
This is only true if the keys are ordered and independent, record numbers
|
||||
for example.
|
||||
.IP
|
||||
.Pp
|
||||
.Dv R_IAFTER
|
||||
and
|
||||
.Dv R_IBEFORE
|
||||
are available only for the
|
||||
.Dv DB_RECNO
|
||||
access method because they each imply that the access method is able
|
||||
to create new keys.
|
||||
This is only true if the keys are ordered and independent, record
|
||||
numbers for example.
|
||||
.Pp
|
||||
The default behavior of the
|
||||
.I put
|
||||
.Fa put
|
||||
routines is to enter the new key/data pair, replacing any previously
|
||||
existing key.
|
||||
.IP
|
||||
.I Put
|
||||
routines return -1 on error (setting
|
||||
.IR errno ),
|
||||
0 on success, and 1 if the R_NOOVERWRITE
|
||||
.I flag
|
||||
.Pp
|
||||
.Fa put
|
||||
routines return \-1 on error (setting
|
||||
.Va errno ) ,
|
||||
0 on success, and 1 if the
|
||||
.Dv R_NOOVERWRITE
|
||||
.Fa flag
|
||||
was set and the key already exists in the file.
|
||||
.TP
|
||||
seq
|
||||
.It Fa seq
|
||||
A pointer to a routine which is the interface for sequential
|
||||
retrieval from the database.
|
||||
The address and length of the key are returned in the structure
|
||||
referenced by
|
||||
.IR key ,
|
||||
.Fa key ,
|
||||
and the address and length of the data are returned in the
|
||||
structure referenced
|
||||
by
|
||||
.IR data .
|
||||
.IP
|
||||
structure referenced by
|
||||
.Fa data .
|
||||
.Pp
|
||||
Sequential key/data pair retrieval may begin at any time, and the
|
||||
position of the ``cursor'' is not affected by calls to the
|
||||
.IR del ,
|
||||
.IR get ,
|
||||
.IR put ,
|
||||
position of the
|
||||
.Dq cursor
|
||||
is not affected by calls to the
|
||||
.Fa del ,
|
||||
.Fa get ,
|
||||
.Fa put ,
|
||||
or
|
||||
.I sync
|
||||
.Fa sync
|
||||
routines.
|
||||
Modifications to the database during a sequential scan will be reflected
|
||||
in the scan, i.e. records inserted behind the cursor will not be returned
|
||||
while records inserted in front of the cursor will be returned.
|
||||
.IP
|
||||
Modifications to the database during a sequential scan will be
|
||||
reflected in the scan, i.e., records inserted behind the cursor will
|
||||
not be returned while records inserted in front of the cursor will be
|
||||
returned.
|
||||
.Pp
|
||||
The flag value
|
||||
.B must
|
||||
.Em must
|
||||
be set to one of the following values:
|
||||
.RS
|
||||
.TP
|
||||
R_CURSOR
|
||||
.Bl -tag -width R_CURSORX
|
||||
.It Dv R_CURSOR
|
||||
The data associated with the specified key is returned.
|
||||
This differs from the
|
||||
.I get
|
||||
.Fa get
|
||||
routines in that it sets or initializes the cursor to the location of
|
||||
the key as well.
|
||||
(Note, for the DB_BTREE access method, the returned key is not necessarily an
|
||||
exact match for the specified key.
|
||||
The returned key is the smallest key greater than or equal to the specified
|
||||
key, permitting partial key matches and range searches.)
|
||||
.TP
|
||||
R_FIRST
|
||||
(Note, for the
|
||||
.Dv DB_BTREE
|
||||
access method, the returned key is not necessarily an exact match for
|
||||
the specified key.
|
||||
The returned key is the smallest key greater than or equal to the
|
||||
specified key, permitting partial key matches and range searches.)
|
||||
.It Dv R_FIRST
|
||||
The first key/data pair of the database is returned, and the cursor
|
||||
is set or initialized to reference it.
|
||||
.TP
|
||||
R_LAST
|
||||
.It Dv R_LAST
|
||||
The last key/data pair of the database is returned, and the cursor
|
||||
is set or initialized to reference it.
|
||||
(Applicable only to the DB_BTREE and DB_RECNO access methods.)
|
||||
.TP
|
||||
R_NEXT
|
||||
(Applicable only to the
|
||||
.Dv DB_BTREE
|
||||
and
|
||||
.Dv DB_RECNO
|
||||
access methods.)
|
||||
.It Dv R_NEXT
|
||||
Retrieve the key/data pair immediately after the cursor.
|
||||
If the cursor is not yet set, this is the same as the R_FIRST flag.
|
||||
.TP
|
||||
R_PREV
|
||||
If the cursor is not yet set, this is the same as the
|
||||
.Dv R_FIRST
|
||||
flag.
|
||||
.It Dv R_PREV
|
||||
Retrieve the key/data pair immediately before the cursor.
|
||||
If the cursor is not yet set, this is the same as the R_LAST flag.
|
||||
(Applicable only to the DB_BTREE and DB_RECNO access methods.)
|
||||
.RE
|
||||
.IP
|
||||
R_LAST and R_PREV are available only for the DB_BTREE and DB_RECNO
|
||||
If the cursor is not yet set, this is the same as the
|
||||
.Dv R_LAST
|
||||
flag.
|
||||
(Applicable only to the
|
||||
.Dv DB_BTREE
|
||||
and
|
||||
.Dv DB_RECNO
|
||||
access methods.)
|
||||
.El
|
||||
.Pp
|
||||
.Dv R_LAST
|
||||
and
|
||||
.Dv R_PREV
|
||||
are available only for the
|
||||
.Dv DB_BTREE
|
||||
and
|
||||
.Dv DB_RECNO
|
||||
access methods because they each imply that the keys have an inherent
|
||||
order which does not change.
|
||||
.IP
|
||||
.I Seq
|
||||
routines return -1 on error (setting
|
||||
.IR errno ),
|
||||
.Pp
|
||||
.Fa seq
|
||||
routines return \-1 on error (setting
|
||||
.Va errno ) ,
|
||||
0 on success and 1 if there are no key/data pairs less than or greater
|
||||
than the specified or current key.
|
||||
If the DB_RECNO access method is being used, and if the database file
|
||||
is a character special file and no complete key/data pairs are currently
|
||||
available, the
|
||||
.I seq
|
||||
If the
|
||||
.Dv DB_RECNO
|
||||
access method is being used, and if the database file is a character
|
||||
special file and no complete key/data pairs are currently available,
|
||||
the
|
||||
.Fa seq
|
||||
routines return 2.
|
||||
.TP
|
||||
sync
|
||||
.It Fa sync
|
||||
A pointer to a routine to flush any cached information to disk.
|
||||
If the database is in memory only, the
|
||||
.I sync
|
||||
.Fa sync
|
||||
routine has no effect and will always succeed.
|
||||
.IP
|
||||
.Pp
|
||||
The flag value may be set to the following value:
|
||||
.RS
|
||||
.TP
|
||||
R_RECNOSYNC
|
||||
If the DB_RECNO access method is being used, this flag causes
|
||||
the sync routine to apply to the btree file which underlies the
|
||||
recno file, not the recno file itself.
|
||||
.Bl -tag -width
|
||||
.It Dv R_RECNOSYNC
|
||||
If the
|
||||
.Dv DB_RECNO
|
||||
access method is being used, this flag causes the sync routine to
|
||||
apply to the btree file which underlies the recno file, not the recno
|
||||
file itself.
|
||||
(See the
|
||||
.I bfname
|
||||
.Fa bfname
|
||||
field of the
|
||||
.IR recno (3)
|
||||
.Xr recno 3
|
||||
manual page for more information.)
|
||||
.RE
|
||||
.IP
|
||||
.I Sync
|
||||
routines return -1 on error (setting
|
||||
.IR errno )
|
||||
.El
|
||||
.Pp
|
||||
.Fa sync
|
||||
routines return \-1 on error (setting
|
||||
.Va errno )
|
||||
and 0 on success.
|
||||
.SH "KEY/DATA PAIRS"
|
||||
.El
|
||||
.Ss KEY/DATA PAIRS
|
||||
Access to all file types is based on key/data pairs.
|
||||
Both keys and data are represented by the following data structure:
|
||||
.PP
|
||||
.Bd -literal
|
||||
typedef struct {
|
||||
.RS
|
||||
void *data;
|
||||
.br
|
||||
size_t size;
|
||||
.RE
|
||||
void *data;
|
||||
size_t size;
|
||||
} DBT;
|
||||
.PP
|
||||
.Pp
|
||||
The elements of the DBT structure are defined as follows:
|
||||
.TP
|
||||
data
|
||||
.Bl -tag -width datax
|
||||
.It Fa data
|
||||
A pointer to a byte string.
|
||||
.TP
|
||||
size
|
||||
.It Fa size
|
||||
The length of the byte string.
|
||||
.PP
|
||||
Key and data byte strings may reference strings of essentially unlimited
|
||||
length although any two of them must fit into available memory at the same
|
||||
time.
|
||||
.El
|
||||
.Pp
|
||||
Key and data byte strings may reference strings of essentially
|
||||
unlimited length although any two of them must fit into available
|
||||
memory at the same time.
|
||||
It should be noted that the access methods provide no guarantees about
|
||||
byte string alignment.
|
||||
.SH ERRORS
|
||||
.Sh ERRORS
|
||||
The
|
||||
.I dbopen
|
||||
.Nm
|
||||
routine may fail and set
|
||||
.I errno
|
||||
.Va errno
|
||||
for any of the errors specified for the library routines
|
||||
.IR open (2)
|
||||
.Xr open 2
|
||||
and
|
||||
.IR malloc (3)
|
||||
.Xr malloc 3
|
||||
or the following:
|
||||
.TP
|
||||
[EFTYPE]
|
||||
.Bl -tag -width Er
|
||||
.It Er EFTYPE
|
||||
A file is incorrectly formatted.
|
||||
.TP
|
||||
[EINVAL]
|
||||
A parameter has been specified (hash function, pad byte etc.) that is
|
||||
.It Er EINVAL
|
||||
A parameter has been specified (hash function, pad byte, etc.) that is
|
||||
incompatible with the current file specification or which is not
|
||||
meaningful for the function (for example, use of the cursor without
|
||||
prior initialization) or there is a mismatch between the version
|
||||
number of file and the software.
|
||||
.TP
|
||||
[EFBIG]
|
||||
.It Er EFBIG
|
||||
The key could not be inserted due to limitations in the DB file format
|
||||
(e.g. a hash database was out of overflow pages).
|
||||
.PP
|
||||
(e.g., a hash database was out of overflow pages).
|
||||
.El
|
||||
.Pp
|
||||
The
|
||||
.I close
|
||||
.Fa close
|
||||
routines may fail and set
|
||||
.I errno
|
||||
.Va errno
|
||||
for any of the errors specified for the library routines
|
||||
.IR close (2),
|
||||
.IR read (2),
|
||||
.IR write (2),
|
||||
.IR free (3),
|
||||
.Xr close 2 ,
|
||||
.Xr read 2 ,
|
||||
.Xr write 2 ,
|
||||
.Xr free 3 ,
|
||||
or
|
||||
.IR fsync (2).
|
||||
.PP
|
||||
.Xr fsync 2 .
|
||||
.Pp
|
||||
The
|
||||
.IR del ,
|
||||
.IR get ,
|
||||
.I put
|
||||
.Fa del ,
|
||||
.Fa get ,
|
||||
.Fa put ,
|
||||
and
|
||||
.I seq
|
||||
.Fa seq
|
||||
routines may fail and set
|
||||
.I errno
|
||||
.Va errno
|
||||
for any of the errors specified for the library routines
|
||||
.IR read (2),
|
||||
.IR write (2),
|
||||
.IR free (3)
|
||||
.Xr read 2 ,
|
||||
.Xr write 2 ,
|
||||
.Xr free 3 ,
|
||||
or
|
||||
.IR malloc (3).
|
||||
.PP
|
||||
.Xr malloc 3 .
|
||||
.Pp
|
||||
The
|
||||
.I fd
|
||||
.Fa fd
|
||||
routines will fail and set
|
||||
.I errno
|
||||
to ENOENT for in memory databases.
|
||||
.PP
|
||||
.Va errno
|
||||
to
|
||||
.Er ENOENT
|
||||
for in memory databases.
|
||||
.Pp
|
||||
The
|
||||
.I sync
|
||||
.Fa sync
|
||||
routines may fail and set
|
||||
.I errno
|
||||
.Va errno
|
||||
for any of the errors specified for the library routine
|
||||
.IR fsync (2).
|
||||
.SH "SEE ALSO"
|
||||
.IR btree (3),
|
||||
.IR hash (3),
|
||||
.IR mpool (3),
|
||||
.IR recno (3)
|
||||
.sp
|
||||
.IR "LIBTP: Portable, Modular Transactions for UNIX" ,
|
||||
Margo Seltzer, Michael Olson, USENIX proceedings, Winter 1992.
|
||||
.SH BUGS
|
||||
The typedef DBT is a mnemonic for ``data base thang'', and was used
|
||||
because noone could think of a reasonable name that wasn't already used.
|
||||
.PP
|
||||
.Xr fsync 2 .
|
||||
.Sh SEE ALSO
|
||||
.Xr btree 3 ,
|
||||
.Xr hash 3 ,
|
||||
.Xr mpool 3 ,
|
||||
.Xr recno 3
|
||||
.Pp
|
||||
.Rs
|
||||
.%T "LIBTP: Portable, Modular Transactions for UNIX"
|
||||
.%A Margo Seltzer
|
||||
.%A Michael Olson
|
||||
.%J USENIX proceedings
|
||||
.%D Winter 1992
|
||||
.Re
|
||||
.Sh BUGS
|
||||
The typedef DBT is a mnemonic for
|
||||
.Dq data base thang ,
|
||||
and was used because noone could think of a reasonable name that
|
||||
wasn't already used.
|
||||
.Pp
|
||||
The file descriptor interface is a kluge and will be deleted in a
|
||||
future version of the interface.
|
||||
.PP
|
||||
.Pp
|
||||
None of the access methods provide any form of concurrent access,
|
||||
locking, or transactions.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user