Man page - hcreate(3)

Packages contains this manual

Available languages:

en fr ja de

Manual

HSEARCH

名 前
書 åŧ
čĒŦ 明
čŋ” り 値
エ ナ ãƒŧ
åąž 性
æē– 拠
æŗ¨ 意
バ グ
例
é–ĸ é€Ŗ 項 į›Ž
こ ぎ 文 書 ãĢ つ い ãĻ

名 前

hcreate, hdestroy, hsearch, hcreate_r, hdestroy_r, hsearch_r - ハ ッ ã‚ˇ ãƒĨ テ ãƒŧ ブ ãƒĢ ぎ įŽĄ į†

書 åŧ

#include <search.h>

int hcreate(size_t nel );

ENTRY *hsearch(ENTRY item , ACTION action );

void hdestroy(void);

#define _GNU_SOURCE /* feature_test_macros(7) 参 į…§ */
#include <search.h>

int hcreate_r(size_t nel , struct hsearch_data * htab );

int hsearch_r(ENTRY item , ACTION action , ENTRY ** retval ,
struct hsearch_data * htab );

void hdestroy_r(struct hsearch_data * htab );

čĒŦ 明

hcreate (), hsearch (), hdestroy () ぎ 3 つ ぎ é–ĸ 数 を 刊 į”¨ す る と 、 キ ãƒŧ (文 字 列 ) と 寞 åŋœ す る デ ãƒŧ ã‚ŋ か ら 構 成 さ れ る エ ãƒŗ ト ãƒĒ ãƒŧ を æ ŧ į´ で き る ハ ッ ã‚ˇ ãƒĨ 検 į´ĸ テ ãƒŧ ブ ãƒĢ を äŊœ 成 、 įŽĄ į† す る こ と が で き る 。 こ れ ら ぎ é–ĸ 数 を äŊŋ ãŖ ãĻ 、 一 åēĻ ãĢ äŊŋ į”¨ で き る ぎ は 一 つ ぎ ハ ッ ã‚ˇ ãƒĨ テ ãƒŧ ブ ãƒĢ だ け で あ る 。

hcreate_r (), hsearch_r (), hdestroy_r () ぎ 3 つ ぎ é–ĸ 数 は ãƒĒ エ ãƒŗ ト ナ ãƒŗ ト į‰ˆ で 、 こ れ ら を 刊 į”¨ す る と 、 一 つ ぎ プ ロ グ ナ ム で 同 時 ãĢ 複 数 ぎ ハ ッ ã‚ˇ ãƒĨ テ ãƒŧ ブ ãƒĢ を äŊŋ う こ と が で き る 。 最 垌 ぎ åŧ• 数 htab は é–ĸ 数 ぎ 操 äŊœ 寞 蹥 と ãĒ る テ ãƒŧ ブ ãƒĢ を į¤ē す 構 造 äŊ“ へ ぎ ポ イ ãƒŗ ã‚ŋ ãƒŧ で あ る 。 プ ロ グ ナ マ は こ ぎ 構 造 äŊ“ を ブ ナ ッ ク ボ ッ ク ã‚š と し ãĻ æ‰ą う ず き で あ る (つ ぞ り 、 こ ぎ 構 造 äŊ“ ぎ フ ã‚Ŗ ãƒŧ ãƒĢ ド ãĢ į›´ æŽĨ ã‚ĸ ク ã‚ģ ã‚š し た り 変 更 し た り し ãĒ い こ と )。

最 初 ãĢ 、 hcreate () é–ĸ 数 ãĢ よ ãŖ ãĻ ハ ッ ã‚ˇ ãƒĨ テ ãƒŧ ブ ãƒĢ を äŊœ 成 し ãĒ け れ ば ãĒ ら ãĒ い 。 åŧ• 数 nel で テ ãƒŧ ブ ãƒĢ ぎ 最 大 エ ãƒŗ ト ãƒĒ ãƒŧ 数 を 指 厚 す る (こ ぎ 最 大 値 は 垌 で 変 更 す る こ と は で き ãĒ い ぎ で 、 よ く 考 え ãĻ 選 択 す る こ と )。 äŊœ 成 さ れ る ハ ッ ã‚ˇ ãƒĨ テ ãƒŧ ブ ãƒĢ ぎ 性 čƒŊ を 向 上 さ せ る た め ãĢ 、 é–ĸ 数 内 部 ぎ 原 čŖ… ãĢ よ り こ ぎ 値 は åĸ— や さ れ る å ´ 合 も あ る 。

hcreate_r () é–ĸ 数 は hcreate () と 同 じ 動 äŊœ を す る が 、 構 造 äŊ“ *htab で į¤ē さ れ る テ ãƒŧ ブ ãƒĢ を 寞 蹥 と し ãĻ 動 äŊœ す る 。 htab が 指 し į¤ē す 構 造 äŊ“ は 、 hcreate_r () を 初 め ãĻ å‘ŧ ãŗ å‡ē す 前 ãĢ 0 で 埋 め ãĻ お か ãĒ け れ ば ãĒ ら ãĒ い 。

hdestroy () é–ĸ 数 は 、 hcreate () で äŊœ 成 さ れ た ハ ッ ã‚ˇ ãƒĨ テ ãƒŧ ブ ãƒĢ が 占 有 し ãĻ い た ãƒĄ ãƒĸ ãƒĒ ãƒŧ を č§Ŗ 攞 す る 。 ハ ッ ã‚ˇ ãƒĨ テ ãƒŧ ブ ãƒĢ ãĢ よ ãŖ ãĻ 占 有 さ れ ãĻ い た ãƒĄ ãƒĸ ãƒĒ ãƒŧ を č§Ŗ 攞 し 、 新 し い テ ãƒŧ ブ ãƒĢ を äŊœ 成 で き る よ う ãĢ す る 。 hdestroy () を å‘ŧ ãŗ å‡ē す と 、 そ ぎ 垌 は hcreate () を äŊŋ ãŖ ãĻ 新 し い ハ ッ ã‚ˇ ãƒĨ テ ãƒŧ ブ ãƒĢ を äŊœ 成 す る こ と が で き る 。 hdestroy_r () é–ĸ 数 は 、 同 様 ぎ å‡Ļ į† を 、 そ れ äģĨ 前 ãĢ hcreate_r () を äŊŋ ãŖ ãĻ äŊœ 成 し た *htab で į¤ē さ れ る ハ ッ ã‚ˇ ãƒĨ テ ãƒŧ ブ ãƒĢ ãĢ 寞 し ãĻ 原 行 す る 。

hsearch () é–ĸ 数 は 、 item と 同 じ キ ãƒŧ を 持 つ 項 į›Ž を ハ ッ ã‚ˇ ãƒĨ テ ãƒŧ ブ ãƒĢ か ら 検 į´ĸ し 、 項 į›Ž が čĻ‹ つ か ãŖ た å ´ 合 ãĢ は そ ぎ 項 į›Ž へ ぎ ポ イ ãƒŗ ã‚ŋ ãƒŧ を čŋ” す (「 同 じ 」 か お う か は strcmp (3) を äŊŋ ãŖ ãĻ 判 厚 す る )。

åŧ• 数 item は ENTRY 型 で あ り 、 <search.h> ぎ 中 で äģĨ 下 ぎ よ う ãĢ 厚 įžŠ さ れ ãĻ い る 。

typedef struct entry {
char *key;
void *data;
} ENTRY;

フ ã‚Ŗ ãƒŧ ãƒĢ ド key は 検 į´ĸ キ ãƒŧ と ãĒ る ヌ ãƒĢ įĩ‚ įĢ¯ さ れ た 文 字 列 を 指 す 。 フ ã‚Ŗ ãƒŧ ãƒĢ ド data は 、 こ ぎ キ ãƒŧ ãĢ 寞 åŋœ す る デ ãƒŧ ã‚ŋ を 指 す 。

検 į´ĸ が å¤ą 敗 し た 垌 ぎ 動 äŊœ は 、 åŧ• 数 action ãĢ よ り æąē ぞ る 。 こ ぎ åŧ• 数 ãĢ は ENTER か FIND ぎ い ず れ か ぎ 値 を 指 厚 し ãĒ け れ ば ãĒ ら ãĒ い 。 ENTER は item ぎ ã‚ŗ ピ ãƒŧ を æŒŋ å…Ĩ す る こ と を (é–ĸ 数 ぎ įĩ 果 と し ãĻ 新 し い ハ ッ ã‚ˇ ãƒĨ テ ãƒŧ ブ ãƒĢ エ ãƒŗ ト ãƒĒ ãƒŧ へ ぎ ポ イ ãƒŗ ã‚ŋ ãƒŧ を čŋ” す )、 FIND は NULL を čŋ” す こ と を 意 å‘ŗ す る ( action が FIND ぎ å ´ 合 、 data は į„Ą čĻ– さ れ る )。

hsearch_r () é–ĸ 数 は hsearch () と 同 様 だ が 、 *htab で į¤ē さ れ る ハ ッ ã‚ˇ ãƒĨ テ ãƒŧ ブ ãƒĢ ãĢ 寞 し ãĻ å‡Ļ į† を 行 う 。 hsearch_r () é–ĸ 数 が hsearch () と į•° ãĒ る ぎ は 、 čĻ‹ つ か ãŖ た 項 į›Ž へ ぎ ポ イ ãƒŗ ã‚ŋ ãƒŧ を 、 é–ĸ 数 ぎ įĩ 果 と し ãĻ で は ãĒ く 、 *retval ãĢ æ ŧ į´ し ãĻ čŋ” す į‚š で あ る 。

čŋ” り 値

hcreate () と hcreate_r () は 、 成 功 し た å ´ 合 0 äģĨ 外 ぎ 値 を čŋ” す 。 エ ナ ãƒŧ ぎ å ´ 合 0 を čŋ” し 、 errno ãĢ エ ナ ãƒŧ ぎ 原 因 を į¤ē す 値 を 設 厚 す る 。

成 功 す る と 、 hsearch () は 、 ハ ッ ã‚ˇ ãƒĨ テ ãƒŧ ブ ãƒĢ 内 ぎ エ ãƒŗ ト ãƒĒ ãƒŧ へ ぎ ポ イ ãƒŗ ã‚ŋ ãƒŧ を čŋ” す 。 エ ナ ãƒŧ ぎ å ´ 合 、 hsearch () は NULL を čŋ” す 。 エ ナ ãƒŧ と ãĒ る ぎ は 、 action が ENTER で ハ ッ ã‚ˇ ãƒĨ テ ãƒŧ ブ ãƒĢ が い ãŖ ãą い ぎ å ´ 合 か 、 action が FIND で item が ハ ッ ã‚ˇ ãƒĨ テ ãƒŧ ブ ãƒĢ 内 ãĢ čĻ‹ つ か ら ãĒ い å ´ 合 で あ る 。 hsearch_r () は 、 成 功 す る と 0 äģĨ 外 を čŋ” し 、 エ ナ ãƒŧ ぎ å ´ 合 0 を čŋ” す 。 エ ナ ãƒŧ ぎ å ´ 合 、 こ れ ら äēŒ つ ぎ é–ĸ 数 は errno ãĢ エ ナ ãƒŧ ぎ 原 因 を į¤ē す 値 を 設 厚 す る 。

エ ナ ãƒŧ

hcreate_r () と hdestroy_r () は äģĨ 下 ぎ į† į”ą で å¤ą 敗 す る 可 čƒŊ 性 が あ る 。

EINVAL

htab が NULL で あ る 。

hsearch () と hsearch_r () は äģĨ 下 ぎ į† į”ą で å¤ą 敗 す る 可 čƒŊ 性 が あ る 。

ENOMEM

action が ENTER で 、 key が テ ãƒŧ ブ ãƒĢ 内 ãĢ čĻ‹ つ か ら ず 、 テ ãƒŧ ブ ãƒĢ ãĢ 新 し い エ ãƒŗ ト ãƒĒ ãƒŧ を čŋŊ 加 す る äŊ™ 地 が ãĒ か ãŖ た 。

ESRCH

action が FIND で 、 key が テ ãƒŧ ブ ãƒĢ 内 ãĢ čĻ‹ つ か ら ãĒ か ãŖ た 。

POSIX.1 が čĻ 厚 し ãĻ い る ぎ は 、 エ ナ ãƒŧ ENOMEM だ け で あ る 。

åąž 性

こ ぎ į¯€ で äŊŋ į”¨ さ れ ãĻ い る į”¨ čĒž ぎ čĒŦ 明 ãĢ つ い ãĻ は 、 attributes (7) を 参 į…§ 。

Image grohtml-29176-1.png

æē– 拠

é–ĸ 数 hcreate (), hsearch (), hdestroy () は SVr4 か ら 導 å…Ĩ さ れ た も ぎ で 、 POSIX.1-2001 と POSIX.1-2008 ãĢ 記 čŋ° さ れ ãĻ い る 。

é–ĸ 数 hcreate_r (), hsearch_r (), hdestroy_r () は GNU ãĢ よ る æ‹Ą åŧĩ で あ る 。

æŗ¨ 意

通 常 、 ハ ッ ã‚ˇ ãƒĨ テ ãƒŧ ブ ãƒĢ ぎ 原 čŖ… は 、 衝 įĒ を 最 小 限 ãĢ す る た め ãĢ テ ãƒŧ ブ ãƒĢ ãĢ 十 分 ãĒ įŠē き 領 域 が あ る å ´ 合 ãĢ 劚 įŽ‡ が よ く ãĒ る 。 こ ぎ た め 、 晎 通 は 、 nel を 、 å‘ŧ ãŗ å‡ē し 側 が テ ãƒŧ ブ ãƒĢ ãĢ æ ŧ į´ し よ う と 思 ãŖ ãĻ い る エ ãƒŗ ト ãƒĒ ãƒŧ ぎ 最 大 数 よ り 少 ãĒ く と も 25% は 大 き ãĒ 値 ãĢ す ず き で あ る 。

hdestroy () と hdestroy_r () は 、 ハ ッ ã‚ˇ ãƒĨ テ ãƒŧ ブ ãƒĢ ぎ エ ãƒŗ ト ãƒĒ ãƒŧ ぎ čĻ į´  で あ る key と data が 指 す バ ッ フ ã‚Ą ãƒŧ を č§Ŗ 攞 し ãĒ い (こ れ が で き ãĒ い ぎ は 、 こ れ ら ぎ バ ッ フ ã‚Ą ãƒŧ が 動 įš„ ãĢ å‰˛ り åŊ“ ãĻ ら れ た ぎ か を įŸĨ る こ と が で き ãĒ い か ら で あ る )。 こ れ ら ぎ バ ッ フ ã‚Ą ãƒŧ を č§Ŗ 攞 す る åŋ… čĻ が あ る å ´ 合 、 プ ロ グ ナ ム で は 、 こ れ ら ぎ バ ッ フ ã‚Ą ãƒŧ を č§Ŗ 攞 で き る よ う ãĢ įŽĄ į† į”¨ ぎ デ ãƒŧ ã‚ŋ 構 造 を 設 け ãĻ 、 こ れ を įŽĄ į† し ãĒ け れ ば ãĒ ら ãĒ い (č§Ŗ 攞 が åŋ… čĻ と ãĒ る į† į”ą は 、 た い ãĻ い は 、 プ ロ グ ナ ム č‡Ē čēĢ と į”Ÿ 存 期 間 が 同 じ ハ ッ ã‚ˇ ãƒĨ テ ãƒŧ ブ ãƒĢ を 一 つ だ け äŊœ 成 す る ぎ で は ãĒ く 、 そ ぎ プ ロ グ ナ ム で は 複 数 ぎ ハ ッ ã‚ˇ ãƒĨ テ ãƒŧ ブ ãƒĢ を įš° り čŋ” し ãĻ äŊœ 成 し た り į ´ æŖ„ し た り す る か ら で あ ろ う )。

バ グ

SVr4 と POSIX.1-2001 ぎ čĻ 厚 で は 、 action は 検 į´ĸ が å¤ą 敗 し た と き ãĢ だ け 意 å‘ŗ を 持 つ と ãĒ ãŖ ãĻ い る 。 よ ãŖ ãĻ 、 検 į´ĸ が 成 功 し た å ´ 合 、 action ぎ 値 が ENTER で も äŊ• も す ず き で は ãĒ い 。 (バ ãƒŧ ジ ョ ãƒŗ 2.3 よ り 前 ぎ ) libc と glibc ぎ 原 čŖ… は こ ぎ čĻ æ ŧ ãĢ 違 反 し ãĻ お り 、 こ ぎ įŠļ æŗ で 、 指 厚 さ れ た key ãĢ 寞 åŋœ す る data が 更 新 さ れ る 。

ハ ッ ã‚ˇ ãƒĨ テ ãƒŧ ブ ãƒĢ エ ãƒŗ ト ãƒĒ ãƒŧ ぎ čŋŊ 加 は で き る が 、 削 除 が で き ãĒ い 。

例

æŦĄ ぎ プ ロ グ ナ ム は 、 ハ ッ ã‚ˇ ãƒĨ テ ãƒŧ ブ ãƒĢ ãĢ 24 個 ぎ 項 į›Ž を æŒŋ å…Ĩ し 、 そ れ か ら そ ぎ う ãĄ ぎ い く つ か を 襨 į¤ē す る 。

#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(void)
{
ENTRY e;
ENTRY *ep;

hcreate(30);

for (int i = 0; i < 24; i++) {
e.key = data[i];
/* デ ãƒŧ ã‚ŋ は 、 ポ イ ãƒŗ ã‚ŋ ãƒŧ で は ãĒ く 、 単 ãĒ る 整 数 値 で あ る 。 */
e.data = (void *) i;
ep = hsearch(e, ENTER);
/* エ ナ ãƒŧ は čĩˇ こ ら ãĒ い は ず で あ る 。 */
if (ep == NULL) {
fprintf(stderr, "entry failed\n");
exit(EXIT_FAILURE);
}
}

for (int i = 22; i < 26; i++) {
/* テ ãƒŧ ブ ãƒĢ ãĢ あ る 2 つ ぎ エ ãƒŗ ト ãƒĒ ãƒŧ を 襨 į¤ē し 、
あ と ぎ 2 つ が テ ãƒŧ ブ ãƒĢ ãĢ ãĒ い こ と を į¤ē す 。 */
e.key = data[i];
ep = hsearch(e, FIND);
printf("%9.9s -> %9.9s:%d\n", e.key,
ep ? ep->key : "NULL", ep ? (int)(ep->data) : 0);
}
hdestroy();
exit(EXIT_SUCCESS);
}

é–ĸ é€Ŗ 項 į›Ž

bsearch (3), lsearch (3), malloc (3), tsearch (3)

こ ぎ 文 書 ãĢ つ い ãĻ

こ ぎ man ペ ãƒŧ ジ は Linux man-pages プ ロ ジ ェ ク ト ぎ ãƒĒ ãƒĒ ãƒŧ ã‚š 5.10 ぎ 一 部 で あ る 。 プ ロ ジ ェ ク ト ぎ čĒŦ 明 と バ グ å ą 告 ãĢ é–ĸ す る 情 å ą は https://www.kernel.org/doc/man-pages/ ãĢ 書 か れ ãĻ い る 。