2004-11-03 13:51:07 +00:00
|
|
|
.\" Hey Emacs! This file is -*- nroff -*- source.
|
|
|
|
.\" Copyright 1993 Ulrich Drepper (drepper@karlsruhe.gmd.de)
|
2008-09-03 08:07:02 +00:00
|
|
|
.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk
|
|
|
|
.\" <mtk.manpages@gmail.com>
|
2004-11-03 13:51:07 +00:00
|
|
|
.\"
|
|
|
|
.\" 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 14:25:59 +00:00
|
|
|
.\" 2008-09-02, mtk: various additions and rewrites
|
2008-09-03 08:09:40 +00:00
|
|
|
.\" 2008-09-03, mtk, restructured somewhat, in part after suggestions from
|
|
|
|
.\" Timothy S. Nelson <wayland@wayland.id.au>
|
2004-11-03 13:51:07 +00:00
|
|
|
.\"
|
2008-10-06 14:26:23 +00:00
|
|
|
.TH HSEARCH 3 2008-10-06 "GNU" "Linux Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
2007-07-08 14:48:42 +00:00
|
|
|
hcreate, hdestroy, hsearch, hcreate_r, hdestroy_r,
|
|
|
|
hsearch_r \- hash table management
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH SYNOPSIS
|
2007-04-03 15:32:52 +00:00
|
|
|
.nf
|
2004-11-03 13:51:07 +00:00
|
|
|
.B #include <search.h>
|
|
|
|
.sp
|
|
|
|
.BI "int hcreate(size_t " nel );
|
|
|
|
.sp
|
|
|
|
.BI "ENTRY *hsearch(ENTRY " item ", ACTION " action );
|
|
|
|
.sp
|
|
|
|
.B "void hdestroy(void);"
|
2007-04-05 12:36:57 +00:00
|
|
|
.sp
|
getresuid.2, mremap.2, poll.2, remap_file_pages.2, setresuid.2, splice.2, sync_file_range.2, syscall.2, tee.2, vmsplice.2, INFINITY.3, aio_init.3, asprintf.3, assert_perror.3, basename.3, bsd_signal.3, canonicalize_file_name.3, clog10.3, crypt.3, dl_iterate_phdr.3, dlopen.3, encrypt.3, exp10.3, fcloseall.3, fenv.3, fopencookie.3, ftw.3, getaddrinfo_a.3, getloadavg.3, getutent.3, grantpt.3, hsearch.3, lseek64.3, memmem.3, mempcpy.3, pow10.3, program_invocation_name.3, ptsname.3, putgrent.3, sched_getcpu.3, sincos.3, strchr.3, strfry.3, strnlen.3, strptime.3, strstr.3, strverscmp.3, swab.3, sysv_signal.3, tsearch.3, unlockpt.3, wcwidth.3: Add reference to feature_test_macros(7)
Some pages simply list feature test macro requirements in
the form:
#define #GNU_SOURCE
#include <someheader.h>
For these pages, add a "See feature_test_macros(7)" comment
on the "#define" line.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-10-31 04:31:47 +00:00
|
|
|
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
|
2004-11-03 13:51:07 +00:00
|
|
|
.br
|
|
|
|
.B #include <search.h>
|
|
|
|
.sp
|
2008-09-03 08:07:02 +00:00
|
|
|
.BI "int hcreate_r(size_t " nel ", struct hsearch_data *" htab );
|
2004-11-03 13:51:07 +00:00
|
|
|
.sp
|
2008-09-03 08:07:02 +00:00
|
|
|
.BI "int hsearch_r(ENTRY " item ", ACTION " action ", ENTRY **" retval ,
|
|
|
|
.BI " struct hsearch_data *" htab );
|
2004-11-03 13:51:07 +00:00
|
|
|
.sp
|
2008-09-03 08:07:02 +00:00
|
|
|
.BI "void hdestroy_r(struct hsearch_data *" htab );
|
2007-04-03 15:32:52 +00:00
|
|
|
.fi
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH DESCRIPTION
|
|
|
|
The three functions
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR hcreate (),
|
|
|
|
.BR hsearch (),
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR hdestroy ()
|
2008-09-03 10:32:22 +00:00
|
|
|
allow the caller to create and manage a hash search table
|
|
|
|
containing entries consisting of a key (a string) and associated data.
|
2008-09-02 14:06:20 +00:00
|
|
|
Using these functions, only one hash table can be used at a time.
|
2008-09-03 08:07:02 +00:00
|
|
|
|
|
|
|
The three functions
|
|
|
|
.BR hcreate_r (),
|
|
|
|
.BR hsearch_r (),
|
|
|
|
.BR hdestroy_r ()
|
|
|
|
are reentrant versions that allow a program to use
|
2008-09-03 10:32:22 +00:00
|
|
|
more than one hash search table at the same time.
|
2008-09-03 08:07:02 +00:00
|
|
|
The last argument,
|
|
|
|
.IR htab ,
|
|
|
|
points to a structure that describes the table
|
|
|
|
on which the function is to operate.
|
|
|
|
The programmer should treat this structure as opaque
|
|
|
|
(i.e., do not attempt to directly access or modify
|
|
|
|
the fields in this structure).
|
|
|
|
|
|
|
|
First a hash table must be created using
|
2007-05-12 09:06:04 +00:00
|
|
|
.BR hcreate ().
|
2008-09-02 14:06:20 +00:00
|
|
|
The argument \fInel\fP specifies the maximum number of entries
|
2004-11-03 13:51:07 +00:00
|
|
|
in the table.
|
2008-09-02 14:06:20 +00:00
|
|
|
(This maximum cannot be changed later, so choose it wisely.)
|
2008-09-03 08:07:02 +00:00
|
|
|
The implementation may adjust this value upward to improve the
|
2004-11-03 13:51:07 +00:00
|
|
|
performance of the resulting hash table.
|
2008-09-02 14:06:20 +00:00
|
|
|
.\" e.g., in glibc it is raised to the next higher prime number
|
2008-09-03 08:07:02 +00:00
|
|
|
|
|
|
|
The
|
|
|
|
.BR hcreate_r ()
|
|
|
|
function performs the same task as
|
|
|
|
.BR hcreate (),
|
|
|
|
but for the table described by the structure
|
|
|
|
.IR *htab .
|
|
|
|
The structure pointed to by
|
|
|
|
.I htab
|
|
|
|
must be zeroed before the first call to
|
|
|
|
.BR hcreate_r ().
|
|
|
|
|
|
|
|
The function
|
2007-05-12 09:06:04 +00:00
|
|
|
.BR hdestroy ()
|
2008-09-03 08:07:02 +00:00
|
|
|
frees the memory occupied by the hash table that was created by
|
|
|
|
.BR hcreate ().
|
2008-09-02 14:06:20 +00:00
|
|
|
After calling
|
|
|
|
.BR hdestroy ()
|
|
|
|
a new hash table can be created using
|
|
|
|
.BR hcreate ().
|
2008-09-03 08:07:02 +00:00
|
|
|
The
|
|
|
|
.BR hdestroy_r ()
|
2008-09-03 10:32:22 +00:00
|
|
|
function performs the analogous task for a hash table described by
|
|
|
|
.IR *htab ,
|
|
|
|
which was previously created using
|
|
|
|
.BR hcreate_r ().
|
2008-09-02 14:06:20 +00:00
|
|
|
|
2008-09-03 08:07:02 +00:00
|
|
|
The
|
2008-09-02 14:06:20 +00:00
|
|
|
.BR hsearch ()
|
2008-09-03 08:07:02 +00:00
|
|
|
function searches the hash table for an
|
2008-09-02 14:06:20 +00:00
|
|
|
item with the same key as \fIitem\fP (where "the same" is determined using
|
|
|
|
.BR strcmp (3)),
|
|
|
|
and if successful returns a pointer to it.
|
|
|
|
|
|
|
|
The argument \fIitem\fP is of type \fIENTRY\fP, which is defined in
|
|
|
|
\fI<search.h>\fP as follows:
|
2007-12-19 06:16:04 +00:00
|
|
|
.in +4n
|
2004-11-03 13:51:07 +00:00
|
|
|
.sp
|
|
|
|
.nf
|
2007-04-12 22:42:49 +00:00
|
|
|
typedef struct entry {
|
2007-12-19 05:53:30 +00:00
|
|
|
char *key;
|
|
|
|
void *data;
|
2007-04-05 13:29:41 +00:00
|
|
|
} ENTRY;
|
2007-12-19 06:16:04 +00:00
|
|
|
.in
|
2004-11-03 13:51:07 +00:00
|
|
|
.fi
|
|
|
|
.sp
|
2008-09-02 14:06:20 +00:00
|
|
|
The field \fIkey\fP points to a null-terminated string which is the
|
2004-11-03 13:51:07 +00:00
|
|
|
search key.
|
2008-09-02 14:06:20 +00:00
|
|
|
The field \fIdata\fP points to data that is associated with that key.
|
|
|
|
|
2007-05-12 09:06:04 +00:00
|
|
|
The argument \fIaction\fP determines what
|
|
|
|
.BR hsearch ()
|
2008-09-02 14:06:20 +00:00
|
|
|
does after an unsuccessful search.
|
|
|
|
This argument must either have the value
|
|
|
|
.BR ENTER ,
|
|
|
|
meaning insert a copy of
|
2008-09-03 08:07:02 +00:00
|
|
|
.IR item
|
|
|
|
(and return a pointer to the new hash table entry as the function result),
|
2008-09-02 14:06:20 +00:00
|
|
|
or the value
|
|
|
|
.BR FIND ,
|
|
|
|
meaning that NULL should be returned.
|
|
|
|
(If
|
|
|
|
.I action
|
|
|
|
is
|
|
|
|
.BR FIND ,
|
|
|
|
then
|
|
|
|
.I data
|
|
|
|
is ignored.)
|
2008-09-03 08:07:02 +00:00
|
|
|
|
|
|
|
The
|
|
|
|
.BR hsearch_r ()
|
|
|
|
function is like
|
|
|
|
.BR hsearch ()
|
|
|
|
but operates on the hash table described by
|
|
|
|
.IR *htab .
|
2008-09-02 14:06:20 +00:00
|
|
|
The
|
|
|
|
.BR hsearch_r ()
|
|
|
|
function differs from
|
|
|
|
.BR hsearch ()
|
|
|
|
in that a pointer to the found item is returned in
|
2008-09-03 08:07:02 +00:00
|
|
|
.IR *retval ,
|
2008-09-02 14:06:20 +00:00
|
|
|
rather than as the function result.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "RETURN VALUE"
|
2007-05-12 09:06:04 +00:00
|
|
|
.BR hcreate ()
|
|
|
|
and
|
|
|
|
.BR hcreate_r ()
|
intro.1, time.1, adjtimex.2, capget.2, eventfd.2, fcntl.2, getrlimit.2, getsockopt.2, gettimeofday.2, intro.2, ioctl_list.2, ioperm.2, mlock.2, pivot_root.2, poll.2, prctl.2, ptrace.2, sched_setscheduler.2, select_tut.2, semget.2, sigaltstack.2, signalfd.2, sysctl.2, timer_settime.2, timerfd_create.2, wait.2, CPU_SET.3, argz_add.3, assert_perror.3, atexit.3, backtrace.3, bcmp.3, clearenv.3, ctime.3, dl_iterate_phdr.3, dlopen.3, ecvt.3, errno.3, error.3, ether_aton.3, exit.3, fenv.3, ferror.3, finite.3, flockfile.3, fnmatch.3, fpathconf.3, fpclassify.3, ftime.3, ftok.3, ftw.3, fwide.3, getaddrinfo.3, gethostbyname.3, getlogin.3, getnameinfo.3, getnetent.3, getopt.3, getprotoent.3, getrpcent.3, getservent.3, glob.3, hsearch.3, inet.3, isalpha.3, iswalnum.3, iswalpha.3, iswblank.3, iswcntrl.3, iswctype.3, iswdigit.3, iswgraph.3, iswlower.3, iswprint.3, iswpunct.3, iswspace.3, iswupper.3, iswxdigit.3, longjmp.3, lsearch.3, malloc.3, matherr.3, mblen.3, mbsinit.3, mbtowc.3, on_exit.3, printf.3, pthread_attr_init.3, pthread_attr_setaffinity_np.3, pthread_attr_setdetachstate.3, pthread_attr_setguardsize.3, pthread_attr_setinheritsched.3, pthread_attr_setschedparam.3, pthread_attr_setschedpolicy.3, pthread_attr_setscope.3, pthread_attr_setstack.3, pthread_attr_setstackaddr.3, pthread_attr_setstacksize.3, pthread_cancel.3, pthread_cleanup_push.3, pthread_equal.3, pthread_getattr_np.3, pthread_getcpuclockid.3, pthread_setaffinity_np.3, pthread_setcancelstate.3, pthread_setconcurrency.3, pthread_setschedparam.3, pthread_setschedprio.3, ptsname.3, putenv.3, putgrent.3, raise.3, rcmd.3, regex.3, rexec.3, rpc.3, rpmatch.3, rtnetlink.3, scandir.3, sem_init.3, setaliasent.3, setbuf.3, setenv.3, setjmp.3, signbit.3, stdio_ext.3, strtod.3, strtol.3, strtoul.3, system.3, termios.3, timeradd.3, tzset.3, ualarm.3, wctomb.3, xdr.3, st.4, tty_ioctl.4, core.5, elf.5, proc.5, bootparam.7, capabilities.7, icmp.7, ip.7, ipv6.7, math_error.7, mdoc.samples.7, mq_overview.7, pthreads.7, raw.7, regex.7, socket.7, tcp.7, tzselect.8: Global fix: s/non-zero/nonzero/
The tendency in English, as prescribed in style guides like
Chicago MoS, is towards removing hyphens after prefixes
like "non-" etc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-01-16 16:40:55 +00:00
|
|
|
return nonzero on success.
|
2008-09-02 14:06:20 +00:00
|
|
|
They return 0 on error.
|
|
|
|
|
|
|
|
On success,
|
|
|
|
.BR hsearch ()
|
|
|
|
returns a pointer to an entry in the hash table.
|
2007-05-12 09:06:04 +00:00
|
|
|
.BR hsearch ()
|
2008-09-02 14:06:20 +00:00
|
|
|
returns NULL on error, that is,
|
|
|
|
if \fIaction\fP is \fBENTER\fP and
|
2004-11-03 13:51:07 +00:00
|
|
|
the hash table is full, or \fIaction\fP is \fBFIND\fP and \fIitem\fP
|
|
|
|
cannot be found in the hash table.
|
2007-05-12 09:06:04 +00:00
|
|
|
.BR hsearch_r ()
|
intro.1, time.1, adjtimex.2, capget.2, eventfd.2, fcntl.2, getrlimit.2, getsockopt.2, gettimeofday.2, intro.2, ioctl_list.2, ioperm.2, mlock.2, pivot_root.2, poll.2, prctl.2, ptrace.2, sched_setscheduler.2, select_tut.2, semget.2, sigaltstack.2, signalfd.2, sysctl.2, timer_settime.2, timerfd_create.2, wait.2, CPU_SET.3, argz_add.3, assert_perror.3, atexit.3, backtrace.3, bcmp.3, clearenv.3, ctime.3, dl_iterate_phdr.3, dlopen.3, ecvt.3, errno.3, error.3, ether_aton.3, exit.3, fenv.3, ferror.3, finite.3, flockfile.3, fnmatch.3, fpathconf.3, fpclassify.3, ftime.3, ftok.3, ftw.3, fwide.3, getaddrinfo.3, gethostbyname.3, getlogin.3, getnameinfo.3, getnetent.3, getopt.3, getprotoent.3, getrpcent.3, getservent.3, glob.3, hsearch.3, inet.3, isalpha.3, iswalnum.3, iswalpha.3, iswblank.3, iswcntrl.3, iswctype.3, iswdigit.3, iswgraph.3, iswlower.3, iswprint.3, iswpunct.3, iswspace.3, iswupper.3, iswxdigit.3, longjmp.3, lsearch.3, malloc.3, matherr.3, mblen.3, mbsinit.3, mbtowc.3, on_exit.3, printf.3, pthread_attr_init.3, pthread_attr_setaffinity_np.3, pthread_attr_setdetachstate.3, pthread_attr_setguardsize.3, pthread_attr_setinheritsched.3, pthread_attr_setschedparam.3, pthread_attr_setschedpolicy.3, pthread_attr_setscope.3, pthread_attr_setstack.3, pthread_attr_setstackaddr.3, pthread_attr_setstacksize.3, pthread_cancel.3, pthread_cleanup_push.3, pthread_equal.3, pthread_getattr_np.3, pthread_getcpuclockid.3, pthread_setaffinity_np.3, pthread_setcancelstate.3, pthread_setconcurrency.3, pthread_setschedparam.3, pthread_setschedprio.3, ptsname.3, putenv.3, putgrent.3, raise.3, rcmd.3, regex.3, rexec.3, rpc.3, rpmatch.3, rtnetlink.3, scandir.3, sem_init.3, setaliasent.3, setbuf.3, setenv.3, setjmp.3, signbit.3, stdio_ext.3, strtod.3, strtol.3, strtoul.3, system.3, termios.3, timeradd.3, tzset.3, ualarm.3, wctomb.3, xdr.3, st.4, tty_ioctl.4, core.5, elf.5, proc.5, bootparam.7, capabilities.7, icmp.7, ip.7, ipv6.7, math_error.7, mdoc.samples.7, mq_overview.7, pthreads.7, raw.7, regex.7, socket.7, tcp.7, tzselect.8: Global fix: s/non-zero/nonzero/
The tendency in English, as prescribed in style guides like
Chicago MoS, is towards removing hyphens after prefixes
like "non-" etc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-01-16 16:40:55 +00:00
|
|
|
returns nonzero on success, and 0 on error.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH ERRORS
|
|
|
|
.LP
|
2008-09-02 14:06:20 +00:00
|
|
|
.BR hcreate ()
|
|
|
|
and
|
|
|
|
.BR hcreate_r ()
|
|
|
|
can fail for the following reasons:
|
|
|
|
.TP
|
|
|
|
.B EINVAL
|
|
|
|
.RB ( hcreate_r ())
|
2008-09-03 08:07:02 +00:00
|
|
|
.I htab
|
2008-09-02 14:06:20 +00:00
|
|
|
is NULL.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B ENOMEM
|
|
|
|
Table full with \fIaction\fP set to \fBENTER\fP.
|
|
|
|
.TP
|
|
|
|
.B ESRCH
|
2008-07-10 20:53:08 +00:00
|
|
|
The \fIaction\fP argument is \fBFIND\fP and no corresponding element
|
2004-11-03 13:51:07 +00:00
|
|
|
is found in the table.
|
2008-09-02 14:06:20 +00:00
|
|
|
.\" hdestroy_r() can set errno to EINVAL if 'tab' is NULL.
|
|
|
|
.PP
|
|
|
|
.BR hsearch ()
|
|
|
|
and
|
|
|
|
.BR hsearch_r ()
|
|
|
|
can fail for the following reasons:
|
|
|
|
.TP
|
|
|
|
.B ENOMEM
|
|
|
|
.I action
|
|
|
|
was
|
|
|
|
.BR ENTER ,
|
|
|
|
.I key
|
|
|
|
was not found in the table,
|
|
|
|
and there was no room in the table to add a new entry.
|
|
|
|
.TP
|
|
|
|
.B ESRCH
|
|
|
|
.I action
|
|
|
|
was
|
2008-09-03 05:55:36 +00:00
|
|
|
.BR FIND ,
|
2008-09-02 14:06:20 +00:00
|
|
|
and
|
|
|
|
.I key
|
|
|
|
was not found in the table.
|
|
|
|
.PP
|
|
|
|
POSIX.1-2001 only specifies the
|
|
|
|
.B ENOMEM
|
|
|
|
error.
|
2006-08-04 12:39:17 +00:00
|
|
|
.SH "CONFORMING TO"
|
2004-11-03 13:51:07 +00:00
|
|
|
The functions
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR hcreate (),
|
|
|
|
.BR hsearch (),
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR hdestroy ()
|
2006-08-03 13:57:30 +00:00
|
|
|
are from SVr4, and are described in POSIX.1-2001.
|
2004-11-03 13:51:07 +00:00
|
|
|
The functions
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR hcreate_r (),
|
|
|
|
.BR hsearch_r (),
|
2008-09-03 08:07:02 +00:00
|
|
|
and
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR hdestroy_r ()
|
2004-11-03 13:51:07 +00:00
|
|
|
are GNU extensions.
|
2008-09-02 14:06:20 +00:00
|
|
|
.SH NOTES
|
|
|
|
Hash table implementations are usually more efficient when the
|
|
|
|
table contains enough free space to minimize collisions.
|
|
|
|
Typically, this means that
|
|
|
|
.I nel
|
|
|
|
should be at least 25% larger than the maximum number of elements
|
|
|
|
that the caller expects to store in the table.
|
|
|
|
|
|
|
|
The
|
|
|
|
.BR hdestroy ()
|
2008-09-03 08:07:02 +00:00
|
|
|
and
|
|
|
|
.BR hdestroy _r()
|
|
|
|
functions do not free the buffers pointed to by the
|
2008-09-02 14:06:20 +00:00
|
|
|
.I key
|
|
|
|
and
|
|
|
|
.I data
|
|
|
|
elements of the hash table entries.
|
2008-09-03 08:07:02 +00:00
|
|
|
(It can't do this because it doesn't know
|
|
|
|
whether these buffers were allocated dynamically.)
|
2008-09-02 14:06:20 +00:00
|
|
|
If these buffers need to be freed (perhaps because the program
|
|
|
|
is repeatedly creating and destroying hash tables,
|
|
|
|
rather than creating a single table whose lifetime
|
|
|
|
matches that of the program),
|
|
|
|
then the program must maintain bookkeeping data structures that
|
|
|
|
allow it to free them.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH BUGS
|
2006-08-03 13:57:30 +00:00
|
|
|
SVr4 and POSIX.1-2001 specify that \fIaction\fP
|
2007-12-13 20:46:52 +00:00
|
|
|
is significant only for unsuccessful searches, so that an \fBENTER\fP
|
2007-04-12 22:42:49 +00:00
|
|
|
should not do anything for a successful search.
|
2008-09-03 08:07:02 +00:00
|
|
|
In libc and glibc (before version 2.3), the
|
|
|
|
implementation violates the specification,
|
|
|
|
updating the \fIdata\fP for the given \fIkey\fP in this case.
|
2008-09-02 14:06:20 +00:00
|
|
|
|
2004-11-03 13:51:07 +00:00
|
|
|
Individual hash table entries can be added, but not deleted.
|
|
|
|
.SH EXAMPLE
|
|
|
|
.PP
|
2008-09-02 14:06:20 +00:00
|
|
|
The following program inserts 24 items into a hash table, then prints
|
2004-11-03 13:51:07 +00:00
|
|
|
some of them.
|
|
|
|
.nf
|
|
|
|
|
2007-04-05 12:36:57 +00:00
|
|
|
#include <stdio.h>
|
|
|
|
#include <stdlib.h>
|
|
|
|
#include <search.h>
|
2007-04-12 22:42:49 +00:00
|
|
|
|
2007-04-05 12:36:57 +00:00
|
|
|
char *data[] = { "alpha", "bravo", "charlie", "delta",
|
|
|
|
"echo", "foxtrot", "golf", "hotel", "india", "juliet",
|
|
|
|
"kilo", "lima", "mike", "november", "oscar", "papa",
|
|
|
|
"quebec", "romeo", "sierra", "tango", "uniform",
|
2007-06-20 21:39:45 +00:00
|
|
|
"victor", "whisky", "x\-ray", "yankee", "zulu"
|
2007-04-05 12:36:57 +00:00
|
|
|
};
|
2004-11-03 13:51:07 +00:00
|
|
|
|
2007-04-12 22:42:49 +00:00
|
|
|
int
|
|
|
|
main(void)
|
2007-04-05 14:17:54 +00:00
|
|
|
{
|
2007-04-05 12:36:57 +00:00
|
|
|
ENTRY e, *ep;
|
|
|
|
int i;
|
2007-04-12 22:42:49 +00:00
|
|
|
|
2007-04-05 12:36:57 +00:00
|
|
|
hcreate(30);
|
2008-09-02 14:06:20 +00:00
|
|
|
|
2007-04-05 12:36:57 +00:00
|
|
|
for (i = 0; i < 24; i++) {
|
2007-04-12 22:42:49 +00:00
|
|
|
e.key = data[i];
|
|
|
|
/* data is just an integer, instead of a
|
2007-04-05 12:36:57 +00:00
|
|
|
pointer to something */
|
2007-05-21 08:47:38 +00:00
|
|
|
e.data = (void *) i;
|
2007-04-05 12:36:57 +00:00
|
|
|
ep = hsearch(e, ENTER);
|
|
|
|
/* there should be no failures */
|
|
|
|
if (ep == NULL) {
|
2004-11-03 13:51:07 +00:00
|
|
|
fprintf(stderr, "entry failed\\n");
|
2007-05-14 21:11:42 +00:00
|
|
|
exit(EXIT_FAILURE);
|
2007-04-05 12:36:57 +00:00
|
|
|
}
|
2004-11-03 13:51:07 +00:00
|
|
|
}
|
2008-09-02 14:06:20 +00:00
|
|
|
|
2007-04-05 12:36:57 +00:00
|
|
|
for (i = 22; i < 26; i++) {
|
|
|
|
/* print two entries from the table, and
|
|
|
|
show that two are not in the table */
|
|
|
|
e.key = data[i];
|
|
|
|
ep = hsearch(e, FIND);
|
|
|
|
printf("%9.9s \-> %9.9s:%d\\n", e.key,
|
2007-06-20 21:39:45 +00:00
|
|
|
ep ? ep\->key : "NULL", ep ? (int)(ep\->data) : 0);
|
2007-04-05 12:36:57 +00:00
|
|
|
}
|
2008-09-24 14:01:22 +00:00
|
|
|
hdestroy();
|
2007-05-16 02:09:09 +00:00
|
|
|
exit(EXIT_SUCCESS);
|
2007-04-05 12:36:57 +00:00
|
|
|
}
|
2004-11-03 13:51:07 +00:00
|
|
|
.fi
|
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR bsearch (3),
|
|
|
|
.BR lsearch (3),
|
|
|
|
.BR malloc (3),
|
getresuid.2, intro.2, mremap.2, open.2, poll.2, posix_fadvise.2, pread.2, remap_file_pages.2, setresuid.2, signal.2, splice.2, sync_file_range.2, tee.2, vmsplice.2, INFINITY.3, asprintf.3, assert_perror.3, basename.3, bsd_signal.3, canonicalize_file_name.3, clog10.3, crypt.3, dl_iterate_phdr.3, dlopen.3, dprintf.3, encrypt.3, exp10.3, fcloseall.3, fenv.3, ffs.3, fmemopen.3, fopencookie.3, ftw.3, getdate.3, getline.3, getloadavg.3, getopt.3, getsubopt.3, getutent.3, grantpt.3, hsearch.3, intro.3, lseek64.3, memmem.3, mempcpy.3, mq_receive.3, mq_send.3, posix_fallocate.3, pow10.3, program_invocation_name.3, ptsname.3, putgrent.3, readdir.3, sigset.3, sincos.3, stpcpy.3, stpncpy.3, strchr.3, strfry.3, strnlen.3, strptime.3, strsignal.3, strstr.3, strverscmp.3, swab.3, sysv_signal.3, tsearch.3, unlocked_stdio.3, unlockpt.3, wcpcpy.3, wcpncpy.3, wcsdup.3, wcwidth.3: SEE ALSO: Remove redundant reference to feature_test_macros(7)
Reported-by: Florian Lehmann <flo.lehmann@googlemail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-10-31 05:05:22 +00:00
|
|
|
.BR tsearch (3)
|