draft/man3/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 .\"
  34 .\" Japanese Version Copyright (c) 1999 Shouichi Saito
  35 .\"     all rights reserved.
  36 .\" Translated Mon Jul 26 12:18:39 JST 1999
  37 .\"     by Shouichi Saito <ss236rx@ymg.urban.ne.jp>
  38 .\" Proofed Tue Aug 19 1999 by NAKANO Takeo <nakano@apm.seikei.ac.jp>
  39 .\"
  40 .\"WORD:        access method           アクセスメソッド
  41 .\"WORD:        pad character           埋め文字
  42 .TH RECNO 3 1994-08-18 "" "Linux Programmer's Manual"
  43 .UC 7
  44 .SH 名前
  45 .\"O recno \- record number database access method
  46 recno \- レコード番号データベースへのアクセスメソッド
  47 .SH 書式
  48 .nf
  49 .ft B
  50 #include <sys/types.h>
  51 #include <db.h>
  52 .ft R
  53 .fi
  54 .SH 説明
  55 .\"O The routine
  56 .\"O .BR dbopen (3)
  57 .\"O is the library interface to database files.
  58 ルーチン
  59 .BR dbopen (3)
  60 はデータベースファイルに対するライブラリインターフェースである。
  61 .\"O One of the supported file formats is record number files.
  62 .\"O The general description of the database access methods is in
  63 .\"O .BR dbopen (3),
  64 .\"O this manual page describes only the recno specific information.
  65 サポートされているファイルフォーマットの一つに、
  66 レコード番号ファイル (record number file: recno file) がある。
  67 データベースへのアクセスメソッドに関する一般的な記述は
  68 .BR dbopen (3),
  69 に書かれている。
  70 このマニュアルページでは recno 特有の情報についてのみ記述する。
  71 .PP
  72 .\"O The record number data structure is either variable or fixed-length
  73 .\"O records stored in a flat-file format, accessed by the logical record
  74 .\"O number.
  75 レコード番号データ構造は、フラットなファイル形式に格納された
  76 可変長/固定長レコードからなり、論理レコード番号でアクセスされる。
  77 .\"O The existence of record number five implies the existence of records
  78 .\"O one through four, and the deletion of record number one causes
  79 .\"O record number five to be renumbered to record number four, as well
  80 .\"O as the cursor, if positioned after record number one, to shift down
  81 .\"O one record.
  82 レコード番号 5 があれば、レコード番号 1 から 4 も存在する。
  83 レコード番号 1 を削除すると、レコード番号 5 は 4 に付け替えられ、
  84 カーソルも移動する。レコード番号 1 以降のものは一つ繰り上がるわけである。
  85 .PP
  86 .\"O The recno access method specific data structure provided to
  87 .\"O .BR dbopen (3)
  88 .\"O is defined in the
  89 .\"O .I <db.h>
  90 .\"O include file as follows:
  91 .BR dbopen (3)
  92 で使う recno アクセスメソッドに特有のデータ構造体は、
  93 .I <db.h>
  94 インクルードファイルで次のように定義されている。
  95 .PP
  96 .in +4n
  97 .nf
  98 typedef struct {
  99     unsigned long flags;
 100     unsigned int  cachesize;
 101     unsigned int  psize;
 102     int           lorder;
 103     size_t        reclen;
 104     unsigned char bval;
 105     char         *bfname;
 106 } RECNOINFO;
 107 .fi
 108 .in
 109 .PP
 110 .\"O The elements of this structure are defined as follows:
 111 この構造体の要素を以下に示す。
 112 .TP
 113 flags
 114 .\"O The flag value is specified by ORing
 115 .\"O any of the following values:
 116 flag の値は以下の値の論理和で指定される。
 117 .RS
 118 .TP
 119 .B R_FIXEDLEN
 120 .\"O The records are fixed-length, not byte delimited.
 121 レコード長が固定であり、バイト区切りではない。
 122 .\"O The structure element
 123 .\"O .I reclen
 124 .\"O specifies the length of the record, and the structure element
 125 .\"O .I bval
 126 .\"O is used as the pad character.
 127 構造体の要素
 128 .I reclen
 129 はレコードの長さを指定する。また、要素
 130 .I bval
 131 は埋め文字 (pad character) を指定する。
 132 .\"O Any records, inserted into the database, that are less than
 133 .\"O .I reclen
 134 .\"O bytes long are automatically padded.
 135 データベースに入れられたレコードの内
 136 .I reclen
 137 バイトに満たないものでは、残りの部分に埋め文字が自動的に入る。
 138 .TP
 139 .B R_NOKEY
 140 .\"O In the interface specified by
 141 .\"O .BR dbopen (3),
 142 .\"O the sequential record retrieval fills in both the caller's key and
 143 .\"O data structures.
 144 .BR dbopen (3)
 145 で指定されたインターフェイスでは、シーケンシャルなレコード取得は
 146 呼び出しキーとデータ構造体の両方を埋めていく。
 147 .\"O If the
 148 .\"O .B R_NOKEY
 149 .\"O flag is specified, the
 150 .\"O .I cursor
 151 .\"O routines are not required to fill in the key structure.
 152 .\"O This permits applications to retrieve records at the end of files without
 153 .\"O reading all of the intervening records.
 154 .B R_NOKEY
 155 フラグが指定されていると、キー構造体を埋めるのに
 156 .I cursor
 157 ルーチンを必要としない。
 158 これを用いれば、アプリケーションがファイルの終りの方を取得する際に、
 159 その途中のレコードを読まなくても済む事になる。
 160 .TP
 161 .B R_SNAPSHOT
 162 .\"O This flag requires that a snapshot of the file be taken when
 163 .\"O .BR dbopen (3)
 164 .\"O is called, instead of permitting any unmodified records to be read from
 165 .\"O the original file.
 166 このフラグを指定すると、
 167 .BR dbopen (3)
 168 の呼び出しの際、
 169 オリジナルファイルから変更されていないレコードを読む代わりに、
 170 ファイルの snapshot を用いる。
 171 .RE
 172 .TP
 173 .I cachesize
 174 .\"O A suggested maximum size, in bytes, of the memory cache.
 175 .\"O This value is
 176 .\"O .B only
 177 .\"O advisory, and the access method will allocate more memory rather than fail.
 178 .\"O If
 179 .\"O .I cachesize
 180 .\"O is  0 (no size is specified) a default cache is used.
 181 想定されるメモリキャッシュの最大サイズ (バイト単位)。
 182 この値は
 183 .B あくまで
 184 参考であり、アクセスメソッドはこの値を越えたメモリの
 185 割り当てに成功することもある。
 186 .I cachesize
 187 が 0 (あるいは指定されていない) の場合、デフォルトのキャッシュが使われる。
 188 .TP
 189 .I psize
 190 .\"O The recno access method stores the in-memory copies of its records
 191 .\"O in a btree.
 192 .\"O This value is the size (in bytes) of the pages used for nodes in that tree.
 193 recno アクセスメソッドは、自身のレコードのコピーをメモリ内部に
 194 btree で保存している。
 195 この値は、その btree 中のノードに対して用いられる
 196 ページサイズ (バイト単位) である。
 197 .\"O If
 198 .\"O .I psize
 199 .\"O is 0 (no page size is specified) a page size is chosen based on the
 200 .\"O underlying file system I/O block size.
 201 .\"O See
 202 .\"O .BR btree (3)
 203 .\"O for more information.
 204 .I psize
 205 が 0 (あるいは指定されていない) の場合、
 206 ファイルシステムの I/O ブロックサイズを基にして
 207 ページサイズが決められる。
 208 詳細は
 209 .BR btree (3)
 210 を参照。
 211 .TP
 212 .I lorder
 213 .\"O The byte order for integers in the stored database metadata.
 214 .\"O The number should represent the order as an integer; for example,
 215 .\"O big endian order would be the number 4,321.
 216 .\"O If
 217 .\"O .I lorder
 218 .\"O is 0 (no order is specified) the current host order is used.
 219 データベースに格納されているメタデータの整数値のバイトオーダー。
 220 この数字は、順序を整数で表したものである。
 221 例えばビッグエンディアンなら、この数値は 4,321 となる。
 222 .I lorder
 223 が 0 (指定されていない) の場合、現在のホスト
 224 で使われているバイトオーダーが使われる。
 225 .TP
 226 .I reclen
 227 .\"O The length of a fixed-length record.
 228 固定レコード長の長さ。
 229 .TP
 230 .I bval
 231 .\"O The delimiting byte to be used to mark the end of a record for
 232 .\"O variable-length records, and the pad character for fixed-length
 233 .\"O records.
 234 可変レコード長において、
 235 レコードの終りを示す区切りバイト (区切り文字) である。
 236 固定レコード長では埋め文字として使われる。
 237 .\"O If no value is specified, newlines ("\en") are used to mark the end
 238 .\"O of variable-length records and fixed-length records are padded with
 239 .\"O spaces.
 240 値が指定されていないと、
 241 可変レコード長のレコードの終りには改行 ("\en") が使われる。
 242 固定レコード長のレコードは空白 (space) で埋められる。
 243 .TP
 244 .I bfname
 245 .\"O The recno access method stores the in-memory copies of its records
 246 .\"O in a btree.
 247 .\"O If
 248 .\"O .I bfname
 249 .\"O is non-NULL, it specifies the name of the btree file,
 250 .\"O as if specified as the filename for a
 251 .\"O .BR dbopen (3)
 252 .\"O of a btree file.
 253 recno アクセスメソッドは、
 254 自身のレコードのコピーをメモリ内部で btree に保存している。
 255 .I bfname
 256 が NULL でない場合、これは btree ファイル名
 257 (btree ファイルを
 258 .BR dbopen (3)
 259 する時に指定するファイル名) を指定する。
 260 .PP
 261 .\"O The data part of the key/data pair used by the
 262 .\"O .I recno
 263 .\"O access method
 264 .\"O is the same as other access methods.
 265 .I recno
 266 アクセスメソッドで使われるキー/データ対のデータ部分は、
 267 他のアクセスメソッドと同じである。
 268 .\"O The key is different.
 269 .\"O The
 270 .\"O .I data
 271 .\"O field of the key should be a pointer to a memory location of type
 272 .\"O .IR recno_t ,
 273 .\"O as defined in the
 274 .\"O .I <db.h>
 275 .\"O include file.
 276 しかしキーは異なっている。
 277 キーの
 278 .I data
 279 フィールドは
 280 .I recno_t
 281 型の、メモリ位置へのポインタでなければならない。
 282 .I recno_t
 283 は
 284 .I <db.h>
 285 インクルードファイルで定義されている。
 286 .\"O This type is normally the largest unsigned integral type available to
 287 .\"O the implementation.
 288 この型は通常、その実装で利用可能な最大の符号無し整数である。
 289 .\"O The
 290 .\"O .I size
 291 .\"O field of the key should be the size of that type.
 292 キーの
 293 .I size
 294 フィールドはその型のサイズとなる。
 295 .PP
 296 .\"O Because there can be no metadata associated with the underlying
 297 .\"O recno access method files, any changes made to the default values
 298 .\"O (e.g., fixed record length or byte separator value) must be explicitly
 299 .\"O specified each time the file is opened.
 300 recno アクセスメソッドのファイルに関連づけられる
 301 メタデータは存在できないから、
 302 デフォルト値 (固定レコード長やセパレータ文字など)
 303 に対する変更はファイルを開く毎に明示的に指定しなければならない。
 304 .PP
 305 .\"O In the interface specified by
 306 .\"O .BR dbopen (3),
 307 .\"O using the
 308 .\"O .I put
 309 .\"O interface to create a new record will cause the creation of multiple,
 310 .\"O empty records if the record number is more than one greater than the
 311 .\"O largest record currently in the database.
 312 .BR dbopen (3)
 313 で指定されたインターフェイスでは、
 314 .I put
 315 インターフェイスを使って新しいレコードを作成するときに、
 316 指定したレコード番号がデータベース中に存在している最大レコード番号より
 317 一つ以上大きいと、
 318 空のレコードが同時にできてしまう。
 319 .SH エラー
 320 .\"O The
 321 .\"O .I recno
 322 .\"O access method routines may fail and set
 323 .\"O .I errno
 324 .\"O for any of the errors specified for the library routine
 325 .\"O .BR dbopen (3)
 326 .\"O or the following:
 327 .I recno
 328 アクセスメソッドルーチンは失敗すると
 329 .BR dbopen (3)
 330 で指定されているエラーに応じた
 331 .IR errno " か、"
 332 あるいは以下に示す
 333 .I errno
 334 をセットする。
 335 .TP
 336 .B EINVAL
 337 .\"O An attempt was made to add a record to a fixed-length database that
 338 .\"O was too large to fit.
 339 固定長データベースにレコードを追加するとき、データが長すぎた。
 340 .SH バグ
 341 .\"O Only big and little endian byte order is supported.
 342 バイトオーダーとしてはビッグエンディアンとリトルエンディアンのみが
 343 サポートされている。
 344 .SH 関連項目
 345 .BR btree (3),
 346 .BR dbopen (3),
 347 .BR hash (3),
 348 .BR mpool (3)
 349 .sp
 350 .IR "Document Processing in a Relational Database System" ,
 351 Michael Stonebraker, Heidi Stettner, Joseph Kalash, Antonin Guttman,
 352 Nadene Lynn, Memorandum No. UCB/ERL M82/32, May 1982.