.\" 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.
.\"
.\"	@(#)dbopen.3	8.5 (Berkeley) 1/2/94
.\" %FreeBSD: src/lib/libc/db/man/dbopen.3,v 1.3.2.2 2001/12/14 18:33:49 ru Exp %
.\" $FreeBSD$
.\"
.Dd January 2, 1994
.Dt DBOPEN 3
.Os
.Sh 名称
.Nm dbopen
.Nd データベースアクセス方式
.Sh 書式
.In sys/types.h
.In limits.h
.In db.h
.Ft DB *
.Fn dbopen "const char *file" "int flags" "int mode" "DBTYPE type" "const void *openinfo"
.Sh 解説
.Fn dbopen
は、データベースファイルへのライブラリインタフェースです。
サポートされているファイルフォーマットは、
btree
形式、ハッシュ形式、UNIX ファイル指向形式です。
btree
フォーマットは、ソート済みのバランスのとれた
ツリー構造の表現です。ハッシュフォーマットは、拡張可能で動的な
ハッシュスキーマです。フラットファイルフォーマットは、固定長または可変長
レコードからなるバイトストリームファイルです。フォーマットおよび
ファイルフォーマットに固有の情報については、それぞれのマニュアルページに
詳しく述べられています。
.Xr btree 3 ,
.Xr hash 3 ,
.Xr recno 3
です。
.Pp
.Fn dbopen
は、読み込みまたは書き込み用に
.Fa file
をオープンします。ディスク上に保持する必要のないファイルは、
ファイルパラメータを
.Dv NULL
に設定することで作成できます。
.Pp
引数
.Fa flags
と引数
.Fa mode
は、
.Xr open 2
で指定されものと同じです。しかし、
.Dv O_CREAT , O_EXCL , O_EXLOCK , O_NONBLOCK ,
.Dv O_RDONLY , O_RDWR , O_SHLOCK ,
.Dv O_TRUNC
の各フラグだけに意味があります (データベースファイルは
.Dv O_WRONLY
では
オープンできないことに注意してください)。
.\"Three additional options may be specified by
.\".Em or Ns 'ing
.\"them into the
.\".Fa flags
.\"argument.
.\".Bl -tag -width indent
.\".It Dv DB_LOCK
.\"Do the necessary locking in the database to support concurrent access.
.\"If concurrent access isn't needed or the database is read-only this
.\"flag should not be set, as it tends to have an associated performance
.\"penalty.
.\".It Dv DB_SHMEM
.\"Place the underlying memory pool used by the database in shared
.\"memory.
.\"Necessary for concurrent access.
.\".It Dv DB_TXN
.\"Support transactions in the database.
.\"The
.\".Dv DB_LOCK
.\"and
.\".Dv DB_SHMEM
.\"flags must be set as well.
.\".El
.Pp
引数
.Fa type
は、タイプ
.Ft DBTYPE
(インクルードファイル
.Aq Pa db.h
で定義されています)
であり、
.Dv DB_BTREE ,
.Dv DB_HASH ,
.Dv DB_RECNO
を設定できます。
.Pp
引数
.Fa openinfo
は、アクセス方式のマニュアルページに説明してあるように、
アクセス方式に固有の構造を指すポインタです。
.Fa openinfo
が
.Dv NULL
の場合、各アクセス方式は、システムとアクセス方式に
適切なデフォルトを使用します。
.Pp
.Fn dbopen
は、処理が成功すると
.Ft DB
構造体を指すポインタを返し、
エラーの場合にはヌルを返します。
.Ft DB
構造体は、インクルードファイル
.Aq Pa db.h
内に定義されており、
少なくとも次のフィールドが含まれています。
.Bd -literal
typedef struct {
	DBTYPE type;
	int (*close)(const DB *db);
	int (*del)(const DB *db, const DBT *key, u_int flags);
	int (*fd)(const DB *db);
	int (*get)(const DB *db, DBT *key, DBT *data, u_int flags);
	int (*put)(const DB *db, DBT *key, const DBT *data,
	     u_int flags);
	int (*sync)(const DB *db, u_int flags);
	int (*seq)(const DB *db, DBT *key, DBT *data, u_int flags);
} DB;
.Ed
.Pp
これらの要素は、データベースタイプと各種のアクションを実行する
関数のセットを記述しています。これらの関数は、
.Fn dbopen
によって返された構造体へのポインタを引数に取り、
時々キー / データ構造とフラグ値を指す 1 つまたは複数のポインタを
取ることもあります。
.Bl -tag -width indent
.It Va type
基本アクセス方式 (およびファイルフォーマット) のタイプ。
.It Va close
キャッシュされた情報をディスクにフラッシュし、割り振られたリソースを
解放し、基になっているファイル (1 つまたは複数) を閉じるルーチンを指す
ポインタ。キー / データの組はメモリにキャッシュされるので、ファイルを
.Va close
関数または
.Va sync
関数でファイルを同期するのに失敗すると、情報に矛盾や欠落が
生じるかもしれません。
.Va close
ルーチンは、エラー終了時には -1 を返し (
.Va errno
を設定)、
正常終了時には 0 を返します。
.It Va del
キー / データの組をデータベースから削除するルーチンを指すポインタ。
.Pp
パラメータ
.Fa flags
は次の値に設定できます。
.Bl -tag -width indent
.It Dv R_CURSOR
カーソルが参照するレコードを削除します。カーソルは、
あらかじめ初期化しておく必要があります。
.El
.Pp
.Va delete
ルーチンはエラー終了時には -1 を返し (
.Va errno
を設定)、
正常終了時には 0 を返します。指定した
.Fa key
がファイルの中になかった場合は 1 を返します。
.It Va fd
基本データベースのファイル記述表現を返すルーチンを指すポインタ。
同じファイルを参照しているファイル記述子は、同じ
.Fa file
名で
.Fn dbopen
を呼び出す全プロセスに返されます。このファイル記述子は、ロック関数
.Xr fcntl 2
と
.Xr flock 2
への引数として安全に使用できます。
ファイル記述子は、必ずしもアクセス方式が使用している基本ファイルに
関連付けられている必要はありません。ファイル記述子は
メモリデータベース内で利用できません。
.Va \&fd
ルーチンは、エラー終了時は -1 を返し (
.Va errno
を設定)、
正常終了時にはファイル記述子を返します。
.It Va get
データベースからキーを使用して取り出すインタフェースである
ルーチンを指すポインタ。指定の
.Fa key
に関連付けられたデータのアドレスと長さが、
.Fa data
で参照される構造体内に返されます。
.Va get
ルーチンはエラー終了時には -1 を返し (
.Va errno
を設定)、
正常終了時には 0 を返します。
.Fa key
がファイルの中になかった場合は 1 を返します。
.It Va put
キー / データの組をデータベース内に保存するルーチンを指すポインタ。
.Pp
パラメータ
.Fa flags
には次の値の 1 つを設定できます。
.Bl -tag -width indent
.It Dv R_CURSOR
カーソルが参照するキー / データの組を置き換えます。カーソルは、
あらかじめ初期化されている必要があります。
.It Dv R_IAFTER
.Fa key
で参照されるデータの直後にデータを追加し、
新しいキー / データの組を作成します。追加したキー / データの組のレコード番号が
.Fa key
構造体内に返されます (
.Dv DB_RECNO
アクセス方式にだけ適用できます)。
.It Dv R_IBEFORE
.Fa key
で参照されるデータの直前にデータを挿入し、
新しいキー / データの組を作成します。追加したキー / データの組のレコード番号が
.Fa key
構造体内に返されます (
.Dv DB_RECNO
アクセス方式にだけ適用できます)。
.It Dv R_NOOVERWRITE
キーがそれ以前に存在しない場合にだけ、新しいキー / データの組を入力します。
.It Dv R_SETCURSOR
キー / データの組を保存し、それを参照するカーソルの位置をセット、または
初期化します (
.Dv DB_BTREE
および
.Dv DB_RECNO
アクセス方式にだけ適用できます)。
.El
.Pp
.Dv R_SETCURSOR
が利用できるのは、
.Dv DB_BTREE
と
.Dv DB_RECNO
のアクセス方式でだけです。
キーには、変化しない固有の順序があることを意味しているからです。
.Pp
.Dv R_IAFTER
と
.Dv R_IBEFORE
は
.Dv DB_RECNO
アクセス方式にだけ利用できます。
どれも、アクセス方式が新しいキーを作成できることを意味しているからです。
これは、キーが順序付けられており独立な場合にだけ真となります。
たとえば、レコード番号です。
.Pp
.Va put
ルーチンのデフォルトの動作は、新しいキー/データの組を入力し、
それ以前に存在していたキーを置き換えることです。
.Pp
.Va put
ルーチンはエラー終了時には -1 を返し (
.Va errno
を設定)、
正常終了時には 0 を返し、
.Dv R_NOOVERWRITE
フラグが設定されていて、しかもキーがファイル内に
既に存在する場合は 1 を返します。
.It Va seq
データベースからのシーケンシャルな取り出し用インタフェースである
ルーチンを指すポインタ。キーのアドレスと長さは
.Fa key
が参照する構造体内に返され、データのアドレスと長さは
.Fa data
が参照する構造体内に返されます。
.Pp
シーケンシャルなキー / データの組の取り出しは、いつでも開始することができ、
.Dq カーソル
の位置は
.Va del ,
.Va get ,
.Va put ,
.Va sync
の各ルーチンによる呼び出しによって影響を受けません。
シーケンシャルな走査の間のデータベースの修正は走査に反映されます。
すなわち、カーソルの前に挿入されたレコードが返されるまでの間、
カーソルの後ろに挿入されたレコードは返されません。
.Pp
.Fa flags
値は次の値の 1 つにセットしなければ
.Em なりません
。
.Bl -tag -width indent
.It Dv R_CURSOR
指定のキーに関連付けられたデータが返されます。これはカーソルをキーの位置に
セットまたは初期化するという点で
.Va get
ルーチンと異なります (
.Dv DB_BTREE
アクセス方式の場合、返されたキーは必ずしも指定のキーと正確に一致する
必要がないことに注意してください。返されるキーは、指定のキーより
大きいかまたは等しいような、最小のキーであり、
部分的なキー一致と範囲検索ができます)。
.It Dv R_FIRST
データベースの最初のキー / データの組が返され、カーソルはそれを
参照するようにセットまたは初期化されます。
.It Dv R_LAST
データベースの最後のキー / データの組が返され、カーソルはそれを
参照するようにセットまたは初期化されます (
.Dv DB_BTREE
と
.Dv DB_RECNO
の各アクセス方式にだけ適用できます)。
.It Dv R_NEXT
カーソルの直後にあるキー / データの組を取り出します。カーソルがまだ
セットされていない場合は、これは
.Dv R_FIRST
フラグと同じになります。
.It Dv R_PREV
カーソルの直前にあるキー / データの組を取り出します。カーソルがまだ
設定されていない場合には、これは
.Dv R_LAST
フラグと同じになります。(
.Dv DB_BTREE
と
.Dv DB_RECNO
の各アクセス方式にだけ適用できます)。
.El
.Pp
.Dv R_LAST
と
.Dv R_PREV
が利用できるのは、
.Dv DB_BTREE
と
.Dv DB_RECNO
の各
アクセス方式についてだけです。これらはそれぞれキーに変化しない固有の
順序があることを意味しているからです。
.Pp
.Va seq
ルーチンはエラー終了時には -1 を返し (
.Va errno
を設定)、
正常終了時には 0 を返し、指定のキーまたは現在のキーより小さいかまたは
大きいキー / データの組が存在しない場合は 1 を返します。
.Dv DB_RECNO
アクセス方式が使用されていて、
しかもデータベースファイルがキャラクタ特殊ファイルであり、
完全なキー / データの組がその時点で存在しない場合、
.Va seq
ルーチンは 2 を返します。
.It Va sync
キャッシュされた情報をディスクにフラッシュするルーチンを指すポインタ。
データベースがメモリ内にだけ存在する場合、
.Va sync
ルーチンには何の効果もなく、処理は常に正常終了します。
.Pp
.Fa flags
値は次の値にセットできます。
.Bl -tag -width indent
.It Dv R_RECNOSYNC
.Dv DB_RECNO
アクセス方式が使用される場合、このフラグは
.Va sync
ルーチンが、
.Va recno
ファイル自身ではなく、
recno
ファイルの基となる
btree
ファイルに適用されるようにします (詳細については
.Xr recno 3
マニュアルページの
.Va bfname
フィールドを参照してください)。
.El
.Pp
.Va sync
ルーチンはエラー終了時には -1 を返し (
.Va errno
を設定)、
正常終了時には 0 を返します。
.El
.Sh キー / データの組
すべてのファイルタイプへのアクセスはキー / データの組を基にしています。
キーとデータの両方が次のデータ構造で表されます。
.Bd -literal
typedef struct {
	void *data;
	size_t size;
} DBT;
.Ed
.Pp
.Ft DBT
構造体の要素は次のように定義されます。
.Bl -tag -width "data"
.It Va data
バイトストリングを指すポインタ。
.It Va size
バイトストリングの長さ。
.El
.Pp
キーとデータバイトストリングは、同時に利用できるメモリにフィットする必要
はありますが、参照できる文字列の長さには本質的には制限がありません。
アクセス方式は、バイトストリングのバイトアラインについては
何の保証もしていないことに注意すべきです。
.Sh エラー
.Fn dbopen
ルーチンがエラー終了すると、ライブラリルーチン
.Xr open 2
や
.Xr malloc 3
で書かれているエラー、または下記のエラーに対する
.Va errno
をセットします。
.Bl -tag -width Er
.It Bq Er EFTYPE
ファイルのフォーマットが間違っています。
.It Bq Er EINVAL
既存のファイル指定と互換性のないパラメータ (ハッシュ関数、
パッドバイトなど) や、関数に意味のないパラメータが指定された (たとえば、
事前の初期化が行なわれていないカーソルの使用)、
またはファイルとソフトウェアのバージョン間に不一致があります。
.El
.Pp
.Va close
ルーチンがエラー終了すると、ライブラリルーチン
.Xr close 2 ,
.Xr read 2 ,
.Xr write 2 ,
.Xr free 3 ,
.Xr fsync 2
に書かれているエラーについての
.Va errno
をセットします。
.Pp
.Va del ,
.Va get ,
.Va put ,
.Va seq
の各ルーチンがエラー終了すると、ライブラリルーチン
.Xr read 2 ,
.Xr write 2 ,
.Xr free 3 ,
.Xr malloc 3
に書かれているエラーについての
.Va errno
をセットします。
.Pp
.Va fd
ルーチンは、メモリ内のデータベースでエラー終了すると、
.Er ENOENT
に
.Va errno
をセットします。
.Pp
.Va sync
ルーチンがエラー終了すると、ライブラリルーチン
.Xr fsync 2
に書かれているエラーについての
.Va errno
をセットします。
.Sh 関連項目
.Xr btree 3 ,
.Xr hash 3 ,
.Xr mpool 3 ,
.Xr recno 3
.Rs
.%T "LIBTP: Portable, Modular Transactions for UNIX"
.%A Margo Seltzer
.%A Michael Olson
.%R "USENIX proceedings"
.%D Winter 1992
.Re
.Sh バグ
typedef
.Ft DBTs
は、
.Dq "data base thang"
の略称で、
まだ使用されていない合理的な名前を誰も思いつかなかったために
使われることになりました。
.Pp
ファイル記述子インタフェースは構成が調和しておらず、
インタフェースの今後のバージョンでは削除される予定です。
.Pp
どのアクセス方式も、並行アクセス、ロック、またはトランザクション
は、どのような形式でも提供しません。