hcreate.3 (a4bf5fb987611aeb78c422312b63b185e39982d7) hcreate.3 (9823a90c79bac3a172a02f7e76947fcbb57e0955)
1.\"-
2.\" Copyright (c) 1999 The NetBSD Foundation, Inc.
3.\" All rights reserved.
4.\"
5.\" This code is derived from software contributed to The NetBSD Foundation
6.\" by Klaus Klein.
7.\"
8.\" Redistribution and use in source and binary forms, with or without

--- 14 unchanged lines hidden (view full) ---

23.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
24.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
25.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
26.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
27.\" POSSIBILITY OF SUCH DAMAGE.
28.\"
29.\" $FreeBSD$
30.\"
1.\"-
2.\" Copyright (c) 1999 The NetBSD Foundation, Inc.
3.\" All rights reserved.
4.\"
5.\" This code is derived from software contributed to The NetBSD Foundation
6.\" by Klaus Klein.
7.\"
8.\" Redistribution and use in source and binary forms, with or without

--- 14 unchanged lines hidden (view full) ---

23.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
24.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
25.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
26.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
27.\" POSSIBILITY OF SUCH DAMAGE.
28.\"
29.\" $FreeBSD$
30.\"
31.Dd July 6, 2008
31.Dd July 21, 2014
32.Dt HCREATE 3
33.Os
34.Sh NAME
32.Dt HCREATE 3
33.Os
34.Sh NAME
35.Nm hcreate , hdestroy , hsearch
35.Nm hcreate ,
36.Nm hcreate_r ,
37.Nm hdestroy ,
38.Nm hdestroy_r ,
39.Nm hsearch ,
40.Nm hsearch_r
36.Nd manage hash search table
37.Sh LIBRARY
38.Lb libc
39.Sh SYNOPSIS
40.In search.h
41.Ft int
42.Fn hcreate "size_t nel"
41.Nd manage hash search table
42.Sh LIBRARY
43.Lb libc
44.Sh SYNOPSIS
45.In search.h
46.Ft int
47.Fn hcreate "size_t nel"
48.Ft int
49.Fn hcreate_r "size_t nel" "struct hsearch_data *table"
43.Ft void
50.Ft void
44.Fn hdestroy void
51.Fn hdestroy "void"
52.Ft void
53.Fn hdestroy_r "struct hsearch_data *table"
45.Ft ENTRY *
46.Fn hsearch "ENTRY item" "ACTION action"
54.Ft ENTRY *
55.Fn hsearch "ENTRY item" "ACTION action"
56.Ft int
57.Fn hsearch_r "ENTRY item" "ACTION action" "ENTRY ** itemp" "struct hsearch_data *table"
47.Sh DESCRIPTION
48The
49.Fn hcreate ,
58.Sh DESCRIPTION
59The
60.Fn hcreate ,
61.Fn hcreate_r ,
50.Fn hdestroy ,
62.Fn hdestroy ,
63.Fn hdestroy_r
64.Fn hsearch ,
51and
65and
52.Fn hsearch
66.Fn hsearch_r
53functions manage hash search tables.
54.Pp
55The
56.Fn hcreate
57function allocates sufficient space for the table, and the application should
58ensure it is called before
59.Fn hsearch
60is used.

--- 24 unchanged lines hidden (view full) ---

85It returns a pointer into a hash table
86indicating the location at which an entry can be found.
87The
88.Fa item
89argument is a structure of type
90.Vt ENTRY
91(defined in the
92.In search.h
67functions manage hash search tables.
68.Pp
69The
70.Fn hcreate
71function allocates sufficient space for the table, and the application should
72ensure it is called before
73.Fn hsearch
74is used.

--- 24 unchanged lines hidden (view full) ---

99It returns a pointer into a hash table
100indicating the location at which an entry can be found.
101The
102.Fa item
103argument is a structure of type
104.Vt ENTRY
105(defined in the
106.In search.h
93header) containing two pointers:
107header) that contains two pointers:
94.Fa item.key
95points to the comparison key (a
96.Vt "char *" ) ,
97and
98.Fa item.data
99(a
100.Vt "void *" )
101points to any other data to be associated with

--- 29 unchanged lines hidden (view full) ---

131.Xr malloc 3
132if
133.Fa action
134is
135.Dv ENTER
136and
137.Fn hdestroy
138is called.
108.Fa item.key
109points to the comparison key (a
110.Vt "char *" ) ,
111and
112.Fa item.data
113(a
114.Vt "void *" )
115points to any other data to be associated with

--- 29 unchanged lines hidden (view full) ---

145.Xr malloc 3
146if
147.Fa action
148is
149.Dv ENTER
150and
151.Fn hdestroy
152is called.
153.Pp
154The
155.Fn hcreate_r ,
156.Fn hdestroy_r ,
157and
158.Fn hsearch_r
159functions are re-entrant versions of the above functions that can
160operate on a table supplied by the user.
161The
162.Fn hsearch_r
163function returns
164.Dv 0
165if the action is
166.Dv ENTER
167and the element cannot be created,
168.Dv 1
169otherwise.
170If the element exists or can be created, it will be placed in
171.Fa itemp ,
172otherwise
173.Fa itemp
174will be set to
175.Dv NULL .
139.Sh RETURN VALUES
140The
141.Fn hcreate
176.Sh RETURN VALUES
177The
178.Fn hcreate
142function returns 0 if the table creation failed and the global variable
179and
180.Fn hcreate_r
181functions return 0 if the table creation failed and the global variable
143.Va errno
144is set to indicate the error;
145otherwise, a non-zero value is returned.
146.Pp
147The
148.Fn hdestroy
182.Va errno
183is set to indicate the error;
184otherwise, a non-zero value is returned.
185.Pp
186The
187.Fn hdestroy
149function does not return a value.
188and
189.Fn hdestroy_r
190functions return no value.
150.Pp
151The
152.Fn hsearch
191.Pp
192The
193.Fn hsearch
153function returns a
194and
195.Fn hsearch_r
196functions return a
154.Dv NULL
155pointer if either the
156.Fa action
157is
158.Dv FIND
159and the
160.Fa item
161could not be found or the

--- 56 unchanged lines hidden (view full) ---

218 }
219 hdestroy();
220 return 0;
221}
222.Ed
223.Sh ERRORS
224The
225.Fn hcreate
197.Dv NULL
198pointer if either the
199.Fa action
200is
201.Dv FIND
202and the
203.Fa item
204could not be found or the

--- 56 unchanged lines hidden (view full) ---

261 }
262 hdestroy();
263 return 0;
264}
265.Ed
266.Sh ERRORS
267The
268.Fn hcreate
226and
269.Fn hcreate_r ,
227.Fn hsearch
270.Fn hsearch
228functions may fail if:
271and
272.Fn hsearch_r
273functions will fail if:
229.Bl -tag -width Er
230.It Bq Er ENOMEM
274.Bl -tag -width Er
275.It Bq Er ENOMEM
231Insufficient storage space is available.
276Insufficient memory is available.
232.It Bq Er EINVAL
233A table already exists.
234.El
277.It Bq Er EINVAL
278A table already exists.
279.El
280.Pp
281The
282.Fn hsearch
283and
284.Fn hsearch_r
285functions will also fail if the action is
286.Dv SEARCH
287and the element is not found:
288.Bl -tag -width Er
289.It Bq Er ESRCH
290The
291.Fa item
292given is not found.
293.El
235.Sh SEE ALSO
236.Xr bsearch 3 ,
237.Xr lsearch 3 ,
238.Xr malloc 3 ,
239.Xr strcmp 3 ,
240.Xr tsearch 3
241.Sh STANDARDS
242The

--- 6 unchanged lines hidden (view full) ---

249.Sh HISTORY
250The
251.Fn hcreate ,
252.Fn hdestroy ,
253and
254.Fn hsearch
255functions first appeared in
256.At V .
294.Sh SEE ALSO
295.Xr bsearch 3 ,
296.Xr lsearch 3 ,
297.Xr malloc 3 ,
298.Xr strcmp 3 ,
299.Xr tsearch 3
300.Sh STANDARDS
301The

--- 6 unchanged lines hidden (view full) ---

308.Sh HISTORY
309The
310.Fn hcreate ,
311.Fn hdestroy ,
312and
313.Fn hsearch
314functions first appeared in
315.At V .
316The
317.Fn hcreate_r ,
318.Fn hdestroy_r
319and
320.Fn hsearch_r
321functions are
322.Tn GNU
323extensions.
257.Sh BUGS
324.Sh BUGS
258The interface permits the use of only one hash table at a time.
325The original,
326.Pf non- Tn GNU
327interface permits the use of only one hash table at a time.