+++ /dev/null
-.\" Copyright 1993 Ulrich Drepper (drepper@karlsruhe.gmd.de)
-.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk
-.\" <mtk.manpages@gmail.com>
-.\"
-.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
-.\" This is free documentation; you can redistribute it and/or
-.\" modify it under the terms of the GNU General Public License as
-.\" published by the Free Software Foundation; either version 2 of
-.\" the License, or (at your option) any later version.
-.\"
-.\" The GNU General Public License's references to "object code"
-.\" and "executables" are to be interpreted as the output of any
-.\" document formatting or typesetting system, including
-.\" intermediate and printed output.
-.\"
-.\" This manual is distributed in the hope that it will be useful,
-.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
-.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-.\" GNU General Public License for more details.
-.\"
-.\" You should have received a copy of the GNU General Public
-.\" License along with this manual; if not, see
-.\" <http://www.gnu.org/licenses/>.
-.\" %%%LICENSE_END
-.\"
-.\" References consulted:
-.\" SunOS 4.1.1 man pages
-.\" Modified Sat Sep 30 21:52:01 1995 by Jim Van Zandt <jrv@vanzandt.mv.com>
-.\" Remarks from dhw@gamgee.acad.emich.edu Fri Jun 19 06:46:31 1998
-.\" Modified 2001-12-26, 2003-11-28, 2004-05-20, aeb
-.\" 2008-09-02, mtk: various additions and rewrites
-.\" 2008-09-03, mtk, restructured somewhat, in part after suggestions from
-.\" Timothy S. Nelson <wayland@wayland.id.au>
-.\"
-.\"*******************************************************************
-.\"
-.\" This file was generated with po4a. Translate the source file.
-.\"
-.\"*******************************************************************
-.\"
-.\" 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 <momma@wakhok.ac.jp>
-.\" Updated & Modified 2001-10-15, Yuichi SATO <ysato@h4.dion.ne.jp>
-.\" Updated & Modified 2002-01-03, Yuichi SATO
-.\" Updated & Modified 2004-01-17, Yuichi SATO <ysato444@yahoo.co.jp>
-.\" Updated & Modified 2005-01-10, Yuichi SATO
-.\" Updated 2008-09-20, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
-.\"
-.TH HSEARCH 3 2014\-01\-05 GNU "Linux Programmer's Manual"
-.SH 名前
-hcreate, hdestroy, hsearch, hcreate_r, hdestroy_r, hsearch_r \- ハッシュテーブルの管理
-.SH 書式
-.nf
-\fB#include <search.h>\fP
-.sp
-\fBint hcreate(size_t \fP\fInel\fP\fB);\fP
-.sp
-\fBENTRY *hsearch(ENTRY \fP\fIitem\fP\fB, ACTION \fP\fIaction\fP\fB);\fP
-.sp
-\fBvoid hdestroy(void);\fP
-.sp
-\fB#define _GNU_SOURCE\fP /* feature_test_macros(7) 参照 */
-.br
-\fB#include <search.h>\fP
-.sp
-\fBint hcreate_r(size_t \fP\fInel\fP\fB, struct hsearch_data *\fP\fIhtab\fP\fB);\fP
-.sp
-\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
-\fBvoid hdestroy_r(struct hsearch_data *\fP\fIhtab\fP\fB);\fP
-.fi
-.SH 説明
-\fBhcreate\fP(), \fBhsearch\fP(), \fBhdestroy\fP() の 3 つの関数を利用すると、キー (文字列)
-と対応するデータから構成される エントリーを格納できるハッシュ検索テーブルを作成、管理することができる。
-これらの関数を使って、一度に使用できるのは一つのハッシュテーブルだけである。
-
-\fBhcreate_r\fP(), \fBhsearch_r\fP(), \fBhdestroy_r\fP() の 3
-つの関数はリエントラント版で、これらを利用すると、 一つのプログラムで同時に複数のハッシュテーブルを使うことができる。 最後の引き数 \fIhtab\fP
-は関数の操作対象となるテーブルを示す構造体へのポインターである。 プログラマはこの構造体をブラックボックスとして扱うべきである
-(つまり、この構造体のフィールドに直接アクセスしたり変更したり しないこと)。
-
-.\" e.g., in glibc it is raised to the next higher prime number
-最初に、 \fBhcreate\fP() 関数によってハッシュテーブルを作成しなければならない。 引き数 \fInel\fP
-でテーブルの最大エントリー数を指定する (この最大値は後で変更することはできないので、よく考えて選択すること)。
-作成されるハッシュテーブルの性能を向上させるために、 関数内部の実装によりこの値は増やされる場合もある。
-
-\fBhcreate_r\fP() 関数は \fBhcreate\fP() と同じ動作をするが、構造体 \fI*htab\fP
-で示されるテーブルを対象として動作する。 \fIhtab\fP が指し示す構造体は、 \fBhcreate_r\fP() を初めて呼び出す前に 0
-で埋めておかなければならない。
-
-\fBhdestroy\fP() 関数は、 \fBhcreate\fP() で作成されたハッシュテーブルが占有していたメモリーを解放する。
-ハッシュテーブルによって占有されていたメモリーを解放し、 新しいテーブルを作成できるようにする。 \fBhdestroy\fP() を呼び出すと、その後は
-\fBhcreate\fP() を使って新しいハッシュテーブルを作成することができる。 \fBhdestroy_r\fP() 関数は、同様の処理を、それ以前に
-\fBhcreate_r\fP() を使って作成した \fI*htab\fP で示されるハッシュテーブルに対して実行する。
-
-\fBhsearch\fP() 関数は、\fIitem\fP と同じキーを持つ項目をハッシュテーブルから
-検索し、項目が見つかった場合にはその項目へのポインターを返す (「同じ」かどうかは \fBstrcmp\fP(3) を使って判定する)。
-
-引き数 \fIitem\fP は \fBENTRY\fP 型であり、\fI<search.h>\fP の中で 以下のように定義されている。
-.in +4n
-.sp
-.nf
-typedef struct entry {
- char *key;
- void *data;
-} ENTRY;
-.in
-.fi
-.sp
-フィールド \fIkey\fP は検索キーとなるヌル終端された文字列を指す。 フィールド \fIdata\fP は、このキーに対応するデータを指す。
-
-検索が失敗した後の動作は、引き数 \fIaction\fP により決まる。 この引き数には \fBENTER\fP か \fBFIND\fP
-のいずれかの値を指定しなければならない。 \fBENTER\fP は \fIitem\fP のコピーを挿入することを
-(関数の結果として新しいハッシュテーブルエントリーへのポインターを返す)、 \fBFIND\fP は NULL を返すことを意味する (\fIaction\fP が
-\fBFIND\fP の場合、 \fIdata\fP は無視される)。
-
-\fBhsearch_r\fP() 関数は \fBhsearch\fP() と同様だが、 \fI*htab\fP で示されるハッシュテーブルに対して処理を行う。
-\fBhsearch_r\fP() 関数が \fBhsearch\fP() と異なるのは、見つかった項目へのポインターを、 関数の結果としてではなく、
-\fI*retval\fP に格納して返す点である。
-.SH 返り値
-\fBhcreate\fP() と \fBhcreate_r\fP() は、成功した場合 0 以外の値を返す。 エラーの場合 0 を返し、 \fIerrno\fP
-にエラーの原因を示す値を設定する。
-
-成功すると、 \fBhsearch\fP() は、ハッシュテーブル内のエントリーへのポインターを返す。 エラーの場合、 \fBhsearch\fP() は
-NULL を返す。 エラーとなるのは、 \fIaction\fP が \fBENTER\fP でハッシュテーブルがいっぱいの場合か、 \fIaction\fP が
-\fBFIND\fP で \fIitem\fP がハッシュテーブル内に 見つからない場合である。 \fBhsearch_r\fP() は、成功すると 0
-以外を返し、エラーの場合 0 を返す。 エラーの場合、 これら二つの関数は \fIerrno\fP にエラーの原因を示す値を設定する。
-.SH エラー
-.LP
-\fBhcreate_r\fP() と \fBhdestroy_r\fP() は以下の理由で失敗する可能性がある。
-.TP
-\fBEINVAL\fP
-\fIhtab\fP が NULL である。
-.PP
-\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 が規定しているのは、エラー \fBENOMEM\fP だけである。
-.SH 属性
-.SS "マルチスレッディング (pthreads(7) 参照)"
-関数 \fBhcreate\fP(), \fBhsearch\fP(), \fBhdestroy\fP()
-はテーブルを格納するのにグローバル空間を使用する。そのため、これらの関数はスレッドセーフではない。
-.LP
-関数 \fBhcreate_r\fP(), \fBhsearch_r\fP(), \fBhdestroy_r\fP() はスレッドセーフである。
-.SH 準拠
-関数 \fBhcreate\fP(), \fBhsearch\fP(), \fBhdestroy\fP() は SVr4 から導入されたもので、POSIX.1\-2001
-に記述されている。 関数 \fBhcreate_r\fP, \fBhsearch_r\fP, \fBhdestroy_r\fP は GNU の拡張である。
-.SH 注意
-通常、ハッシュテーブルの実装は、衝突を最小限にするために テーブルに十分な空き領域がある場合に効率がよくなる。 このため、普通は、 \fInel\fP
-を、呼び出し側がテーブルに格納しようと思っている エントリーの最大数より少なくとも 25% は大きな値にすべきである。
-
-\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 が更新される。
-
-ハッシュテーブルエントリーの追加はできるが、削除ができない。
-.SH 例
-.PP
-次のプログラムは、ハッシュテーブルに 24 個の項目を挿入し、 それからそのうちのいくつかを表示する。
-.nf
-
-#include <stdio.h>
-#include <stdlib.h>
-#include <search.h>
-
-static char *data[] = { "alpha", "bravo", "charlie", "delta",
- "echo", "foxtrot", "golf", "hotel", "india", "juliet",
- "kilo", "lima", "mike", "november", "oscar", "papa",
- "quebec", "romeo", "sierra", "tango", "uniform",
- "victor", "whisky", "x\-ray", "yankee", "zulu"
-};
-
-int main()
-{
- ENTRY e, *ep;
- int i;
-
- hcreate(30);
-
- for (i = 0; i < 24; i++) {
- e.key = data[i];
- /* データは、ポインターではなく、単なる整数値である。 */
- e.data = (void *) i;
- ep = hsearch(e, ENTER);
- /* エラーは起こらないはずである。 */
- if (ep == NULL) {
- fprintf(stderr, "entry failed\en");
- exit(EXIT_FAILURE);
- }
- }
-
- for (i = 22; i < 26; i++) {
- /* テーブルにある 2 つのエントリーを表示し、
- あとの 2 つがテーブルにないことを示す。 */
- e.key = data[i];
- ep = hsearch(e, FIND);
- printf("%9.9s \-> %9.9s:%d\en", e.key,
- ep ? ep\->key : "NULL", ep ? (int)(ep\->data) : 0);
- }
- hdestroy();
- exit(EXIT_SUCCESS);
-}
-.fi
-.SH 関連項目
-\fBbsearch\fP(3), \fBlsearch\fP(3), \fBmalloc\fP(3), \fBtsearch\fP(3)
-.SH この文書について
-この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.79 の一部
-である。プロジェクトの説明とバグ報告に関する情報は
-http://www.kernel.org/doc/man\-pages/ に書かれている。
OSDN Git Service
