hdestroy(3)

1HSEARCH(3)                 Linux Programmer's Manual                HSEARCH(3)
2
3
4

NAME

6       hcreate, hdestroy, hsearch - hash table management
7

SYNOPSIS

9       #include <search.h>
10
11       int hcreate(size_t nel);
12
13       ENTRY *hsearch(ENTRY item, ACTION action);
14
15       void hdestroy(void);
16
17
18       #define _GNU_SOURCE
19       #include <search.h>
20
21       int hcreate_r(size_t nel, struct hsearch_data *tab);
22
23       int   hsearch_r(ENTRY   item,   ACTION   action,  ENTRY  **ret,  struct
24       hsearch_data *tab);
25
26       void hdestroy_r(struct hsearch_data *tab);
27

DESCRIPTION

29       The three functions hcreate(), hsearch(), and hdestroy() allow the user
30       to create a hash table (only one at a time) which associates a key with
31       any data.
32
33       First the table must be created with the function hcreate().  The argu‐
34       ment  nel is an estimate of the maximum number of entries in the table.
35       The function hcreate() may adjust this value upward to improve the per‐
36       formance of the resulting hash table.
37
38       The  corresponding function hdestroy() frees the memory occupied by the
39       hash table so that a new table can be constructed.
40
41       The argument item is of type ENTRY,  which  is  a  typedef  defined  in
42       <search.h> and includes these elements:
43
44            typedef struct entry {
45                char *key;
46                void *data;
47            } ENTRY;
48
49       The  field key points to the null-terminated string which is the search
50       key.  The field data points to the data associated with that key.   The
51       function  hsearch()  searches  the hash table for an item with the same
52       key as item (where "the same" is determined using  strcmp(3)),  and  if
53       successful  returns  a  pointer  to it.  The argument action determines
54       what hsearch() does after an unsuccessful search.   A  value  of  ENTER
55       instructs  it  to insert a copy of item, while a value of FIND means to
56       return NULL.
57
58       The three functions hcreate_r(), hsearch_r(),  hdestroy_r()  are  reen‐
59       trant  versions  that  allow  the use of more than one table.  The last
60       argument used identifies the table. The struct it  points  to  must  be
61       zeroed before the first call to hcreate_r().
62

RETURN VALUE

64       hcreate()  and  hcreate_r()  return 0 when allocation of the memory for
65       the hash table fails, non-zero otherwise.
66
67       hsearch() returns NULL if action is ENTER and the hash table  is  full,
68       or action is FIND and item cannot be found in the hash table.
69
70       hsearch_r()  returns  0  if action is ENTER and the hash table is full,
71       and non-zero otherwise.
72

ERRORS

74       POSIX documents
75
76       ENOMEM Out of memory.
77
78       The glibc implementation will return the following two errors.
79
80       ENOMEM Table full with action set to ENTER.
81
82       ESRCH  The action parameter is FIND and  no  corresponding  element  is
83              found in the table.
84

CONFORMING TO

86       The  functions  hcreate(), hsearch(), and hdestroy() are from SVr4, and
87       are described in POSIX.1-2001.  The functions hcreate_r(), hsearch_r(),
88       hdestroy_r() are GNU extensions.
89

BUGS

91       SVr4  and  POSIX.1-2001  specify  that  action  is significant only for
92       unsuccessful searches, so that an ENTER should not do  anything  for  a
93       successful  search.  The libc and glibc implementations update the data
94       for the given key in this case.
95
96       Individual hash table entries can be added, but not deleted.
97

EXAMPLE

99       The following program inserts 24 items in to a hash table, then  prints
100       some of them.
101
102           #include <stdio.h>
103           #include <stdlib.h>
104           #include <search.h>
105
106           char *data[] = { "alpha", "bravo", "charlie", "delta",
107                "echo", "foxtrot", "golf", "hotel", "india", "juliet",
108                "kilo", "lima", "mike", "november", "oscar", "papa",
109                "quebec", "romeo", "sierra", "tango", "uniform",
110                "victor", "whisky", "x-ray", "yankee", "zulu"
111           };
112
113           int main() {
114             ENTRY e, *ep;
115             int i;
116
117             /* starting with small table, and letting it grow does not work */
118             hcreate(30);
119             for (i = 0; i < 24; i++) {
120                 e.key = data[i];
121                 /* data is just an integer, instead of a
122                    pointer to something */
123                 e.data = (void *)i;
124                 ep = hsearch(e, ENTER);
125                 /* there should be no failures */
126                 if (ep == NULL) {
127                   fprintf(stderr, "entry failed\n");
128                   exit(1);
129                 }
130             }
131             for (i = 22; i < 26; i++) {
132                 /* print two entries from the table, and
133                    show that two are not in the table */
134                 e.key = data[i];
135                 ep = hsearch(e, FIND);
136                 printf("%9.9s -> %9.9s:%d\n", e.key,
137                        ep ? ep->key : "NULL",
138                        ep ? (int)(ep->data) : 0);
139             }
140             return 0;
141           }
142
143