215 lines
6.7 KiB
Groff
215 lines
6.7 KiB
Groff
|
.\" $NetBSD: recno.3,v 1.11 2010/03/22 19:30:53 joerg Exp $
|
||
|
|
.\"
|
||
|
|
.\" 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. 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
|
||
|
|
.\"
|
||
|
|
.Dd April 17, 2003
|
||
|
|
.Dt RECNO 3
|
||
|
|
.Os
|
||
|
|
.Sh NAME
|
||
|
|
.Nm recno
|
||
|
|
.Nd record number database access method
|
||
|
|
.Sh SYNOPSIS
|
||
|
|
.In sys/types.h
|
||
|
|
.In db.h
|
||
|
|
.Sh DESCRIPTION
|
||
|
|
The routine
|
||
|
|
.Fn 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
|
||
|
|
.Xr 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
|
||
|
|
.Fn dbopen
|
||
|
|
is defined in the
|
||
|
|
.In db.h
|
||
|
|
include file as follows:
|
||
|
|
.Bd -literal
|
||
|
|
typedef struct {
|
||
|
|
u_long flags;
|
||
|
|
u_int cachesize;
|
||
|
|
u_int psize;
|
||
|
|
int lorder;
|
||
|
|
size_t reclen;
|
||
|
|
uint8_t bval;
|
||
|
|
char *bfname;
|
||
|
|
} RECNOINFO;
|
||
|
|
.Ed
|
||
|
|
.Pp
|
||
|
|
The elements of this structure are defined as follows:
|
||
|
|
.Bl -tag -width cachesizex
|
||
|
|
.It Fa flags
|
||
|
|
The flag value is specified by or'ing any of the following values:
|
||
|
|
.Bl -tag -width R_FIXEDLENX -offset indent
|
||
|
|
.It Dv R_FIXEDLEN
|
||
|
|
The records are fixed-length, not byte delimited.
|
||
|
|
The structure element
|
||
|
|
.Fa reclen
|
||
|
|
specifies the length of the record, and the structure element
|
||
|
|
.Fa bval
|
||
|
|
is used as the pad character.
|
||
|
|
Any records, inserted into the database, that are less than
|
||
|
|
.Fa reclen
|
||
|
|
bytes long are automatically padded.
|
||
|
|
.It Dv R_NOKEY
|
||
|
|
In the interface specified by
|
||
|
|
.Fn dbopen ,
|
||
|
|
the sequential record retrieval fills in both the caller's key and
|
||
|
|
data structures.
|
||
|
|
If the
|
||
|
|
.Dv R_NOKEY
|
||
|
|
flag is specified, the 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.
|
||
|
|
.It Dv R_SNAPSHOT
|
||
|
|
This flag requires that a snapshot of the file be taken when
|
||
|
|
.Fn dbopen
|
||
|
|
is called, instead of permitting any unmodified records to be read
|
||
|
|
from the original file.
|
||
|
|
.El
|
||
|
|
.It Fa cachesize
|
||
|
|
A suggested maximum size, in bytes, of the memory cache.
|
||
|
|
This value is
|
||
|
|
.Em only
|
||
|
|
advisory, and the access method will allocate more memory rather than
|
||
|
|
fail.
|
||
|
|
If
|
||
|
|
.Fa cachesize
|
||
|
|
is 0 (no size is specified) a default cache is used.
|
||
|
|
.It Fa 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
|
||
|
|
.Fa psize
|
||
|
|
is 0 (no page size is specified) a page size is chosen based on the
|
||
|
|
underlying file system I/O block size.
|
||
|
|
See
|
||
|
|
.Xr btree 3
|
||
|
|
for more information.
|
||
|
|
.It Fa 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
|
||
|
|
.Fa lorder
|
||
|
|
is 0 (no order is specified) the current host order is used.
|
||
|
|
.It Fa reclen
|
||
|
|
The length of a fixed-length record.
|
||
|
|
.It Fa 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
|
||
|
|
.Pq Dq \en
|
||
|
|
are used to mark the end of variable-length records and fixed-length
|
||
|
|
records are padded with spaces.
|
||
|
|
.It Fa bfname
|
||
|
|
The recno access method stores the in-memory copies of its records
|
||
|
|
in a btree.
|
||
|
|
If bfname is
|
||
|
|
.No non- Ns Dv NULL ,
|
||
|
|
it specifies the name of the btree file, as if specified as the file
|
||
|
|
name for a
|
||
|
|
.Fn dbopen
|
||
|
|
of a btree file.
|
||
|
|
.El
|
||
|
|
.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
|
||
|
|
.Fa data
|
||
|
|
field of the key should be a pointer to a memory location of type
|
||
|
|
recno_t, as defined in the
|
||
|
|
.In db.h
|
||
|
|
include file.
|
||
|
|
This type is normally the largest unsigned integral type available to
|
||
|
|
the implementation.
|
||
|
|
The
|
||
|
|
.Fa 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
|
||
|
|
.Fn dbopen ,
|
||
|
|
using the
|
||
|
|
.Fa 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
|
||
|
|
.Nm
|
||
|
|
access method routines may fail and set
|
||
|
|
.Va errno
|
||
|
|
for any of the errors specified for the library routine
|
||
|
|
.Xr dbopen 3
|
||
|
|
or the following:
|
||
|
|
.Bl -tag -width Er
|
||
|
|
.It Er EINVAL
|
||
|
|
An attempt was made to add a record to a fixed-length database that
|
||
|
|
was too large to fit.
|
||
|
|
.El
|
||
|
|
.Sh SEE ALSO
|
||
|
|
.Xr btree 3 ,
|
||
|
|
.Xr dbopen 3 ,
|
||
|
|
.Xr hash 3 ,
|
||
|
|
.Xr mpool 3
|
||
|
|
.Pp
|
||
|
|
.Rs
|
||
|
|
.%T "Document Processing in a Relational Database System"
|
||
|
|
.%A Michael Stonebraker
|
||
|
|
.%A Heidi Stettner
|
||
|
|
.%A Joseph Kalash
|
||
|
|
.%A Antonin Guttman
|
||
|
|
.%A Nadene Lynn
|
||
|
|
.%J Memorandum No. UCB/ERL M82/32
|
||
|
|
.%D May 1982
|
||
|
|
.Re
|
||
|
|
.Sh BUGS
|
||
|
|
Only big and little endian byte order is supported.
|