diff options
Diffstat (limited to 'documentation/manual-pages/ja/man3/dbopen.3')
| -rw-r--r-- | documentation/manual-pages/ja/man3/dbopen.3 | 521 |
1 files changed, 521 insertions, 0 deletions
diff --git a/documentation/manual-pages/ja/man3/dbopen.3 b/documentation/manual-pages/ja/man3/dbopen.3 new file mode 100644 index 0000000000..972bf293ab --- /dev/null +++ b/documentation/manual-pages/ja/man3/dbopen.3 @@ -0,0 +1,521 @@ +.\" 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 +どのアクセス方式も、並行アクセス、ロック、またはトランザクション +は、どのような形式でも提供しません。 |