aboutsummaryrefslogtreecommitdiff
path: root/_db1.85/man/recno.3
diff options
context:
space:
mode:
Diffstat (limited to '_db1.85/man/recno.3')
-rw-r--r--_db1.85/man/recno.3221
1 files changed, 221 insertions, 0 deletions
diff --git a/_db1.85/man/recno.3 b/_db1.85/man/recno.3
new file mode 100644
index 0000000..2a58f6f
--- /dev/null
+++ b/_db1.85/man/recno.3
@@ -0,0 +1,221 @@
+.\" $OpenBSD: recno.3,v 1.20 2015/09/10 10:20:55 jmc Exp $
+.\" $NetBSD: recno.3,v 1.6 1996/05/03 21:26:51 cgd Exp $
+.\"
+.\" Copyright (c) 1997, Phillip F Knaack. All rights reserved.
+.\"
+.\" 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 $Mdocdate: September 10 2015 $
+.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
+.Fn dbopen
+routine 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
+.Nm
+access method specific data structure provided to
+.Fn dbopen
+is defined in the
+.In db.h
+include file as follows:
+.Bd -literal -offset indent
+typedef struct {
+ unsigned long flags;
+ unsigned int cachesize;
+ unsigned int psize;
+ int lorder;
+ size_t reclen;
+ unsigned char bval;
+ char *bfname;
+} RECNOINFO;
+.Ed
+.Pp
+The elements of this structure are defined as follows:
+.Bl -tag -width XXXXXX
+.It Fa flags
+The flag value is specified by
+.Tn OR Ns 'ing
+any of the following values:
+.Bl -tag -width R_FIXEDLEN
+.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 R_NOKEY flag is specified, the
+.Fa 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 Ql \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
+.Fa bfname
+is non-NULL, it specifies the name of the
+.Xr btree 3
+file, as if specified as the file name for a
+.Xr dbopen 3
+of a
+.Xr btree 3
+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
+.Vt 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
+.Fa recno
+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 XEINVALX
+.It Bq 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
+.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.