1.\" $OpenBSD: hcreate.3,v 1.5 2008/06/26 05:42:05 ray 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.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 20.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 21.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 22.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 23.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 24.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 25.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 27.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29.\" POSSIBILITY OF SUCH DAMAGE. 30.\" 31.Dd $Mdocdate: June 26 2008 $ 32.Dt HCREATE 3 33.Os 34.Sh NAME 35.Nm hcreate , 36.Nm hdestroy , 37.Nm hsearch 38.Nd manage hash search table 39.Sh SYNOPSIS 40.In search.h 41.Ft int 42.Fn hcreate "size_t nel" 43.Ft void 44.Fn hdestroy "void" 45.Ft ENTRY * 46.Fn hsearch "ENTRY item" "ACTION action" 47.Sh DESCRIPTION 48The 49.Fn hcreate , 50.Fn hdestroy , 51and 52.Fn hsearch 53functions manage hash search tables. 54.Pp 55The 56.Fn hcreate 57function allocates and initializes the table. 58The 59.Fa nel 60argument specifies an estimate of the maximum number of entries to be held 61by the table. 62Unless further memory allocation fails, supplying an insufficient 63.Fa nel 64value will not result in functional harm, although a performance degradation 65may occur. 66Initialization using the 67.Fn hcreate 68function is mandatory prior to any access operations using 69.Fn hsearch . 70.Pp 71The 72.Fn hdestroy 73function destroys a table previously created using 74.Fn hcreate . 75After a call to 76.Fn hdestroy , 77the data can no longer be accessed. 78.Pp 79The 80.Fn hsearch 81function is used to search to the hash table. 82It returns a pointer into the 83hash table indicating the address of an item. 84The 85.Fa item 86argument is of type 87.Dv ENTRY , 88a structural type which contains the following members: 89.Pp 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 -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 a 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 173These functions conform to 174.St -p1003.1-2004 . 175.Sh HISTORY 176The 177.Fn hcreate , 178.Fn hdestroy 179and 180.Fn hsearch 181functions first appeared in 182.At V . 183.Sh BUGS 184The interface permits the use of only one hash table at a time. 185