Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 207 insertions, 0 deletions

diff --git a/man/man3/recno.3 b/man/man3/recno.3
new file mode 100644
index 0000000..03bcf1c
--- /dev/null
+++ b/man/man3/recno.3
@@ -0,0 +1,207 @@
+.\" Copyright (c) 1990, 1993
+.\"	The Regents of the University of California.  All rights reserved.
+.\"
+.\" SPDX-License-Identifier: BSD-4-Clause-UC
+.\"
+.\"	@(#)recno.3	8.5 (Berkeley) 8/18/94
+.\"
+.TH recno 3 2024-05-02 "Linux man-pages (unreleased)"
+.UC 7
+.SH NAME
+recno \- record number database access method
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.ft B
+#include <sys/types.h>
+#include <db.h>
+.ft R
+.fi
+.SH DESCRIPTION
+.IR "Note well" :
+This page documents interfaces provided up until glibc 2.1.
+Since glibc 2.2, glibc no longer provides these interfaces.
+Probably, you are looking for the APIs provided by the
+.I libdb
+library instead.
+.P
+The routine
+.BR dbopen (3)
+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
+.BR dbopen (3),
+this manual page describes only the recno-specific information.
+.P
+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.
+.P
+The recno access-method-specific data structure provided to
+.BR dbopen (3)
+is defined in the
+.I <db.h>
+include file as follows:
+.P
+.in +4n
+.EX
+typedef struct {
+    unsigned long flags;
+    unsigned int  cachesize;
+    unsigned int  psize;
+    int           lorder;
+    size_t        reclen;
+    unsigned char bval;
+    char         *bfname;
+} RECNOINFO;
+.EE
+.in
+.P
+The elements of this structure are defined as follows:
+.TP
+.I flags
+The flag value is specified by ORing
+any of the following values:
+.RS
+.TP
+.B 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
+.B R_NOKEY
+In the interface specified by
+.BR dbopen (3),
+the sequential record retrieval fills in both the caller's key and
+data structures.
+If the
+.B 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
+.B R_SNAPSHOT
+This flag requires that a snapshot of the file be taken when
+.BR dbopen (3)
+is called, instead of permitting any unmodified records to be read from
+the original file.
+.RE
+.TP
+.I 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
+.I 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 filesystem I/O block size.
+See
+.BR btree (3)
+for more information.
+.TP
+.I 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
+.I reclen
+The length of a fixed-length record.
+.TP
+.I 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
+.I bfname
+The recno access method stores the in-memory copies of its records
+in a btree.
+If
+.I bfname
+is non-NULL, it specifies the name of the btree file,
+as if specified as the filename for a
+.BR dbopen (3)
+of a btree file.
+.P
+The data part of the key/data pair used by the
+.I 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
+.I <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.
+.P
+Because there can be no metadata 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.
+.P
+In the interface specified by
+.BR dbopen (3),
+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
+.BR dbopen (3)
+or the following:
+.TP
+.B EINVAL
+An attempt was made to add a record to a fixed-length database that
+was too large to fit.
+.SH BUGS
+Only big and little endian byte order is supported.
+.SH SEE ALSO
+.BR btree (3),
+.BR dbopen (3),
+.BR hash (3),
+.BR mpool (3)
+.P
+.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.