.\" Hey Emacs! This file is -*- nroff -*- source.
.\" Copyright 1993 Ulrich Drepper (drepper@karlsruhe.gmd.de)
.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk
.\"     <mtk.manpages@gmail.com>
.\"
.\" 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, write to the Free
.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
.\" USA.
.\"
.\" 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>
.\"
.\" 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>
.\"
.\"WORD:	hash table		ϥåơ֥
.\"WORD:	entry			ȥ꡼
.\"WORD:	allocate		
.\"WORD:	NUL-terminated		̥ʸ \0 ǽü줿
.\"WORD:	pointer			ݥ
.\"WORD:	character		ʸ
.\"WORD:	item			
.\"
.TH HSEARCH 3 2008-10-06 "GNU" "Linux Programmer's Manual"
.SH ̾
hcreate, hdestroy, hsearch, hcreate_r, hdestroy_r,
hsearch_r \- ϥåơ֥δ
.SH 
.nf
.B #include <search.h>
.sp
.BI "int hcreate(size_t " nel );
.sp
.BI "ENTRY *hsearch(ENTRY " item ", ACTION " action );
.sp
.B "void hdestroy(void);"
.sp
.B #define _GNU_SOURCE
.br
.B #include <search.h>
.sp
.BI "int hcreate_r(size_t " nel ", struct hsearch_data *" htab );
.sp
.BI "int hsearch_r(ENTRY " item ", ACTION " action ", ENTRY **" retval ,
.BI "              struct hsearch_data *" htab );
.sp
.BI "void hdestroy_r(struct hsearch_data *" htab );
.fi
.SH 
.BR hcreate (),
.BR hsearch (),
.BR hdestroy ()
 3 ĤδؿѤȡ (ʸ) бǡ鹽
ȥǼǤϥå帡ơ֥뤳ȤǤ롣
δؿȤäơ٤˻ѤǤΤϰĤΥϥåơ֥Ǥ롣

.BR hcreate_r (),
.BR hsearch_r (),
.BR hdestroy_r ()
 3 ĤδؿϥꥨȥǤǡѤȡ
ĤΥץƱʣΥϥåơ֥ȤȤǤ롣
Ǹΰ
.I htab
ϴؿоݤȤʤơ֥򼨤¤ΤؤΥݥ󥿤Ǥ롣
ץޤϤι¤Τ֥åܥåȤư٤Ǥ
(Ĥޤꡢι¤ΤΥեɤľܥѹ
ʤ)

ǽˡ
.BR hcreate ()
ؿˤäƥϥåơ֥ʤФʤʤ
 \fInel\fP ǥơ֥κ票ȥꤹ
(κͤϸѹ뤳ȤϤǤʤΤǡ褯ͤ򤹤뤳)
ϥåơ֥ǽ夵뤿ˡ
ؿμˤꤳͤ䤵⤢롣
.\" e.g., in glibc it is raised to the next higher prime number

.BR hcreate_r ()
ؿ
.BR hcreate ()
Ʊư򤹤뤬¤
.I *htab
Ǽơ֥оݤȤư롣
.I htab
ؤ¤Τϡ
.BR hcreate_r ()
ƸƤӽФ 0 ƤʤФʤʤ

.BR hdestroy ()
ؿϡ
.BR hcreate ()
Ǻ줿ϥåơ֥뤬ͭƤ롣
ϥåơ֥ˤäͭƤ
ơ֥Ǥ褦ˤ롣
.BR hdestroy ()
ƤӽФȡθ
.BR hcreate ()
Ȥäƿϥåơ֥뤳ȤǤ롣
.BR hdestroy_r ()
ؿϡƱͤν򡢤
.BR hcreate_r ()
Ȥäƺ
.I *htab
Ǽϥåơ֥ФƼ¹Ԥ롣

.BR hsearch ()
ؿϡ\fIitem\fP ƱĹܤϥåơ֥뤫
ܤĤäˤϤιܤؤΥݥ󥿤֤
(Ʊפɤ
.BR strcmp (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 ϸȤʤ NULL ü줿ʸؤ
ե \fIdata\fP ϡΥбǡؤ

Ԥưϡ \fIaction\fP ˤޤ롣
ΰˤ
.B ENTER

.B FIND
Τ줫ͤꤷʤФʤʤ
.B ENTER

.I item
Υԡ뤳Ȥ
(ؿη̤Ȥƿϥåơ֥륨ȥؤΥݥ󥿤֤)
.B FIND
 NULL ֤Ȥ̣
.RI ( action

.B FIND
ξ硢
.I data
̵뤵)

.BR hsearch_r ()
ؿ
.BR hsearch ()
Ʊͤ
.I *htab
Ǽϥåơ֥ФƽԤ
.BR hsearch_r ()
ؿ
.BR hsearch ()
ȰۤʤΤϡĤäܤؤΥݥ󥿤
ؿη̤ȤƤǤϤʤ
.I *retval
˳Ǽ֤Ǥ롣
.SH ֤
.BR hcreate ()

.BR hcreate_r ()
ϡ 0 ʳ֤ͤ
顼ξ 0 ֤

ȡ
.BR hsearch ()
ϡϥåơ֥ΥȥؤΥݥ󥿤֤
顼ξ硢
.BR hsearch ()
 NULL ֤
顼ȤʤΤϡ
\fIaction\fP  \fBENTER\fP ǥϥåơ֥뤬äѤξ礫
\fIaction\fP  \fBFIND\fP  \fIitem\fP ϥåơ֥
ĤʤǤ롣
.BR hsearch_r ()
ϡ 0 ʳ֤顼ξ 0 ֤
.SH 顼
.LP
.BR hcreate ()

.BR hcreate_r ()
ϰʲͳǼԤǽ롣
.TP
.B EINVAL
.RB ( hcreate_r ())
.I htab
 NULL Ǥ롣
.TP
.B ENOMEM
\fBENTER\fP ꤵ줿 \fIaction\fP ǡ
ơ֥뤬äѤˤʤä
.TP
.B ESRCH
\fIaction\fP  \fBFIND\fP ǡ
бǤơ֥˸Ĥʤä
.\" hdestroy_r()  'tab'  NULL ξ errno  EINVAL ꤹ礬롣
.PP
.BR hsearch ()

.BR hsearch_r ()
ϰʲͳǼԤǽ롣
.TP
.B ENOMEM
.I action

.B ENTER
ǡ
.I key
ơ֥˸Ĥ餺
ơ֥˿ȥɲä;Ϥʤä
.TP
.B ESRCH
.I action

.B FIND
ǡ
.I key
ơ֥˸Ĥʤä
.PP
POSIX.1-2001 ꤷƤΤϡ顼
.B ENOMEM
Ǥ롣
.SH 
ؿ
.BR hcreate (),
.BR hsearch (),
.BR hdestroy ()
 SVr4 Ƴ줿ΤǡPOSIX.1-2001 ˵ҤƤ롣
ؿ
.BR hcreate_r ,
.BR hsearch_r ,
.B hdestroy_r
 GNU γĥǤ롣
.SH 
̾ϥåơ֥μϡͤǾ¤ˤ뤿
ơ֥˽ʬʶΰ褬˸Ψ褯ʤ롣
Τᡢ̤ϡ
.I nel
򡢸ƤӽФ¦ơ֥˳Ǽ褦ȻפäƤ
ȥκ꾯ʤȤ 25% 礭ͤˤ٤Ǥ롣

.BR hdestroy ()

.BR hdestroy_r ()
ϡϥåơ֥ΥȥǤǤ
.I key

.I data
ؤХåեʤ
(줬ǤʤΤϡΥХåեưŪ˳Ƥ줿Τ
Τ뤳ȤǤʤǤ)
ΥХåեɬפ硢
ץǤϡΥХåեǤ褦˴ѤΥǡ¤
ߤơʤФʤʤ
(ɬפȤʤͳϡƤϡץ༫Ȥ¸֤Ʊ
ϥåơ֥ĤΤǤϤʤΥץǤʣ
ϥåơ֥򷫤֤ƺ˴ꤹ뤫Ǥ)
.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>

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\\n");
            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\\n", e.key,
               ep ? ep\->key : "NULL", ep ? (int)(ep\->data) : 0);
    }
    hdestroy();
    exit(EXIT_SUCCESS);
}
.fi
.SH Ϣ
.BR bsearch (3),
.BR lsearch (3),
.BR malloc (3),
.BR tsearch (3),
.BR feature_test_macros (7)