1HCREATE(3P)                POSIX Programmer's Manual               HCREATE(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       hcreate, hdestroy, hsearch - manage hash search table
13

SYNOPSIS

15       #include <search.h>
16
17       int hcreate(size_t nel);
18       void hdestroy(void);
19       ENTRY *hsearch(ENTRY item, ACTION action);
20
21

DESCRIPTION

23       The hcreate(), hdestroy(), and hsearch() functions  shall  manage  hash
24       search tables.
25
26       The  hcreate()  function shall allocate sufficient space for the table,
27       and the application shall ensure it is called before hsearch() is used.
28       The  nel  argument is an estimate of the maximum number of entries that
29       the table shall contain. This number may  be  adjusted  upward  by  the
30       algorithm  in  order to obtain certain mathematically favorable circum‐
31       stances.
32
33       The hdestroy() function shall dispose of the search table, and  may  be
34       followed  by  another  call to hcreate(). After the call to hdestroy(),
35       the data can no longer be considered accessible.
36
37       The hsearch() function is a hash-table search routine. It shall  return
38       a  pointer  into a hash table indicating the location at which an entry
39       can be found. The item argument is a structure of type  ENTRY  (defined
40       in  the  <search.h> header) containing two pointers: item.key points to
41       the comparison key (a char *), and item.data (a void *) points  to  any
42       other data to be associated with that key. The comparison function used
43       by hsearch() is strcmp(). The action argument is a member of an enumer‐
44       ation  type ACTION indicating the disposition of the entry if it cannot
45       be found in the table. ENTER indicates that the item should be inserted
46       in  the  table  at  an  appropriate point. FIND indicates that no entry
47       should be made.  Unsuccessful resolution is indicated by the return  of
48       a null pointer.
49
50       These  functions need not be reentrant. A function that is not required
51       to be reentrant is not required to be thread-safe.
52

RETURN VALUE

54       The hcreate() function shall return 0 if it cannot allocate  sufficient
55       space for the table; otherwise, it shall return non-zero.
56
57       The hdestroy() function shall not return a value.
58
59       The hsearch() function shall return a null pointer if either the action
60       is FIND and the item could not be found or the action is ENTER and  the
61       table is full.
62

ERRORS

64       The hcreate() and hsearch() functions may fail if:
65
66       ENOMEM Insufficient storage space is available.
67
68
69       The following sections are informative.
70

EXAMPLES

72       The  following  example  reads  in  strings followed by two numbers and
73       stores them in a hash table, discarding duplicates. It  then  reads  in
74       strings  and  finds  the matching entry in the hash table and prints it
75       out.
76
77
78              #include <stdio.h>
79              #include <search.h>
80              #include <string.h>
81
82
83              struct info {        /* This is the info stored in the table */
84                  int age, room;   /* other than the key. */
85              };
86
87
88              #define NUM_EMPL    5000    /* # of elements in search table. */
89
90
91
92              int main(void)
93              {
94                  char string_space[NUM_EMPL*20];   /* Space to store strings. */
95                  struct info info_space[NUM_EMPL]; /* Space to store employee info. */
96                  char *str_ptr = string_space;     /* Next space in string_space. */
97                  struct info *info_ptr = info_space;
98                                                    /* Next space in info_space. */
99                  ENTRY item;
100                  ENTRY *found_item; /* Name to look for in table. */
101                  char name_to_find[30];
102
103
104                  int i = 0;
105
106
107                  /* Create table; no error checking is performed. */
108                  (void) hcreate(NUM_EMPL);
109                  while (scanf("%s%d%d", str_ptr, &info_ptr->age,
110                         &info_ptr->room) != EOF && i++ < NUM_EMPL) {
111
112
113                      /* Put information in structure, and structure in item. */
114                      item.key = str_ptr;
115                      item.data = info_ptr;
116                      str_ptr += strlen(str_ptr) + 1;
117                      info_ptr++;
118
119
120                      /* Put item into table. */
121                      (void) hsearch(item, ENTER);
122                  }
123
124
125                  /* Access table. */
126                  item.key = name_to_find;
127                  while (scanf("%s", item.key) != EOF) {
128                      if ((found_item = hsearch(item, FIND)) != NULL) {
129
130
131                          /* If item is in the table. */
132                          (void)printf("found %s, age = %d, room = %d\n",
133                              found_item->key,
134                              ((struct info *)found_item->data)->age,
135                              ((struct info *)found_item->data)->room);
136                      } else
137                          (void)printf("no such employee %s\n", name_to_find);
138                  }
139                  return 0;
140              }
141

APPLICATION USAGE

143       The hcreate() and hsearch() functions  may  use  malloc()  to  allocate
144       space.
145

RATIONALE

147       None.
148

FUTURE DIRECTIONS

150       None.
151

SEE ALSO

153       bsearch(),  lsearch(),  malloc(), strcmp(), tsearch(), the Base Defini‐
154       tions volume of IEEE Std 1003.1-2001, <search.h>
155
157       Portions of this text are reprinted and reproduced in  electronic  form
158       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
159       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
160       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
161       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
162       event of any discrepancy between this version and the original IEEE and
163       The Open Group Standard, the original IEEE and The Open Group  Standard
164       is  the  referee document. The original Standard can be obtained online
165       at http://www.opengroup.org/unix/online.html .
166
167
168
169IEEE/The Open Group                  2003                          HCREATE(3P)
Impressum