.\" Copyright (c) 1990, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	@(#)recno.3	8.5 (Berkeley) 8/18/94
.\" %FreeBSD: src/lib/libc/db/man/recno.3,v 1.4.2.2 2001/12/14 18:33:49 ru Exp %
.\" $FreeBSD$
.\"
.Dd August 18, 1994
.Dt RECNO 3
.Os
.Sh 名称
.Nm recno
.Nd レコード番号データベースへのアクセス手法
.Sh 書式
.In sys/types.h
.In db.h
.Sh 解説
.Fn dbopen
ルーチンは、データベースファイルのライブラリインタフェース
ですが、そこでサポートされているファイルフォーマットの 1 つに、
レコード番号ファイルがあります。データベースアクセス手法の一般事項については、
.Xr dbopen 3
を参照してください。このマニュアルページでは、
.Nm
の固有事項について
説明します。
.Pp
レコード番号データ構造は、フラットファイルフォーマットで保存された、
可変長あるいは固定長のレコードで、論理レコード番号でアクセスされます。
レコード番号 5 が存在するということは、レコード 1 からレコード 4 が
存在することになります。レコード番号 1 を削除すると、レコード番号 5 は
レコード番号 4 になり、レコード番号 1 の後ろを指していたカーソルは、
1 レコード下にシフトします。
.Pp
.Fn dbopen
で提供される
.Nm
へのアクセス手法に固有なデータ構造は、
.Aq Pa db.h
インクルードファイルで以下のように定義されています。
.Bd -literal
typedef struct {
	u_long flags;
	u_int cachesize;
	u_int psize;
	int lorder;
	size_t reclen;
	u_char bval;
	char *bfname;
} RECNOINFO;
.Ed
.Pp
この構造体のエレメントは、以下のように定義されます。
.Bl -tag -width indent
.It Va flags
フラグ値は、以下の値の論理和 (
.Em or
) を取ることで指定されます。
.Bl -tag -width indent
.It Dv R_FIXEDLEN
レコードは固定長で、バイトで区切られていません。
構造体のエレメント
.Va reclen
がレコードの長さを指定し、構造体のエレメント
.Va bval
がパッドキャラクタとして使用されます。データベースに挿入された
レコードは、
.Va reclen
バイトより小さい場合、自動的にパッドされます。
.It Dv R_NOKEY
.Fn dbopen
が指定するインタフェースでは、
シーケンシャルレコード検索で、呼び出し側のキーとデータ構造の両方にデータが
入ります。
.Dv R_NOKEY
フラグを指定すると、
.Em cursor
ルーチンがなくてもキー構造に
データが入ります。これにより、アプリケーションは、中間に存在するレコード
すべてを読み込まずに、ファイルの最後のレコードを取り出せます。
.It Dv R_SNAPSHOT
このフラグは、修正されていないレコードを
オリジナルファイルから読み込む代わりに、
.Fn dbopen
が呼び出された場合にファイル
のスナップショットを取ることを要求します。
.El
.It Va cachesize
メモリキャッシュの最大サイズ (バイト単位) です。この値は
.Em 参考程度のもの
で、アクセス手法はエラーにならずにこれ以上のメモリを割り
振ります。
.Va cachesize
を 0 にすると (サイズを指定しないと)、デフォルトの
キャッシュが使用されます。
.It Va psize
.Nm
へのアクセス手法は、レコードのメモリのコピーを btree に
保存します。
この値は、そのツリーのノードで使用されるページのサイズ (バイト単位) です。
.Va psize
が 0 である場合は (ページサイズが指定されていない場合は)、
基礎となるファイルシステムの I/O ブロックサイズに従って
ページサイズが選択されます。詳細については、
.Xr btree 3
を参照してください。
.It Va lorder
保存されているデータベースメタデータの整数のバイトオーダ
です。整数のオーダを数値で表現する必要があります。たとえば
ビッグエンディアンのばバイトオーダは、4321 の順番になります。
.Va lorder
が 0 である場合は、(オーダが指定されていない場合は)、
現行ホストのオーダが使用されます。
.It Va reclen
固定長レコードの長さです。
.It Va bval
可変長レコードの場合は、レコードの終わりをマークする区切り
バイトで、固定長レコードの場合は、パッドキャラクタです。値を指定しないと、
可変長レコードの最後は改行
.Pq Dq \en
でマークされ、
固定長レコードはスペースでパッドされます。
.It Va bfname
.Nm
アクセス手法は、レコードのメモリのコピーを btree に保存します。
.Dv NULL
以外の
.Va bfname
は、btree ファイルの
.Fn dbopen
の
ファイル名として指定されたかのように、btree ファイルの名前を指定します。
.El
.Pp
.Nm
へのアクセス手法で使用するキーとデータのペアのデータ部分は、その
他のアクセス手法と同じですが、キーは異なります。キーの
.Va data
フィールドは、
.Aq Pa db.h
インクルードファイルで定義された、タイプ
.Ft recno_t
のメモリ位置を指す
ポインタでなければなりません。通常の場合、このタイプは、システムで
使用できる最大の符号なし整数タイプです。キーの
.Va size
フィールドは、そのタイプのサイズである必要があります。
.Pp
基礎となる
.Nm
アクセス手法ファイルでは、メタデータを
関連付けられないので、デフォルト値に対する変更内容 (たとえばレコードの
固定長やバイト区切り値) は、ファイルを開くたびに明確に指定する
必要があります。
.Pp
.Fn dbopen
が指定するインタフェースでは、
.Va put
インタフェースを使用して
新しいレコードを作成すると、レコード番号が、現在のデータベースの最大
レコードより 1 以上大きい場合、複数の空のレコードが作成されます。
.Sh エラー
.Nm
アクセス手法ルーチンがエラーになると、ライブラリルーチン
.Xr dbopen 3
に指定されたエラーか以下のエラーに
.Va errno
が設定されます。
.Bl -tag -width Er
.It Bq Er EINVAL
固定長データベースに、大きすぎるレコードを
追加しようとしました。
.El
.Sh 関連項目
.Xr btree 3 ,
.Xr dbopen 3 ,
.Xr hash 3 ,
.Xr mpool 3
.Rs
.%T "Document Processing in a Relational Database System"
.%A Michael Stonebraker
.%A Heidi Stettner
.%A Joseph Kalash
.%A Antonin Guttman
.%A Nadene Lynn
.%R "Memorandum No. UCB/ERL M82/32"
.%D May 1982
.Re
.Sh バグ
ビッグエンディアンのバイトオーダとリトルエンディアンのバイトオーダのみ
がサポートされています。