| 1 |
.\" Copyright 1990-1993, The Regents of the University of California. |
| 2 |
.\" Copyright, the authors of the Linux man-pages project |
| 3 |
.\" |
| 4 |
.\" SPDX-License-Identifier: BSD-4-Clause-UC |
| 5 |
.\" |
| 6 |
.TH recno 3 2025-09-21 "Linux man-pages 6.18" |
| 7 |
.UC 7 |
| 8 |
.SH NAME |
| 9 |
recno \- record number database access method |
| 10 |
.SH LIBRARY |
| 11 |
Standard C library |
| 12 |
.RI ( libc ,\~ \-lc ) |
| 13 |
.SH SYNOPSIS |
| 14 |
.nf |
| 15 |
.ft B |
| 16 |
#include <sys/types.h> |
| 17 |
#include <db.h> |
| 18 |
.ft R |
| 19 |
.fi |
| 20 |
.SH DESCRIPTION |
| 21 |
.IR "Note well" : |
| 22 |
This page documents interfaces provided up until glibc 2.1. |
| 23 |
Since glibc 2.2, glibc no longer provides these interfaces. |
| 24 |
Probably, you are looking for the APIs provided by the |
| 25 |
.I libdb |
| 26 |
library instead. |
| 27 |
.P |
| 28 |
The routine |
| 29 |
.BR dbopen (3) |
| 30 |
is the library interface to database files. |
| 31 |
One of the supported file formats is record number files. |
| 32 |
The general description of the database access methods is in |
| 33 |
.BR dbopen (3), |
| 34 |
this manual page describes only the recno-specific information. |
| 35 |
.P |
| 36 |
The record number data structure is either variable or fixed-length |
| 37 |
records stored in a flat-file format, accessed by the logical record |
| 38 |
number. |
| 39 |
The existence of record number five implies the existence of records |
| 40 |
one through four, and the deletion of record number one causes |
| 41 |
record number five to be renumbered to record number four, as well |
| 42 |
as the cursor, if positioned after record number one, to shift down |
| 43 |
one record. |
| 44 |
.P |
| 45 |
The recno access-method-specific data structure provided to |
| 46 |
.BR dbopen (3) |
| 47 |
is defined in the |
| 48 |
.I <db.h> |
| 49 |
include file as follows: |
| 50 |
.P |
| 51 |
.in +4n |
| 52 |
.EX |
| 53 |
typedef struct { |
| 54 |
unsigned long flags; |
| 55 |
unsigned int cachesize; |
| 56 |
unsigned int psize; |
| 57 |
int lorder; |
| 58 |
size_t reclen; |
| 59 |
unsigned char bval; |
| 60 |
char *bfname; |
| 61 |
} RECNOINFO; |
| 62 |
.EE |
| 63 |
.in |
| 64 |
.P |
| 65 |
The elements of this structure are defined as follows: |
| 66 |
.TP |
| 67 |
.I flags |
| 68 |
The flag value is specified by ORing |
| 69 |
any of the following values: |
| 70 |
.RS |
| 71 |
.TP |
| 72 |
.B R_FIXEDLEN |
| 73 |
The records are fixed-length, not byte delimited. |
| 74 |
The structure element |
| 75 |
.I reclen |
| 76 |
specifies the length of the record, and the structure element |
| 77 |
.I bval |
| 78 |
is used as the pad character. |
| 79 |
Any records, inserted into the database, that are less than |
| 80 |
.I reclen |
| 81 |
bytes long are automatically padded. |
| 82 |
.TP |
| 83 |
.B R_NOKEY |
| 84 |
In the interface specified by |
| 85 |
.BR dbopen (3), |
| 86 |
the sequential record retrieval fills in both the caller's key and |
| 87 |
data structures. |
| 88 |
If the |
| 89 |
.B R_NOKEY |
| 90 |
flag is specified, the |
| 91 |
.I cursor |
| 92 |
routines are not required to fill in the key structure. |
| 93 |
This permits applications to retrieve records at the end of files without |
| 94 |
reading all of the intervening records. |
| 95 |
.TP |
| 96 |
.B R_SNAPSHOT |
| 97 |
This flag requires that a snapshot of the file be taken when |
| 98 |
.BR dbopen (3) |
| 99 |
is called, instead of permitting any unmodified records to be read from |
| 100 |
the original file. |
| 101 |
.RE |
| 102 |
.TP |
| 103 |
.I cachesize |
| 104 |
A suggested maximum size, in bytes, of the memory cache. |
| 105 |
This value is |
| 106 |
.B only |
| 107 |
advisory, and the access method will allocate more memory rather than fail. |
| 108 |
If |
| 109 |
.I cachesize |
| 110 |
is 0 (no size is specified), a default cache is used. |
| 111 |
.TP |
| 112 |
.I psize |
| 113 |
The recno access method stores the in-memory copies of its records |
| 114 |
in a btree. |
| 115 |
This value is the size (in bytes) of the pages used for nodes in that tree. |
| 116 |
If |
| 117 |
.I psize |
| 118 |
is 0 (no page size is specified), a page size is chosen based on the |
| 119 |
underlying filesystem I/O block size. |
| 120 |
See |
| 121 |
.BR btree (3) |
| 122 |
for more information. |
| 123 |
.TP |
| 124 |
.I lorder |
| 125 |
The byte order for integers in the stored database metadata. |
| 126 |
The number should represent the order as an integer; |
| 127 |
for example, |
| 128 |
big endian order would be the number 4,321. |
| 129 |
If |
| 130 |
.I lorder |
| 131 |
is 0 (no order is specified), |
| 132 |
the current host order is used. |
| 133 |
.TP |
| 134 |
.I reclen |
| 135 |
The length of a fixed-length record. |
| 136 |
.TP |
| 137 |
.I bval |
| 138 |
The delimiting byte to be used to mark the end of a record |
| 139 |
for variable-length records, |
| 140 |
and the pad character |
| 141 |
for fixed-length records. |
| 142 |
If no value is specified, |
| 143 |
newlines ("\[rs]n") are used to mark |
| 144 |
the end of variable-length records |
| 145 |
and fixed-length records |
| 146 |
are padded with spaces. |
| 147 |
.TP |
| 148 |
.I bfname |
| 149 |
The recno access method stores the in-memory copies of its records |
| 150 |
in a btree. |
| 151 |
If |
| 152 |
.I bfname |
| 153 |
is non-NULL, it specifies the name of the btree file, |
| 154 |
as if specified as the filename for a |
| 155 |
.BR dbopen (3) |
| 156 |
of a btree file. |
| 157 |
.P |
| 158 |
The data part of the key/data pair used by the |
| 159 |
.I recno |
| 160 |
access method |
| 161 |
is the same as other access methods. |
| 162 |
The key is different. |
| 163 |
The |
| 164 |
.I data |
| 165 |
field of the key should be a pointer to a memory location of type |
| 166 |
.IR recno_t , |
| 167 |
as defined in the |
| 168 |
.I <db.h> |
| 169 |
include file. |
| 170 |
This type is normally the largest unsigned integral type available to |
| 171 |
the implementation. |
| 172 |
The |
| 173 |
.I size |
| 174 |
field of the key should be the size of that type. |
| 175 |
.P |
| 176 |
Because there can be no metadata associated with the underlying |
| 177 |
recno access method files, any changes made to the default values |
| 178 |
(e.g., fixed record length or byte separator value) must be explicitly |
| 179 |
specified each time the file is opened. |
| 180 |
.P |
| 181 |
In the interface specified by |
| 182 |
.BR dbopen (3), |
| 183 |
using the |
| 184 |
.I put |
| 185 |
interface to create a new record will cause the creation of multiple, |
| 186 |
empty records if the record number is more than one greater than the |
| 187 |
largest record currently in the database. |
| 188 |
.SH ERRORS |
| 189 |
The |
| 190 |
.I recno |
| 191 |
access method routines may fail and set |
| 192 |
.I errno |
| 193 |
for any of the errors specified for the library routine |
| 194 |
.BR dbopen (3) |
| 195 |
or the following: |
| 196 |
.TP |
| 197 |
.B EINVAL |
| 198 |
An attempt was made to add a record to a fixed-length database that |
| 199 |
was too large to fit. |
| 200 |
.SH BUGS |
| 201 |
Only big and little endian byte order is supported. |
| 202 |
.SH SEE ALSO |
| 203 |
.BR btree (3), |
| 204 |
.BR dbopen (3), |
| 205 |
.BR hash (3), |
| 206 |
.BR mpool (3) |
| 207 |
.P |
| 208 |
.IR "Document Processing in a Relational Database System" , |
| 209 |
Michael Stonebraker, |
| 210 |
Heidi Stettner, |
| 211 |
Joseph Kalash, |
| 212 |
Antonin Guttman, |
| 213 |
Nadene Lynn, |
| 214 |
Memorandum No.\& UCB/ERL M82/32, May 1982. |