lib/libc/stdlib/hcreate.3

   1 .\"     $NetBSD: hcreate.3,v 1.6 2003/04/16 13:34:46 wiz 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
  49 The
  50 .Fn hcreate ,
  51 .Fn hdestroy
  52 and
  53 .Fn hsearch
  54 functions manage hash search tables.
  55 .Pp
  56 The
  57 .Fn hcreate
  58 function allocates and initializes the table.
  59 The
  60 .Fa nel
  61 argument specifies an estimate of the maximum number of entries to be held
  62 by the table.
  63 Unless further memory allocation fails, supplying an insufficient
  64 .Fa nel
  65 value will not result in functional harm, although a performance degradation
  66 may occur.
  67 Initialization using the
  68 .Fn hcreate
  69 function is mandatory prior to any access operations using
  70 .Fn hsearch .
  71 .Pp
  72 The
  73 .Fn hdestroy
  74 function destroys a table previously created using
  75 .Fn hcreate .
  76 After a call to
  77 .Fn hdestroy ,
  78 the data can no longer be accessed.
  79 .Pp
  80 The
  81 .Fn hsearch
  82 function is used to search to the hash table.
  83 It returns a pointer into the
  84 hash table indicating the address of an item.
  85 The
  86 .Fa item
  87 argument is of type
  88 .Dv ENTRY ,
  89 a structural type which contains the following members:
  90 .Bl -tag -compact -offset indent -width voidX*dataXX
  91 .It Fa char *key
  92 comparison key.
  93 .It Fa void *data
  94 pointer to data associated with
  95 .Fa key .
  96 .El
  97 .Pp
  98 The key comparison function used by
  99 .Fn hsearch
 100 is
 101 .Xr strcmp 3 .
 102 .Pp
 103 The
 104 .Fa action
 105 argument is of type
 106 .Dv ACTION ,
 107 an enumeration type which defines the following values:
 108 .Bl -tag -compact -offset indent -width ENTERXX
 109 .It Dv ENTER
 110 Insert
 111 .Fa item
 112 into the hash table.
 113 If an existing item with the same key is found, it is not replaced.
 114 Note that the
 115 .Fa key
 116 and
 117 .Fa data
 118 elements of
 119 .Fa item
 120 are used directly by the new table entry.
 121 The storage for the
 122 key must not be modified during the lifetime of the hash table.
 123 .It Dv FIND
 124 Search the hash table without inserting
 125 .Fa item .
 126 .El
 127 .Sh RETURN VALUES
 128 If successful, the
 129 .Fn hcreate
 130 function returns a non-zero value.
 131 Otherwise, a value of 0 is returned and
 132 .Va errno
 133 is set to indicate the error.
 134 .Pp
 135 The
 136 .Fn hdestroy
 137 functions
 138 returns no value.
 139 .Pp
 140 If successful, the
 141 .Fn hsearch
 142 function returns a pointer to hash table entry matching
 143 the provided key.
 144 If the action is
 145 .Dv FIND
 146 and the item was not found, or if the action is
 147 .Dv ENTER
 148 and the insertion failed,
 149 .Dv NULL
 150 is returned and
 151 .Va errno
 152 is set to indicate the error.
 153 If the action is
 154 .Dv ENTER
 155 and an entry already existed in the table matching the given
 156 key, the existing entry is returned and is not replaced.
 157 .Sh ERRORS
 158 The
 159 .Fn hcreate
 160 and
 161 .Fn hsearch
 162 functions will fail if:
 163 .Bl -tag -width Er
 164 .It Bq Er ENOMEM
 165 Insufficient 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
 173 The
 174 .Fn hcreate ,
 175 .Fn hdestroy
 176 and
 177 .Fn hsearch
 178 functions conform to
 179 .St -xpg4.2 .
 180 .Sh HISTORY
 181 The
 182 .Fn hcreate ,
 183 .Fn hdestroy
 184 and
 185 .Fn hsearch
 186 functions first appeared in
 187 .At V .
 188 .Sh BUGS
 189 The interface permits the use of only one hash table at a time.