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