summaryrefslogtreecommitdiff
path: root/src/lib/libc/stdlib/hcreate.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libc/stdlib/hcreate.3')
-rw-r--r--src/lib/libc/stdlib/hcreate.3195
1 files changed, 195 insertions, 0 deletions
diff --git a/src/lib/libc/stdlib/hcreate.3 b/src/lib/libc/stdlib/hcreate.3
new file mode 100644
index 0000000000..d1d4e5c185
--- /dev/null
+++ b/src/lib/libc/stdlib/hcreate.3
@@ -0,0 +1,195 @@
1.\" $OpenBSD: hcreate.3,v 1.1 2004/06/24 04:43:33 millert Exp $
2.\" $NetBSD: hcreate.3,v 1.6 2003/04/16 13:34:46 wiz Exp $
3.\"
4.\" Copyright (c) 1999 The NetBSD Foundation, Inc.
5.\" All rights reserved.
6.\"
7.\" This code is derived from software contributed to The NetBSD Foundation
8.\" by Klaus Klein.
9.\"
10.\" Redistribution and use in source and binary forms, with or without
11.\" modification, are permitted provided that the following conditions
12.\" are met:
13.\" 1. Redistributions of source code must retain the above copyright
14.\" notice, this list of conditions and the following disclaimer.
15.\" 2. Redistributions in binary form must reproduce the above copyright
16.\" notice, this list of conditions and the following disclaimer in the
17.\" documentation and/or other materials provided with the distribution.
18.\" 3. All advertising materials mentioning features or use of this software
19.\" must display the following acknowledgement:
20.\" This product includes software developed by the NetBSD
21.\" Foundation, Inc. and its contributors.
22.\" 4. Neither the name of The NetBSD Foundation nor the names of its
23.\" contributors may be used to endorse or promote products derived
24.\" from this software without specific prior written permission.
25.\"
26.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
27.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
28.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
29.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
30.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
31.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
32.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
33.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
34.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
35.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
36.\" POSSIBILITY OF SUCH DAMAGE.
37.\"
38.Dd February 13, 2001
39.Dt HCREATE 3
40.Os
41.Sh NAME
42.Nm hcreate ,
43.Nm hdestroy ,
44.Nm hsearch
45.Nd manage hash search table
46.Sh SYNOPSIS
47.In search.h
48.Ft int
49.Fn hcreate "size_t nel"
50.Ft void
51.Fn hdestroy "void"
52.Ft ENTRY *
53.Fn hsearch "ENTRY item" "ACTION action"
54.Sh DESCRIPTION
55The
56.Fn hcreate ,
57.Fn hdestroy
58and
59.Fn hsearch
60functions manage hash search tables.
61.Pp
62The
63.Fn hcreate
64function allocates and initializes the table.
65The
66.Fa nel
67argument specifies an estimate of the maximum number of entries to be held
68by the table.
69Unless further memory allocation fails, supplying an insufficient
70.Fa nel
71value will not result in functional harm, although a performance degradation
72may occur.
73Initialization using the
74.Fn hcreate
75function is mandatory prior to any access operations using
76.Fn hsearch .
77.Pp
78The
79.Fn hdestroy
80function destroys a table previously created using
81.Fn hcreate .
82After a call to
83.Fn hdestroy ,
84the data can no longer be accessed.
85.Pp
86The
87.Fn hsearch
88function is used to search to the hash table.
89It returns a pointer into the
90hash table indicating the address of an item.
91The
92.Fa item
93argument is of type
94.Dv ENTRY ,
95a structural type which contains the following members:
96.Bl -tag -compact -offset indent -width voidX*dataXX
97.It Fa char *key
98comparison key.
99.It Fa void *data
100pointer to data associated with
101.Fa key .
102.El
103.Pp
104The key comparison function used by
105.Fn hsearch
106is
107.Xr strcmp 3 .
108.Pp
109The
110.Fa action
111argument is of type
112.Dv ACTION ,
113an enumeration type which defines the following values:
114.Bl -tag -compact -offset indent -width ENTERXX
115.It Dv ENTER
116Insert
117.Fa item
118into the hash table.
119If an existing item with the same key is found, it is not replaced.
120Note that the
121.Fa key
122and
123.Fa data
124elements of
125.Fa item
126are used directly by the new table entry.
127The storage for the
128key must not be modified during the lifetime of the hash table.
129.It Dv FIND
130Search the hash table without inserting
131.Fa item .
132.El
133.Sh RETURN VALUES
134If successful, the
135.Fn hcreate
136function returns a non-zero value.
137Otherwise, a value of 0 is returned and
138.Va errno
139is set to indicate the error.
140.Pp
141The
142.Fn hdestroy
143functions
144returns no value.
145.Pp
146If successful, the
147.Fn hsearch
148function returns a pointer to hash table entry matching
149the provided key.
150If the action is
151.Dv FIND
152and the item was not found, or if the action is
153.Dv ENTER
154and the insertion failed,
155.Dv NULL
156is returned and
157.Va errno
158is set to indicate the error.
159If the action is
160.Dv ENTER
161and an entry already existed in the table matching the given
162key, the existing entry is returned and is not replaced.
163.Sh ERRORS
164The
165.Fn hcreate
166and
167.Fn hsearch
168functions will fail if:
169.Bl -tag -width Er
170.It Bq Er ENOMEM
171Insufficient memory is available.
172.El
173.Sh SEE ALSO
174.Xr bsearch 3 ,
175.Xr lsearch 3 ,
176.Xr malloc 3 ,
177.Xr strcmp 3
178.Sh STANDARDS
179The
180.Fn hcreate ,
181.Fn hdestroy
182and
183.Fn hsearch
184functions conform to
185.St -xpg4.2 .
186.Sh HISTORY
187The
188.Fn hcreate ,
189.Fn hdestroy
190and
191.Fn hsearch
192functions first appeared in
193.At V .
194.Sh BUGS
195The interface permits the use of only one hash table at a time.
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-04-26 13:02:33 +0000