X-Git-Url: http://git.osdn.net/view?a=blobdiff_plain;f=release%2Fman3%2Fhsearch.3;h=ebb47eb51dbbb491eef070661f198b197acdb430;hb=4fa3e54b837e5814a4598ec901d77446bf5cb9b3;hp=e3d037a67345bb473489ac6e073f7cda9e4d6b1b;hpb=ce024239a1d8e74a7a44f7c24cee4375cb13b3ef;p=linuxjm%2FLDP_man-pages.git diff --git a/release/man3/hsearch.3 b/release/man3/hsearch.3 index e3d037a6..ebb47eb5 100644 --- a/release/man3/hsearch.3 +++ b/release/man3/hsearch.3 @@ -32,115 +32,63 @@ .\" 2008-09-03, mtk, restructured somewhat, in part after suggestions from .\" Timothy S. Nelson .\" -.\" Japanese Version Copyright (c) 1998 George Momma, -.\" Copyright (c) 2001-2005 Yuichi SATO, -.\" and Copyright (c) 2008 Akihiro MOTOKI -.\" Translated 1998-05-23, George Momma -.\" Updated & Modified 2001-10-15, Yuichi SATO -.\" Updated & Modified 2002-01-03, Yuichi SATO -.\" Updated & Modified 2004-01-17, Yuichi SATO -.\" Updated & Modified 2005-01-10, Yuichi SATO -.\" Updated 2008-09-20, Akihiro MOTOKI +.\"******************************************************************* .\" -.\"WORD: hash table ハッシュテーブル -.\"WORD: entry エントリー -.\"WORD: allocate 割り当て -.\"WORD: NUL-terminated ヌル文字 \0 で終端された -.\"WORD: pointer ポインタ -.\"WORD: character 文字型 -.\"WORD: item 項目 +.\" This file was generated with po4a. Translate the source file. .\" -.TH HSEARCH 3 2011-09-10 "GNU" "Linux Programmer's Manual" +.\"******************************************************************* +.TH HSEARCH 3 2011\-09\-10 GNU "Linux Programmer's Manual" .SH 名前 -hcreate, hdestroy, hsearch, hcreate_r, hdestroy_r, -hsearch_r \- ハッシュテーブルの管理 +hcreate, hdestroy, hsearch, hcreate_r, hdestroy_r, hsearch_r \- ハッシュテーブルの管理 .SH 書式 .nf -.B #include +\fB#include \fP .sp -.BI "int hcreate(size_t " nel ); +\fBint hcreate(size_t \fP\fInel\fP\fB);\fP .sp -.BI "ENTRY *hsearch(ENTRY " item ", ACTION " action ); +\fBENTRY *hsearch(ENTRY \fP\fIitem\fP\fB, ACTION \fP\fIaction\fP\fB);\fP .sp -.B "void hdestroy(void);" +\fBvoid hdestroy(void);\fP .sp -.BR "#define _GNU_SOURCE" " /* feature_test_macros(7) 参照 */" +\fB#define _GNU_SOURCE\fP /* feature_test_macros(7) 参照 */ .br -.B #include +\fB#include \fP .sp -.BI "int hcreate_r(size_t " nel ", struct hsearch_data *" htab ); +\fBint hcreate_r(size_t \fP\fInel\fP\fB, struct hsearch_data *\fP\fIhtab\fP\fB);\fP .sp -.BI "int hsearch_r(ENTRY " item ", ACTION " action ", ENTRY **" retval , -.BI " struct hsearch_data *" htab ); +\fBint hsearch_r(ENTRY \fP\fIitem\fP\fB, ACTION \fP\fIaction\fP\fB, ENTRY **\fP\fIretval\fP\fB,\fP +\fB struct hsearch_data *\fP\fIhtab\fP\fB);\fP .sp -.BI "void hdestroy_r(struct hsearch_data *" htab ); +\fBvoid hdestroy_r(struct hsearch_data *\fP\fIhtab\fP\fB);\fP .fi .SH 説明 -.BR hcreate (), -.BR hsearch (), -.BR hdestroy () -の 3 つの関数を利用すると、キー (文字列) と対応するデータから構成される -エントリを格納できるハッシュ検索テーブルを作成、管理することができる。 +\fBhcreate\fP(), \fBhsearch\fP(), \fBhdestroy\fP() の 3 つの関数を利用すると、キー (文字列) +と対応するデータから構成される エントリを格納できるハッシュ検索テーブルを作成、管理することができる。 これらの関数を使って、一度に使用できるのは一つのハッシュテーブルだけである。 -.BR hcreate_r (), -.BR hsearch_r (), -.BR hdestroy_r () -の 3 つの関数はリエントラント版で、これらを利用すると、 -一つのプログラムで同時に複数のハッシュテーブルを使うことができる。 -最後の引き数 -.I htab -は関数の操作対象となるテーブルを示す構造体へのポインタである。 -プログラマはこの構造体をブラックボックスとして扱うべきである -(つまり、この構造体のフィールドに直接アクセスしたり変更したり -しないこと)。 +\fBhcreate_r\fP(), \fBhsearch_r\fP(), \fBhdestroy_r\fP() の 3 +つの関数はリエントラント版で、これらを利用すると、 一つのプログラムで同時に複数のハッシュテーブルを使うことができる。 最後の引き数 \fIhtab\fP +は関数の操作対象となるテーブルを示す構造体へのポインタである。 プログラマはこの構造体をブラックボックスとして扱うべきである +(つまり、この構造体のフィールドに直接アクセスしたり変更したり しないこと)。 -最初に、 -.BR hcreate () -関数によってハッシュテーブルを作成しなければならない。 -引き数 \fInel\fP でテーブルの最大エントリ数を指定する -(この最大値は後で変更することはできないので、よく考えて選択すること)。 -作成されるハッシュテーブルの性能を向上させるために、 -関数内部の実装によりこの値は増やされる場合もある。 .\" e.g., in glibc it is raised to the next higher prime number +最初に、 \fBhcreate\fP() 関数によってハッシュテーブルを作成しなければならない。 引き数 \fInel\fP でテーブルの最大エントリ数を指定する +(この最大値は後で変更することはできないので、よく考えて選択すること)。 作成されるハッシュテーブルの性能を向上させるために、 +関数内部の実装によりこの値は増やされる場合もある。 -.BR hcreate_r () -関数は -.BR hcreate () -と同じ動作をするが、構造体 -.I *htab -で示されるテーブルを対象として動作する。 -.I htab -が指し示す構造体は、 -.BR hcreate_r () -を初めて呼び出す前に 0 で埋めておかなければならない。 +\fBhcreate_r\fP() 関数は \fBhcreate\fP() と同じ動作をするが、構造体 \fI*htab\fP +で示されるテーブルを対象として動作する。 \fIhtab\fP が指し示す構造体は、 \fBhcreate_r\fP() を初めて呼び出す前に 0 +で埋めておかなければならない。 -.BR hdestroy () -関数は、 -.BR hcreate () -で作成されたハッシュテーブルが占有していたメモリを解放する。 -ハッシュテーブルによって占有されていたメモリを解放し、 -新しいテーブルを作成できるようにする。 -.BR hdestroy () -を呼び出すと、その後は -.BR hcreate () -を使って新しいハッシュテーブルを作成することができる。 -.BR hdestroy_r () -関数は、同様の処理を、それ以前に -.BR hcreate_r () -を使って作成した -.I *htab -で示されるハッシュテーブルに対して実行する。 +\fBhdestroy\fP() 関数は、 \fBhcreate\fP() で作成されたハッシュテーブルが占有していたメモリを解放する。 +ハッシュテーブルによって占有されていたメモリを解放し、 新しいテーブルを作成できるようにする。 \fBhdestroy\fP() を呼び出すと、その後は +\fBhcreate\fP() を使って新しいハッシュテーブルを作成することができる。 \fBhdestroy_r\fP() 関数は、同様の処理を、それ以前に +\fBhcreate_r\fP() を使って作成した \fI*htab\fP で示されるハッシュテーブルに対して実行する。 -.BR hsearch () -関数は、\fIitem\fP と同じキーを持つ項目をハッシュテーブルから -検索し、項目が見つかった場合にはその項目へのポインタを返す -(「同じ」かどうかは -.BR strcmp (3) -を使って判定する)。 +\fBhsearch\fP() 関数は、\fIitem\fP と同じキーを持つ項目をハッシュテーブルから +検索し、項目が見つかった場合にはその項目へのポインタを返す (「同じ」かどうかは \fBstrcmp\fP(3) を使って判定する)。 -引き数 \fIitem\fP は \fBENTRY\fP 型であり、\fI\fP の中で -以下のように定義されている。 +引き数 \fIitem\fP は \fBENTRY\fP 型であり、\fI\fP の中で 以下のように定義されている。 .in +4n .sp .nf @@ -151,145 +99,60 @@ typedef struct entry { .in .fi .sp -フィールド \fIkey\fP は検索キーとなる NULL 終端された文字列を指す。 -フィールド \fIdata\fP は、このキーに対応するデータを指す。 +フィールド \fIkey\fP は検索キーとなる NULL 終端された文字列を指す。 フィールド \fIdata\fP は、このキーに対応するデータを指す。 -検索が失敗した後の動作は、引き数 \fIaction\fP により決まる。 -この引き数には -.B ENTER -か -.B FIND -のいずれかの値を指定しなければならない。 -.B ENTER -は -.I item -のコピーを挿入することを -(関数の結果として新しいハッシュテーブルエントリへのポインタを返す)、 -.B FIND -は NULL を返すことを意味する -.RI ( action -が -.B FIND -の場合、 -.I data -は無視される)。 +検索が失敗した後の動作は、引き数 \fIaction\fP により決まる。 この引き数には \fBENTER\fP か \fBFIND\fP +のいずれかの値を指定しなければならない。 \fBENTER\fP は \fIitem\fP のコピーを挿入することを +(関数の結果として新しいハッシュテーブルエントリへのポインタを返す)、 \fBFIND\fP は NULL を返すことを意味する (\fIaction\fP が +\fBFIND\fP の場合、 \fIdata\fP は無視される)。 -.BR hsearch_r () -関数は -.BR hsearch () -と同様だが、 -.I *htab -で示されるハッシュテーブルに対して処理を行う。 -.BR hsearch_r () -関数が -.BR hsearch () -と異なるのは、見つかった項目へのポインタを、 -関数の結果としてではなく、 -.I *retval -に格納して返す点である。 +\fBhsearch_r\fP() 関数は \fBhsearch\fP() と同様だが、 \fI*htab\fP で示されるハッシュテーブルに対して処理を行う。 +\fBhsearch_r\fP() 関数が \fBhsearch\fP() と異なるのは、見つかった項目へのポインタを、 関数の結果としてではなく、 +\fI*retval\fP に格納して返す点である。 .SH 返り値 -.BR hcreate () -と -.BR hcreate_r () -は、成功した場合 0 以外の値を返し、 -エラーの場合 0 を返す。 +\fBhcreate\fP() と \fBhcreate_r\fP() は、成功した場合 0 以外の値を返し、 エラーの場合 0 を返す。 -成功すると、 -.BR hsearch () -は、ハッシュテーブル内のエントリへのポインタを返す。 -エラーの場合、 -.BR hsearch () -は NULL を返す。 -エラーとなるのは、 -\fIaction\fP が \fBENTER\fP でハッシュテーブルがいっぱいの場合か、 -\fIaction\fP が \fBFIND\fP で \fIitem\fP がハッシュテーブル内に -見つからない場合である。 -.BR hsearch_r () -は、成功すると 0 以外を返し、エラーの場合 0 を返す。 +成功すると、 \fBhsearch\fP() は、ハッシュテーブル内のエントリへのポインタを返す。 エラーの場合、 \fBhsearch\fP() は NULL +を返す。 エラーとなるのは、 \fIaction\fP が \fBENTER\fP でハッシュテーブルがいっぱいの場合か、 \fIaction\fP が \fBFIND\fP +で \fIitem\fP がハッシュテーブル内に 見つからない場合である。 \fBhsearch_r\fP() は、成功すると 0 以外を返し、エラーの場合 0 +を返す。 .SH エラー .LP -.BR hcreate_r () -と -.BR hdestroy_r () -は以下の理由で失敗する可能性がある。 -.TP -.B EINVAL -.I htab -が NULL である。 +\fBhcreate_r\fP() と \fBhdestroy_r\fP() は以下の理由で失敗する可能性がある。 +.TP +\fBEINVAL\fP +\fIhtab\fP が NULL である。 .PP -.BR hsearch () -と -.BR hsearch_r () -は以下の理由で失敗する可能性がある。 -.TP -.B ENOMEM -.I action -が -.B ENTER -で、 -.I key -がテーブル内に見つからず、 -テーブルに新しいエントリを追加する余地がなかった。 -.TP -.B ESRCH -.I action -が -.B FIND -で、 -.I key -がテーブル内に見つからなかった。 +\fBhsearch\fP() と \fBhsearch_r\fP() は以下の理由で失敗する可能性がある。 +.TP +\fBENOMEM\fP +\fIaction\fP が \fBENTER\fP で、 \fIkey\fP がテーブル内に見つからず、 テーブルに新しいエントリを追加する余地がなかった。 +.TP +\fBESRCH\fP +\fIaction\fP が \fBFIND\fP で、 \fIkey\fP がテーブル内に見つからなかった。 .PP -POSIX.1-2001 が規定しているのは、エラー -.B ENOMEM -だけである。 +POSIX.1\-2001 が規定しているのは、エラー \fBENOMEM\fP だけである。 .SH 準拠 -関数 -.BR hcreate (), -.BR hsearch (), -.BR hdestroy () -は SVr4 から導入されたもので、POSIX.1-2001 に記述されている。 -関数 -.BR hcreate_r , -.BR hsearch_r , -.B hdestroy_r -は GNU の拡張である。 +関数 \fBhcreate\fP(), \fBhsearch\fP(), \fBhdestroy\fP() は SVr4 から導入されたもので、POSIX.1\-2001 +に記述されている。 関数 \fBhcreate_r\fP, \fBhsearch_r\fP, \fBhdestroy_r\fP は GNU の拡張である。 .SH 注意 -通常、ハッシュテーブルの実装は、衝突を最小限にするために -テーブルに十分な空き領域がある場合に効率がよくなる。 -このため、普通は、 -.I nel -を、呼び出し側がテーブルに格納しようと思っている -エントリの最大数より少なくとも 25% は大きな値にすべきである。 +通常、ハッシュテーブルの実装は、衝突を最小限にするために テーブルに十分な空き領域がある場合に効率がよくなる。 このため、普通は、 \fInel\fP +を、呼び出し側がテーブルに格納しようと思っている エントリの最大数より少なくとも 25% は大きな値にすべきである。 -.BR hdestroy () -と -.BR hdestroy_r () -は、ハッシュテーブルのエントリの要素である -.I key -と -.I data -が指すバッファを解放しない -(これができないのは、これらのバッファが動的に割り当てられたのかを -知ることができないからである)。 -これらのバッファを解放する必要がある場合、 -プログラムでは、これらのバッファを解放できるように管理用のデータ構造を -設けて、これを管理しなければならない -(解放が必要となる理由は、たいていは、プログラム自身と生存期間が同じ -ハッシュテーブルを一つだけ作成するのではなく、そのプログラムでは複数の +\fBhdestroy\fP() と \fBhdestroy_r\fP() は、ハッシュテーブルのエントリの要素である \fIkey\fP と \fIdata\fP +が指すバッファを解放しない (これができないのは、これらのバッファが動的に割り当てられたのかを 知ることができないからである)。 +これらのバッファを解放する必要がある場合、 プログラムでは、これらのバッファを解放できるように管理用のデータ構造を 設けて、これを管理しなければならない +(解放が必要となる理由は、たいていは、プログラム自身と生存期間が同じ ハッシュテーブルを一つだけ作成するのではなく、そのプログラムでは複数の ハッシュテーブルを繰り返して作成したり破棄したりするからであろう)。 .SH バグ -SVr4 と POSIX.1-2001 の規定では、 -\fIaction\fP は検索が失敗したときにだけ意味を持つとなっている。 -よって、検索が成功した場合、\fIaction\fP の値が \fBENTER\fP でも -何もすべきではない。 -(バージョン 2.3 より前の) libc と glibc の実装はこの規格に違反しており、 -この状況で、指定された \fIkey\fP に対応する \fIdata\fP が更新される。 +SVr4 と POSIX.1\-2001 の規定では、 \fIaction\fP は検索が失敗したときにだけ意味を持つとなっている。 +よって、検索が成功した場合、\fIaction\fP の値が \fBENTER\fP でも 何もすべきではない。 (バージョン 2.3 より前の) libc と +glibc の実装はこの規格に違反しており、 この状況で、指定された \fIkey\fP に対応する \fIdata\fP が更新される。 ハッシュテーブルエントリーの追加はできるが、削除ができない。 .SH 例 .PP -次のプログラムは、ハッシュテーブルに 24 個の項目を挿入し、 -それからそのうちのいくつかを表示する。 +次のプログラムは、ハッシュテーブルに 24 個の項目を挿入し、 それからそのうちのいくつかを表示する。 .nf #include @@ -317,7 +180,7 @@ int main() ep = hsearch(e, ENTER); /* エラーは起こらないはずである。 */ if (ep == NULL) { - fprintf(stderr, "entry failed\\n"); + fprintf(stderr, "entry failed\en"); exit(EXIT_FAILURE); } } @@ -327,7 +190,7 @@ int main() あとの 2 つがテーブルにないことを示す。 */ e.key = data[i]; ep = hsearch(e, FIND); - printf("%9.9s \-> %9.9s:%d\\n", e.key, + printf("%9.9s \-> %9.9s:%d\en", e.key, ep ? ep\->key : "NULL", ep ? (int)(ep\->data) : 0); } hdestroy(); @@ -335,7 +198,4 @@ int main() } .fi .SH 関連項目 -.BR bsearch (3), -.BR lsearch (3), -.BR malloc (3), -.BR tsearch (3) +\fBbsearch\fP(3), \fBlsearch\fP(3), \fBmalloc\fP(3), \fBtsearch\fP(3)