need types.h

[unix-history] / usr / src / lib / libc / db / man / dbopen.3

.\" Copyright (c) 1990 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" %sccs.include.redist.man%
.\"
.\"	@(#)dbopen.3	5.1 (Berkeley) %G%
.\"
.TH DB 3  ""
.UC 7
.SH NAME
btree_open, flat_open, hash_open \- database manipulation routines
.SH SYNOPSIS
.nf
.ft B
#include <db.h>

DB *
btree_open(const char *file, int flags, int mode, const BTREEINFO * private);

DB *
flat_open(const char *file, int flags, int mode, const FLATINFO * private);

DB *
hash_open(const char *file, int flags, int mode, const HASHINFO * private);
.ft R
.fi
.SH DESCRIPTION
.IR Btree_open ,
.IR flat_open ,
and
.I hash_open
are interfaces, respectively, to database files in btree, flat,
and hashed record formats.
Access to all file types is based on key/data pairs, where both keys
and data are of essentially unlimited size.
.PP
Each routine opens
.I file
for reading and/or writing.
The
.I flags
and
.I mode arguments
are as specified to the
.IR open (2)
routine, however only the O_CREAT, O_EXCL, O_RDONLY, O_RDWR, O_TRUNC
and O_WRONLY flags are meaningful.
Databases which are temporary, i.e. not intended to be preserved
on disk, may be created by setting the file parameter to NULL.
The argument
.I private
is a pointer to a private, access-method specific structure described
below.
.PP
The open routines return a pointer to a structure representing the
database on success and NULL on error.
This structure is as follows:
.sp
typedef struct {
.RS
void *internal;
.br
int (*close)(), (*delete)(), (*get)(), (*put)(), (*seq)(), (*sync)();
.RE
} DB;
.sp
.PP
This structure is as follows:
.TP
internal
A pointer to an internal structure private to the access method.
.TP
close
A pointer to a routine to flush any cached information to disk, free any
allocated resources, and close the database file, whose function prototype
is:
.sp
.in +5
close(const DB *db);
.in -5
.sp
Since key/data pairs may be cached in memory, failing to close the
file with the
.I close
routine may result in inconsistent or lost information.
The
.I close
routine returns 0 on error and 1 on success.
.TP
delete
A pointer to a routine to remove key/data pairs from the database,
whose function prototype is:
.sp
.in +5
delete(const DB *db, const VALUE *key);
.in -5
.sp
The
.I delete
routine returns 0 on error, 1 on success, and -1 if the specified
.I key
was not in the file.
.TP
get
A pointer to a routine which is the interface for keyed retrieval from
the database, whose function prototype is:
.sp
.in +5
get(const DB *db, const VALUE *key, VALUE *data);
.in -5
.sp
The address and length of the data associated with the specified
.I key
are returned in the structure referenced by
.IR data .
The
.I get
routine returns 0 on error, 1 on success, and -1 if the
.I key
was not in the file.
.TP
put
A pointer to a routine to store key/data pairs in the database,
whose function prototype is:
.sp
.in +5
put(const DB *db, const VALUE *key, const VALUE *data, u_long flag);
.in -5
.sp
The parameter flag, if set, should be either R_APPEND or R_INSERT,
optionally
.IR or 'ed
with R_NOOVERWRITE.
.RS
.TP
R_APPEND
Append the data immediately after the data referenced by
.IR key ,
creating a new record.
(This implies that the access method is able to create new keys itself,
i.e. the keys are ordered and independent, for example, record numbers.
Currently applicable only to the flat file access method.)
.TP
R_INSERT
Insert the data immediately before the data referenced by
.IR key ,
creating a new record.
(This implies that the access method is able to create new keys itself,
i.e. the keys are ordered and independent, for example, record numbers.
Currently applicable only to the flat file access method.)
.TP
R_NOOVERWRITE
Enter the new key/data pair only if the key does not previously exist.
.RE
.PP
The
.I put
routine returns 0 on error, 1 on success, and -1 if the
R_NOOVERWRITE
.I flag
is set and the key already exists in the file.
.TP
seq
A pointer to a routine which is the interface for sequential
retrieval from the database, whose function prototype is:
.sp
.in +5
seq(const DB *db, VALUE *key, VALUE *data, int flag);
.in -5
.sp
The address and length of the key are returned in the structure
referenced by
.IR key ,
and the address and length of the data are returned in the
structure referenced
by
.IR data .
.PP
The flag value, if set, should be one of the following values:
.RS
.TP
R_FIRST
The first key of the hash table is returned.
.TP
R_LAST
The last key of the hash table is returned.
.TP
R_NEXT
Retrieve the record immediately after the most recently requested
record.
.TP
R_PREV
Retrieve the record immediately before the most recently requested
record.
.RE
.PP
The first time the
.I seq
routine is called, the first record of the database is returned
if
.I flag
is not set or is set to R_FIRST or R_NEXT.
.PP
The
.I seq
routine returns 0 on error, 1 on success, -1 if end-of-file is reached,
and -2 if the input is a character device and no complete records are
available.
.TP
sync
A pointer to a routine to flush any cached information to disk,
whose function prototype is:
.sp
.in +5
sync(const DB *db);
.in -5
.sp
If the database is in memory only, the
.I sync
routine is a no-op.
The
.I sync
routine returns 0 on error and 1 on success.
.PP
Each of the routines take a pointer to a structure as returned by
the open routine, one or more pointers to key/data structures, and,
optionally, a flag value.
.PP
Keys (and data) are represented by the following data structure:
.sp
typedef struct {
.RS
u_char *data;
.br
size_t size;
.RE
} ENTRY;
.PP
The elements of this structure are as follows:
.TP
data
A pointer to a byte string.
.TP
size
The length of the byte string.
.SH BTREE
One of the access methods is a btree: a sorted, balanced
tree structure with associated key and data pairs.
.PP
<Mike fill this in?>
.PP
The private data structure provided to
.I btree_open
is as follows:
.sp
typedef struct {
.RS
u_long flags;
.br
int cachesize;
.br
int pagesize;
.RE
} BTREEINFO;
.PP
The elements of this structure are as follows:
.TP
flags
The flag value is specified by
.IR or 'ing
the following values:
.RS
.TP
R_SMALLCACHE
A flag informing the routines that they are not expected to be
the primary data cache, and to minimize any caching they do.
.RE
.TP
cachesize
.TP
pagesize
.SH HASH
One of the access methods is hashed access and storage.
The private data structure provided to
.I hash_open
is as follows:
.sp
typedef struct {
.RS
u_long flags;
.br
int bsize;
.br
int ffactor;
.br
int nelem;
.br
u_long (*hash)(const void *, const size_t);
.RE
} HASHINFO;
.PP
The elements of this structure are as follows:
.TP
flags
The flag value is specified by
.IR or 'ing
the following values:
.RS
.TP
R_SMALLCACHE
A flag informing the routines that they are not expected to be
the primary cache, and to minimize any caching they do.
.RE
.TP
bsize
.I Bsize
defines the hash table bucket size, and is, by default 1024, bytes.
For tables with large data items, it may be preferable to increase the
page size, and, conversely, applications doing exclusively in-memory hashing
may want to use a very small bucket size, for example, 256, to minimize
hash chain collisions.
.TP
ffactor
.I Ffactor
indicates a desired density within the hash table.
It is an approximation of the number of keys allowed to accumulate in any
one bucket, determining when the hash table grows or shrinks.
The default value is 5.
.TP
hash
.I Hash
is a user defined hash function.
Since no hash function performs equally well on all possible data, the
user may find that the built-in hash function does poorly on a particular
data set.
Any user specified hash function should take two arguments, a pointer to
a byte string and a length, and return an unsigned long to be used as
the hash value.
.TP
nelem
.I Nelem
is an estimate of the final size of the hash table.
If not set, the default value is 1.
If not set or set too low, hash tables will expand gracefully as keys
are entered, although a slight performance degradation may be noticed.
.PP
If the hash table already exists, and the O_TRUNC flag is not
specified to 
.IR hash_open ,
the parameters
.IR bsize ,
.IR ffactor ,
and
.I nelem
are ignored. 
.PP
If a hash function is specified, 
.I hash_open
will attempt to determine if the hash function specified is the same as
the one with which the database was created, and will fail if it is not.
.PP
Backward compatible interfaces to the routines described in
.IR dbm (3),
.IR hsearch (3),
and
.IR ndbm (3)
are provided as part of the compatibility library, ``libcompat.a''.
.SH "FLAT FILES"
One of the access methods is either variable or fixed-length records,
the former delimited by a specific byte value.
The private data structure provided to
.I flat_open
is as follows:
.sp
typedef struct {
.RS
u_long flags;
.br
int cachesize;
.br
size_t reclen;
.br
u_char bval;
.RE
} VLENINFO;
.PP
The elements of this structure are as follows:
.TP
flags
The flag value is specified by
.IR or 'ing
the following values:
.RS
.TP
R_FIXEDLEN
The records are fixed-length, not byte delimited.
The structure element
.I reclen
specifies the length of the record, and the structure element
.I bval
is used as the pad character.
.TP
R_SMALLCACHE
A flag informing the routines that they are not expected to be
the primary cache, and to minimize any caching they do.
.RE
.TP
cachesize
The amount of memory to be used as a data cache.
.TP
reclen
The length of a fixed-length record.
.TP
bval
The delimiting byte to be used to mark the end of a record for
variable-length records, and the pad character for fixed-length
records.
.PP
Variable-length and fixed-length data files require
.I key
structures to reference a byte followed by three unsigned longs.
The numbers are used as a record number, a byte offset and a record length,
respectively, and the byte is a flag value which indicates the validity
of the other fields.
These access methods do no validity checking as to the correctness of any
of these values, nor are they constrained to use the values provided.
If any of the record number, byte offset or record length are not specified
by the calling routine, and the record retrieval is successful, the correct
values are copied into the caller's
.I key
structure.
The flag value is specified by
.IR or 'ing
the following values:
.TP
R_LENGTH
The record length is valid.
.TP
R_OFFSET
The byte offset is valid.
.TP
R_RECNO
The record number is valid.
.SH ERRORS
The
.I open
routines may fail and set errno for any of the errors specified for the
library routines
.IR open (2)
and
.IR malloc (3)
or the following:
.TP
[EINVAL]
A parameter has been specified (hash function, pad byte etc.) that is
incompatible with the current file specification or there is a mismatch
between the version number of file and the software.
.PP
The
.I get
routines may fail and set errno for any of the errors specified for the
library routine
.IR malloc (3).
.PP
The
.I close
routines may fail and set errno for any of the errors specified for the
library routines
.IR close (2),
.IR free (3),
or
.IR fsync (2).
.PP
The
.I sync
routines may fail and set errno for any of the errors specified for the
library routine
.IR fsync (2).