hcreate(3c) - osol9

1hsearch(3C)              Standard C Library Functions              hsearch(3C)
2
3
4

NAME

6       hsearch, hcreate, hdestroy - manage hash search tables
7

SYNOPSIS

9       #include <search.h>
10
11       ENTRY *hsearch(ENTRY item, ACTION action);
12
13
14       int hcreate(size_t mekments);
15
16
17       void hdestroy(void);
18
19

DESCRIPTION

21       The  hsearch() function is a hash-table search routine generalized from
22       Knuth (6.4) Algorithm D. It returns a pointer into a hash  table  indi‐
23       cating  the  location  at  which  an entry can be found. The comparison
24       function used by hsearch() is strcmp() (see string(3C)). The item argu‐
25       ment  is  a structure of type ENTRY (defined in the  <search.h> header)
26       containing two pointers: item.key points to  the  comparison  key,  and
27       item.data  points  to  any  other  data to be associated with that key.
28       (Pointers to types other than void should be cast to  pointer-to-void.)
29       The  action argument is a member of an enumeration type ACTION (defined
30       in <search.h>) indicating the disposition of the entry if it cannot  be
31       found in the table. ENTER indicates that the item should be inserted in
32       the table at an appropriate point. Given a  duplicate  of  an  existing
33       item,  the  new  item is not entered and hsearch() returns a pointer to
34       the existing item. FIND indicates that no entry should be made.  Unsuc‐
35       cessful resolution is indicated by the return of a null pointer.
36
37
38       The  hcreate()  function  allocates sufficient space for the table, and
39       must be called before hsearch() is used.  The nel argument is an  esti‐
40       mate of the maximum number of entries that the table will contain. This
41       number may be adjusted upward by the algorithm in order to obtain  cer‐
42       tain mathematically favorable circumstances.
43
44
45       The  hdestroy() function destroys the search table, and may be followed
46       by another call to hcreate().
47

RETURN VALUES

49       The hsearch() function returns a null pointer if either the  action  is
50       FIND and the item could not be found or the action is ENTER and the ta‐
51       ble is full.
52
53
54       The hcreate() function returns 0 if it cannot allocate sufficient space
55       for the table.
56

USAGE

58       The  hsearch()  and   hcreate()  functions  use  malloc(3C) to allocate
59       space.
60
61
62       Only one hash search table may be active at any given time.
63

EXAMPLES

65       Example 1 Example to read in strings.
66
67
68       The following example will read in strings followed by two numbers  and
69       store them in a hash table, discarding duplicates. It will then read in
70       strings and find the matching entry in the hash table and print it.
71
72
73         #include <stdio.h>
74         #include <search.h>
75         #include <string.h>
76         #include <stdlib.h>
77
78         struct info {              /* this is the info stored in table */
79                 int age, room;     /* other than the key */
80         };
81         #define NUM_EMPL    5000   /* # of elements in search table */
82         main( )
83         {
84                                 /* space to store strings */
85                 char string_space[NUM_EMPL*20];
86                                 /* space to store employee info */
87                 struct info info_space[NUM_EMPL];
88                                 /* next avail space in string_space */
89                 char *str_ptr = string_space;
90                                 /* next avail space in info_space */
91                 struct info *info_ptr = info_space;
92                 ENTRY item, *found_item;
93                                 /* name to look for in table */
94                 char name_to_find[30];
95                 int i = 0;
96
97                                 /* create table */
98                 (void) hcreate(NUM_EMPL);
99                 while (scanf("%s%d%d", str_ptr, &info_ptr−>age,
100                        &info_ptr−>room) != EOF && i++ < NUM_EMPL) {
101                            /* put info in structure, and structure in item */
102                         item.key = str_ptr;
103                         item.data = (void *)info_ptr;
104                         str_ptr += strlen(str_ptr) + 1;
105                         info_ptr++;
106                                 /* put item into table */
107                         (void) hsearch(item, ENTER);
108                 }
109
110                                 /* access table */
111                 item.key = name_to_find;
112                 while (scanf("%s", item.key) != EOF) {
113                     if ((found_item = hsearch(item, FIND)) != NULL) {
114                                 /* if item is in the table */
115                         (void)printf("found %s, age = %d, room = %d\n",
116                                 found_item−>key,
117                                 ((struct info *)found_item−>data)−>age,
118                                 ((struct info *)found_item−>data)−>room);
119                     } else {
120                         (void)printf("no such employee %s\n",
121                                 name_to_find)
122                     }
123                 }
124                 return 0;
125         }
126
127

ATTRIBUTES

129       See attributes(5) for descriptions of the following attributes:
130
131
132
133
134       ┌─────────────────────────────┬─────────────────────────────┐
135       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
136       ├─────────────────────────────┼─────────────────────────────┤
137       │Interface Stability          │Standard                     │
138       ├─────────────────────────────┼─────────────────────────────┤
139       │MT-Level                     │Safe                         │
140       └─────────────────────────────┴─────────────────────────────┘
141