Debian Codegraph @

upstream/debian-unstable/man3/recno.3

raw
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.