lib/libc/db/man/recno.3

   1 .\" Copyright (c) 1990, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)recno.3     8.5 (Berkeley) 8/18/94
  33 .\" $FreeBSD: src/lib/libc/db/man/recno.3,v 1.4.2.2 2001/12/14 18:33:49 ru Exp $
  34 .\" $DragonFly: src/lib/libc/db/man/recno.3,v 1.2 2003/06/17 04:26:41 dillon Exp $
  35 .\"
  36 .Dd August 18, 1994
  37 .Dt RECNO 3
  38 .Os
  39 .Sh NAME
  40 .Nm recno
  41 .Nd "record number database access method"
  42 .Sh SYNOPSIS
  43 .In sys/types.h
  44 .In db.h
  45 .Sh DESCRIPTION
  46 The routine
  47 .Fn dbopen
  48 is the library interface to database files.
  49 One of the supported file formats is record number files.
  50 The general description of the database access methods is in
  51 .Xr dbopen 3 ,
  52 this manual page describes only the
  53 .Nm
  54 specific information.
  55 .Pp
  56 The record number data structure is either variable or fixed-length
  57 records stored in a flat-file format, accessed by the logical record
  58 number.
  59 The existence of record number five implies the existence of records
  60 one through four, and the deletion of record number one causes
  61 record number five to be renumbered to record number four, as well
  62 as the cursor, if positioned after record number one, to shift down
  63 one record.
  64 .Pp
  65 The
  66 .Nm
  67 access method specific data structure provided to
  68 .Fn dbopen
  69 is defined in the
  70 .Aq Pa db.h
  71 include file as follows:
  72 .Bd -literal
  73 typedef struct {
  74         u_long flags;
  75         u_int cachesize;
  76         u_int psize;
  77         int lorder;
  78         size_t reclen;
  79         u_char bval;
  80         char *bfname;
  81 } RECNOINFO;
  82 .Ed
  83 .Pp
  84 The elements of this structure are defined as follows:
  85 .Bl -tag -width indent
  86 .It Va flags
  87 The flag value is specified by
  88 .Em or Ns 'ing
  89 any of the following values:
  90 .Bl -tag -width indent
  91 .It Dv R_FIXEDLEN
  92 The records are fixed-length, not byte delimited.
  93 The structure element
  94 .Va reclen
  95 specifies the length of the record, and the structure element
  96 .Va bval
  97 is used as the pad character.
  98 Any records, inserted into the database, that are less than
  99 .Va reclen
 100 bytes long are automatically padded.
 101 .It Dv R_NOKEY
 102 In the interface specified by
 103 .Fn dbopen ,
 104 the sequential record retrieval fills in both the caller's key and
 105 data structures.
 106 If the
 107 .Dv R_NOKEY
 108 flag is specified, the
 109 .Em cursor
 110 routines are not required to fill in the key structure.
 111 This permits applications to retrieve records at the end of files without
 112 reading all of the intervening records.
 113 .It Dv R_SNAPSHOT
 114 This flag requires that a snapshot of the file be taken when
 115 .Fn dbopen
 116 is called, instead of permitting any unmodified records to be read from
 117 the original file.
 118 .El
 119 .It Va cachesize
 120 A suggested maximum size, in bytes, of the memory cache.
 121 This value is
 122 .Em only
 123 advisory, and the access method will allocate more memory rather than fail.
 124 If
 125 .Va cachesize
 126 is 0 (no size is specified) a default cache is used.
 127 .It Va psize
 128 The
 129 .Nm
 130 access method stores the in-memory copies of its records
 131 in a btree.
 132 This value is the size (in bytes) of the pages used for nodes in that tree.
 133 If
 134 .Va psize
 135 is 0 (no page size is specified) a page size is chosen based on the
 136 underlying file system I/O block size.
 137 See
 138 .Xr btree 3
 139 for more information.
 140 .It Va lorder
 141 The byte order for integers in the stored database metadata.
 142 The number should represent the order as an integer; for example,
 143 big endian order would be the number 4,321.
 144 If
 145 .Va lorder
 146 is 0 (no order is specified) the current host order is used.
 147 .It Va reclen
 148 The length of a fixed-length record.
 149 .It Va bval
 150 The delimiting byte to be used to mark the end of a record for
 151 variable-length records, and the pad character for fixed-length
 152 records.
 153 If no value is specified, newlines
 154 .Pq Dq \en
 155 are used to mark the end
 156 of variable-length records and fixed-length records are padded with
 157 spaces.
 158 .It Va bfname
 159 The
 160 .Nm
 161 access method stores the in-memory copies of its records
 162 in a btree.
 163 If
 164 .Va bfname
 165 is
 166 .No non\- Ns Dv NULL ,
 167 it specifies the name of the btree file,
 168 as if specified as the file name for a
 169 .Fn dbopen
 170 of a btree file.
 171 .El
 172 .Pp
 173 The data part of the key/data pair used by the
 174 .Nm
 175 access method
 176 is the same as other access methods.
 177 The key is different.
 178 The
 179 .Va data
 180 field of the key should be a pointer to a memory location of type
 181 .Ft recno_t ,
 182 as defined in the
 183 .Aq Pa db.h
 184 include file.
 185 This type is normally the largest unsigned integral type available to
 186 the implementation.
 187 The
 188 .Va size
 189 field of the key should be the size of that type.
 190 .Pp
 191 Because there can be no meta-data associated with the underlying
 192 .Nm
 193 access method files, any changes made to the default values
 194 (e.g. fixed record length or byte separator value) must be explicitly
 195 specified each time the file is opened.
 196 .Pp
 197 In the interface specified by
 198 .Fn dbopen ,
 199 using the
 200 .Va put
 201 interface to create a new record will cause the creation of multiple,
 202 empty records if the record number is more than one greater than the
 203 largest record currently in the database.
 204 .Sh ERRORS
 205 The
 206 .Nm
 207 access method routines may fail and set
 208 .Va errno
 209 for any of the errors specified for the library routine
 210 .Xr dbopen 3
 211 or the following:
 212 .Bl -tag -width Er
 213 .It Bq Er EINVAL
 214 An attempt was made to add a record to a fixed-length database that
 215 was too large to fit.
 216 .El
 217 .Sh SEE ALSO
 218 .Xr btree 3 ,
 219 .Xr dbopen 3 ,
 220 .Xr hash 3 ,
 221 .Xr mpool 3
 222 .Rs
 223 .%T "Document Processing in a Relational Database System"
 224 .%A Michael Stonebraker
 225 .%A Heidi Stettner
 226 .%A Joseph Kalash
 227 .%A Antonin Guttman
 228 .%A Nadene Lynn
 229 .%R "Memorandum No. UCB/ERL M82/32"
 230 .%D May 1982
 231 .Re
 232 .Sh BUGS
 233 Only big and little endian byte order is supported.