218 lines
6.8 KiB
Groff
218 lines
6.8 KiB
Groff
.\" Copyright (c) 1990, 1993
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the University of
|
|
.\" California, Berkeley and its contributors.
|
|
.\" 4. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" @(#)recno.3 8.5 (Berkeley) 8/18/94
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.TH RECNO 3 "August 18, 1994"
|
|
.UC 7
|
|
.SH NAME
|
|
recno \- record number database access method
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.ft B
|
|
#include <sys/types.h>
|
|
#include <db.h>
|
|
.ft R
|
|
.fi
|
|
.SH DESCRIPTION
|
|
The routine
|
|
.IR dbopen
|
|
is the library interface to database files.
|
|
One of the supported file formats is record number files.
|
|
The general description of the database access methods is in
|
|
.IR dbopen (3),
|
|
this manual page describes only the recno specific information.
|
|
.PP
|
|
The record number data structure is either variable or fixed-length
|
|
records stored in a flat-file format, accessed by the logical record
|
|
number.
|
|
The existence of record number five implies the existence of records
|
|
one through four, and the deletion of record number one causes
|
|
record number five to be renumbered to record number four, as well
|
|
as the cursor, if positioned after record number one, to shift down
|
|
one record.
|
|
.PP
|
|
The recno access method specific data structure provided to
|
|
.I dbopen
|
|
is defined in the <db.h> include file as follows:
|
|
.PP
|
|
typedef struct {
|
|
.RS
|
|
u_long flags;
|
|
.br
|
|
u_int cachesize;
|
|
.br
|
|
u_int psize;
|
|
.br
|
|
int lorder;
|
|
.br
|
|
size_t reclen;
|
|
.br
|
|
u_char bval;
|
|
.br
|
|
char *bfname;
|
|
.RE
|
|
} RECNOINFO;
|
|
.PP
|
|
The elements of this structure are defined as follows:
|
|
.TP
|
|
flags
|
|
The flag value is specified by
|
|
.IR or 'ing
|
|
any of 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.
|
|
Any records, inserted into the database, that are less than
|
|
.I reclen
|
|
bytes long are automatically padded.
|
|
.TP
|
|
R_NOKEY
|
|
In the interface specified by
|
|
.IR dbopen ,
|
|
the sequential record retrieval fills in both the caller's key and
|
|
data structures.
|
|
If the R_NOKEY flag is specified, the
|
|
.I cursor
|
|
routines are not required to fill in the key structure.
|
|
This permits applications to retrieve records at the end of files without
|
|
reading all of the intervening records.
|
|
.TP
|
|
R_SNAPSHOT
|
|
This flag requires that a snapshot of the file be taken when
|
|
.I dbopen
|
|
is called, instead of permitting any unmodified records to be read from
|
|
the original file.
|
|
.RE
|
|
.TP
|
|
cachesize
|
|
A suggested maximum size, in bytes, of the memory cache.
|
|
This value is
|
|
.B only
|
|
advisory, and the access method will allocate more memory rather than fail.
|
|
If
|
|
.I cachesize
|
|
is 0 (no size is specified) a default cache is used.
|
|
.TP
|
|
psize
|
|
The recno access method stores the in-memory copies of its records
|
|
in a btree.
|
|
This value is the size (in bytes) of the pages used for nodes in that tree.
|
|
If
|
|
.I psize
|
|
is 0 (no page size is specified) a page size is chosen based on the
|
|
underlying file system I/O block size.
|
|
See
|
|
.IR btree (3)
|
|
for more information.
|
|
.TP
|
|
lorder
|
|
The byte order for integers in the stored database metadata.
|
|
The number should represent the order as an integer; for example,
|
|
big endian order would be the number 4,321.
|
|
If
|
|
.I lorder
|
|
is 0 (no order is specified) the current host order is used.
|
|
.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.
|
|
If no value is specified, newlines (``\en'') are used to mark the end
|
|
of variable-length records and fixed-length records are padded with
|
|
spaces.
|
|
.TP
|
|
bfname
|
|
The recno access method stores the in-memory copies of its records
|
|
in a btree.
|
|
If bfname is non-NULL, it specifies the name of the btree file,
|
|
as if specified as the file name for a dbopen of a btree file.
|
|
.PP
|
|
The data part of the key/data pair used by the recno access method
|
|
is the same as other access methods.
|
|
The key is different.
|
|
The
|
|
.I data
|
|
field of the key should be a pointer to a memory location of type
|
|
.IR recno_t ,
|
|
as defined in the <db.h> include file.
|
|
This type is normally the largest unsigned integral type available to
|
|
the implementation.
|
|
The
|
|
.I size
|
|
field of the key should be the size of that type.
|
|
.PP
|
|
Because there can be no meta-data associated with the underlying
|
|
recno access method files, any changes made to the default values
|
|
(e.g. fixed record length or byte separator value) must be explicitly
|
|
specified each time the file is opened.
|
|
.PP
|
|
In the interface specified by
|
|
.IR dbopen ,
|
|
using the
|
|
.I put
|
|
interface to create a new record will cause the creation of multiple,
|
|
empty records if the record number is more than one greater than the
|
|
largest record currently in the database.
|
|
.SH ERRORS
|
|
The
|
|
.I recno
|
|
access method routines may fail and set
|
|
.I errno
|
|
for any of the errors specified for the library routine
|
|
.IR dbopen (3)
|
|
or the following:
|
|
.TP
|
|
[EINVAL]
|
|
An attempt was made to add a record to a fixed-length database that
|
|
was too large to fit.
|
|
.SH "SEE ALSO"
|
|
.IR btree (3),
|
|
.IR dbopen (3),
|
|
.IR hash (3),
|
|
.IR mpool (3)
|
|
.sp
|
|
.IR "Document Processing in a Relational Database System" ,
|
|
Michael Stonebraker, Heidi Stettner, Joseph Kalash, Antonin Guttman,
|
|
Nadene Lynn, Memorandum No. UCB/ERL M82/32, May 1982.
|
|
.SH BUGS
|
|
Only big and little endian byte order is supported.
|