|
Hopefully, this page is exactly what you are looking for, but if not, you can always find further assistance on Unix/Linux Forum!
HSEARCH(3) Linux Programmer's Manual HSEARCH(3)
NAME
hcreate, hdestroy, hsearch - hash table management
SYNOPSIS
#include <search.h>
int hcreate(size_t nel);
ENTRY *hsearch(ENTRY item, ACTION action);
void hdestroy(void);
#define _GNU_SOURCE
#include <search.h>
int hcreate_r(size_t nel, struct hsearch_data *tab);
int hsearch_r(ENTRY item, ACTION action, ENTRY **ret, struct
hsearch_data *tab);
void hdestroy_r(struct hsearch_data *tab);
DESCRIPTION
The three functions hcreate(), hsearch(), and hdestroy() allow the user
to create a hash table (only one at a time) which associates a key with
any data.
First the table must be created with the function hcreate(). The argu-
ment nel is an estimate of the maximum number of entries in the table.
The function hcreate() may adjust this value upward to improve the per-
formance of the resulting hash table.
The corresponding function hdestroy() frees the memory occupied by the
hash table so that a new table can be constructed.
The argument item is of type ENTRY, which is a typedef defined in
<search.h> and includes these elements:
typedef struct entry {
char *key;
void *data;
} ENTRY;
The field key points to the null-terminated string which is the search
key. The field data points to the data associated with that key. The
function hsearch() searches the hash table for an item with the same
key as item (where "the same" is determined using strcmp(3)), and if
successful returns a pointer to it. The argument action determines
what hsearch() does after an unsuccessful search. A value of ENTER
instructs it to insert a copy of item, while a value of FIND means to
return NULL.
The three functions hcreate_r(), hsearch_r(), hdestroy_r() are reen-
trant versions that allow the use of more than one table. The last
argument used identifies the table. The struct it points to must be
zeroed before the first call to hcreate_r().
RETURN VALUE
hcreate() and hcreate_r() return 0 when allocation of the memory for
the hash table fails, non-zero otherwise.
hsearch() returns NULL if action is ENTER and the hash table is full,
or action is FIND and item cannot be found in the hash table.
hsearch_r() returns 0 if action is ENTER and the hash table is full,
and non-zero otherwise.
ERRORS
POSIX documents
ENOMEM Out of memory.
The glibc implementation will return the following two errors.
ENOMEM Table full with action set to ENTER.
ESRCH The action parameter is FIND and no corresponding element is
found in the table.
CONFORMING TO
The functions hcreate(), hsearch(), and hdestroy() are from SVr4, and
are described in POSIX.1-2001. The functions hcreate_r(), hsearch_r(),
hdestroy_r() are GNU extensions.
BUGS
SVr4 and POSIX.1-2001 specify that action is significant only for
unsuccessful searches, so that an ENTER should not do anything for a
successful search. The libc and glibc implementations update the data
for the given key in this case.
Individual hash table entries can be added, but not deleted.
EXAMPLE
The following program inserts 24 items in to a hash table, then prints
some of them.
#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;
/* starting with small table, and letting it grow does not work */
hcreate(30);
for (i = 0; i < 24; i++) {
e.key = data[i];
/* data is just an integer, instead of a
pointer to something */
e.data = (void *)i;
ep = hsearch(e, ENTER);
/* there should be no failures */
if (ep == NULL) {
fprintf(stderr, "entry failed\n");
exit(1);
}
}
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,
ep ? ep->key : "NULL",
ep ? (int)(ep->data) : 0);
}
return 0;
}
SEE ALSO
bsearch(3), lsearch(3), malloc(3), tsearch(3)
GNU 2004-05-20 HSEARCH(3)
Man(1) output converted with
man2html and wrapped by fishsponge
This page was generated on Sat Sep 8 16:38:13 GMT 2007
|
Your favourite pages:
No pages logged yet.
Trying to save cookie... Top 10 most popular pages:
svn man page (6143 hits)
(FreeBSD 6.2)
sqlite3 man page (5592 hits)
(openSUSE 10.2)
adv_cap_autoneg man page (5041 hits)
(Solaris 10 11_06)
CPAN man page (4787 hits)
(Suse Linux 10.1)
ssh man page (4438 hits)
(Suse Linux 10.1)
ssh-socks5-proxy-connect man page (3506 hits)
(Solaris 10 11_06)
signal man page (3363 hits)
(Suse Linux 10.1)
netcat man page (3359 hits)
(Suse Linux 10.1)
pprosetup man page (2876 hits)
(Solaris 10 11_06)
startproc man page (2732 hits)
(Suse Linux 10.1)
|
Man Pages 
