libs/dbprim/doc/man/man3/dbprim_hash.3

   1 .TH "Hash tables" 3 "6 Mar 2003" "dbprim" \" -*- nroff -*-
   2 .ad l
   3 .nh
   4 .SH NAME
   5 Hash tables \- Operations for hash tables.
   6 More...
   7 .SS "Defines"
   8
   9 .in +1c
  10 .ti -1c
  11 .RI "#define \fBHASH_FLAG_AUTOGROW\fP"
  12 .br
  13 .RI "\fIFlag permitting a hash table to automatically grow.\fP"
  14 .ti -1c
  15 .RI "#define \fBHASH_FLAG_AUTOSHRINK\fP"
  16 .br
  17 .RI "\fIFlag permitting a hash table to automatically shrink.\fP"
  18 .ti -1c
  19 .RI "#define \fBHASH_TABLE_INIT\fP(flags, func, comp, resize, extra)"
  20 .br
  21 .RI "\fIHash table static initializer.\fP"
  22 .ti -1c
  23 .RI "#define \fBht_verify\fP(table)"
  24 .br
  25 .RI "\fIHash table verification macro.\fP"
  26 .ti -1c
  27 .RI "#define \fBht_flags\fP(table)"
  28 .br
  29 .RI "\fIHash table flags.\fP"
  30 .ti -1c
  31 .RI "#define \fBht_frozen\fP(table)"
  32 .br
  33 .RI "\fIDetermine if a hash table is frozen.\fP"
  34 .ti -1c
  35 .RI "#define \fBht_modulus\fP(table)"
  36 .br
  37 .RI "\fIHash table modulus.\fP"
  38 .ti -1c
  39 .RI "#define \fBht_count\fP(table)"
  40 .br
  41 .RI "\fIHash table count.\fP"
  42 .ti -1c
  43 .RI "#define \fBht_func\fP(table)"
  44 .br
  45 .RI "\fIHash table hash function.\fP"
  46 .ti -1c
  47 .RI "#define \fBht_comp\fP(table)"
  48 .br
  49 .RI "\fIHash table comparison function.\fP"
  50 .ti -1c
  51 .RI "#define \fBht_rsize\fP(table)"
  52 .br
  53 .RI "\fIHash table resize callback function.\fP"
  54 .ti -1c
  55 .RI "#define \fBht_extra\fP(table)"
  56 .br
  57 .RI "\fIExtra pointer data in a hash table.\fP"
  58 .ti -1c
  59 .RI "#define \fBht_size\fP(table)"
  60 .br
  61 .RI "\fIHash table memory size.\fP"
  62 .ti -1c
  63 .RI "#define \fBHASH_ENTRY_INIT\fP(value)"
  64 .br
  65 .RI "\fIHash table entry static initializer.\fP"
  66 .ti -1c
  67 .RI "#define \fBhe_verify\fP(entry)"
  68 .br
  69 .RI "\fIHash table entry verification macro.\fP"
  70 .ti -1c
  71 .RI "#define \fBhe_link\fP(entry)"
  72 .br
  73 .RI "\fIHash table entry linked list element.\fP"
  74 .ti -1c
  75 .RI "#define \fBhe_flags\fP(entry)"
  76 .br
  77 .RI "\fIHash table entry flags.\fP"
  78 .ti -1c
  79 .RI "#define \fBhe_table\fP(entry)"
  80 .br
  81 .RI "\fIHash table entry table pointer.\fP"
  82 .ti -1c
  83 .RI "#define \fBhe_hash\fP(entry)"
  84 .br
  85 .RI "\fIHash table entry hash value.\fP"
  86 .ti -1c
  87 .RI "#define \fBhe_key\fP(entry)"
  88 .br
  89 .RI "\fIHash table entry key pointer.\fP"
  90 .ti -1c
  91 .RI "#define \fBhe_value\fP(entry)"
  92 .br
  93 .RI "\fIHash table entry value pointer.\fP"
  94 .ti -1c
  95 .RI "#define \fBst_rsize\fP(table)"
  96 .br
  97 .RI "\fISparse matrix table resize callback function.\fP"
  98 .in -1c
  99 .SS "Typedefs"
 100
 101 .in +1c
 102 .ti -1c
 103 .RI "typedef struct _hash_table_s \fBhash_table_t\fP"
 104 .br
 105 .RI "\fIHash table.\fP"
 106 .ti -1c
 107 .RI "typedef struct _hash_entry_s \fBhash_entry_t\fP"
 108 .br
 109 .RI "\fIHash table entry.\fP"
 110 .ti -1c
 111 .RI "typedef unsigned long (* \fBhash_iter_t\fP )(\fBhash_table_t\fP *, \fBhash_entry_t\fP *, void *)"
 112 .br
 113 .RI "\fIHash table iteration callback.\fP"
 114 .ti -1c
 115 .RI "typedef unsigned long (* \fBhash_func_t\fP )(\fBhash_table_t\fP *, \fBdb_key_t\fP *)"
 116 .br
 117 .RI "\fIHash function callback.\fP"
 118 .ti -1c
 119 .RI "typedef unsigned long (* \fBhash_comp_t\fP )(\fBhash_table_t\fP *, \fBdb_key_t\fP *, \fBdb_key_t\fP *)"
 120 .br
 121 .RI "\fIHash table comparison callback.\fP"
 122 .ti -1c
 123 .RI "typedef unsigned long (* \fBhash_resize_t\fP )(\fBhash_table_t\fP *, unsigned long)"
 124 .br
 125 .RI "\fIHash table resize callback.\fP"
 126 .in -1c
 127 .SS "Functions"
 128
 129 .in +1c
 130 .ti -1c
 131 .RI "unsigned long \fBht_init\fP (\fBhash_table_t\fP *table, unsigned long flags, \fBhash_func_t\fP func, \fBhash_comp_t\fP comp, \fBhash_resize_t\fP resize, void *extra, unsigned long init_mod)"
 132 .br
 133 .RI "\fIDynamically initialize a hash table.\fP"
 134 .ti -1c
 135 .RI "unsigned long \fBht_add\fP (\fBhash_table_t\fP *table, \fBhash_entry_t\fP *entry, \fBdb_key_t\fP *key)"
 136 .br
 137 .RI "\fIAdd an entry to a hash table.\fP"
 138 .ti -1c
 139 .RI "unsigned long \fBht_move\fP (\fBhash_table_t\fP *table, \fBhash_entry_t\fP *entry, \fBdb_key_t\fP *key)"
 140 .br
 141 .RI "\fIMove an entry in the hash table.\fP"
 142 .ti -1c
 143 .RI "unsigned long \fBht_remove\fP (\fBhash_table_t\fP *table, \fBhash_entry_t\fP *entry)"
 144 .br
 145 .RI "\fIRemove an element from a hash table.\fP"
 146 .ti -1c
 147 .RI "unsigned long \fBht_find\fP (\fBhash_table_t\fP *table, \fBhash_entry_t\fP **entry_p, \fBdb_key_t\fP *key)"
 148 .br
 149 .RI "\fIFind an entry in a hash table.\fP"
 150 .ti -1c
 151 .RI "unsigned long \fBht_iter\fP (\fBhash_table_t\fP *table, \fBhash_iter_t\fP iter_func, void *extra)"
 152 .br
 153 .RI "\fIIterate over each entry in a hash table.\fP"
 154 .ti -1c
 155 .RI "unsigned long \fBht_flush\fP (\fBhash_table_t\fP *table, \fBhash_iter_t\fP flush_func, void *extra)"
 156 .br
 157 .RI "\fIFlush a hash table.\fP"
 158 .ti -1c
 159 .RI "unsigned long \fBht_resize\fP (\fBhash_table_t\fP *table, unsigned long new_size)"
 160 .br
 161 .RI "\fIResize a hash table.\fP"
 162 .ti -1c
 163 .RI "unsigned long \fBht_free\fP (\fBhash_table_t\fP *table)"
 164 .br
 165 .RI "\fIFree memory used by an empty hash table.\fP"
 166 .ti -1c
 167 .RI "unsigned long \fBhe_init\fP (\fBhash_entry_t\fP *entry, void *value)"
 168 .br
 169 .RI "\fIDynamically initialize a hash table entry.\fP"
 170 .in -1c
 171 .SH "DETAILED DESCRIPTION"
 172 .PP
 173 Hash tables are a basic data structure used in building databases. Hash tables provide a means of storing data such that an arbitrary entry may be looked up efficiently. This library implements a hash table that may optionally grow and shrink to provide maximum efficiency. The implementation is with two kinds of caller-allocated structures--a \fBhash_table_t\fP structure that describes the table and a \fBhash_entry_t\fP structure for each entry in the table. The library allocates a bucket array which must be released with the \fBht_free\fP() function when the hash table has been emptied. Additionally, the hash table may be manually resized with the \fBht_resize\fP() function.
 174 .PP
 175 Entries may be added to and removed from the table using the \fBht_add\fP() and \fBht_remove\fP() functions. Additionally, the key on a given entry may be changed using the \fBht_move\fP() function. Of course, any given entry may be looked up using the \fBht_find\fP() function, and \fBht_iter\fP() will execute a user-defined function for each entry in the hash table (in an unspecified order). The \fBht_flush\fP() function will remove all entries from the hash table, optionally executing a user-specified clean-up function.
 176 .SH "DEFINE DOCUMENTATION"
 177 .PP
 178 .SS "#define HASH_ENTRY_INIT(value)"
 179 .PP
 180 .PP
 181  This macro statically initializes a \fBhash_entry_t\fP.
 182 .PP
 183 \fBParameters: \fP
 184 .in +1c
 185 .TP
 186 \fB\fIvalue\fP\fP
 187 A pointer to \fCvoid\fP representing the object associated with the entry.
 188 .SS "#define HASH_FLAG_AUTOGROW"
 189 .PP
 190 .PP
 191  If passed in to \fBHASH_TABLE_INIT\fP() or \fBht_init\fP(), allows the hash table to grow automatically.
 192 .SS "#define HASH_FLAG_AUTOSHRINK"
 193 .PP
 194 .PP
 195  If passed in to \fBHASH_TABLE_INIT\fP() or \fBht_init\fP(), allows the hash table to shrink automatically.
 196 .SS "#define HASH_TABLE_INIT(flags, func, comp, resize, extra)"
 197 .PP
 198 .PP
 199  This macro statically initializes a \fBhash_table_t\fP.
 200 .PP
 201 \fBParameters: \fP
 202 .in +1c
 203 .TP
 204 \fB\fIflags\fP\fP
 205 A bit-wise OR of \fBHASH_FLAG_AUTOGROW\fP and \fBHASH_FLAG_AUTOSHRINK\fP. If neither behavior is desired, use 0.
 206 .TP
 207 \fB\fIfunc\fP\fP
 208 A \fBhash_func_t\fP function pointer for a hash function.
 209 .TP
 210 \fB\fIcomp\fP\fP
 211 A \fBhash_comp_t\fP function pointer for a comparison function.
 212 .TP
 213 \fB\fIresize\fP\fP
 214 A \fBhash_resize_t\fP function pointer for determining whether resizing is permitted and/or for notification of the resize.
 215 .TP
 216 \fB\fIextra\fP\fP
 217 Extra pointer data that should be associated with the hash table.
 218 .SS "#define he_flags(entry)"
 219 .PP
 220 .PP
 221  This macro retrieves a set of user-defined flags associated with the entry. It may be used as an lvalue to set those flags.
 222 .PP
 223 \fBParameters: \fP
 224 .in +1c
 225 .TP
 226 \fB\fIentry\fP\fP
 227 A pointer to a \fBhash_entry_t\fP.
 228 .PP
 229 \fBReturns: \fP
 230 .in +1c
 231 An \fCunsigned long\fP containing the flags associated with the entry.
 232 .SS "#define he_hash(entry)"
 233 .PP
 234 .PP
 235  This macro retrieves the hash value of the given hash entry. If the hash table has been resized, this value may not be the same as a previous value.
 236 .PP
 237 \fBParameters: \fP
 238 .in +1c
 239 .TP
 240 \fB\fIentry\fP\fP
 241 A pointer to a \fBhash_entry_t\fP.
 242 .PP
 243 \fBReturns: \fP
 244 .in +1c
 245 An \fCunsigned long\fP containing the hash code for the entry.
 246 .SS "#define he_key(entry)"
 247 .PP
 248 .PP
 249  This macro retrieves the key associated with the hash table entry.
 250 .PP
 251 \fBParameters: \fP
 252 .in +1c
 253 .TP
 254 \fB\fIentry\fP\fP
 255 A pointer to a \fBhash_entry_t\fP.
 256 .PP
 257 \fBReturns: \fP
 258 .in +1c
 259 A pointer to a \fBdb_key_t\fP.
 260 .SS "#define he_link(entry)"
 261 .PP
 262 .PP
 263  This macro provides access to the linked list element buried in the hash table entry. It should *not* be used on entries currently in a hash table. The purpose of this macro is to allow an object containing a hash table entry to be placed upon a free list.
 264 .PP
 265 \fBParameters: \fP
 266 .in +1c
 267 .TP
 268 \fB\fIentry\fP\fP
 269 A pointer to a \fBhash_entry_t\fP.
 270 .PP
 271 \fBReturns: \fP
 272 .in +1c
 273 A pointer to a \fBlink_elem_t\fP.
 274 .SS "#define he_table(entry)"
 275 .PP
 276 .PP
 277  This macro retrieves a pointer to the hash table the entry is in.
 278 .PP
 279 \fBParameters: \fP
 280 .in +1c
 281 .TP
 282 \fB\fIentry\fP\fP
 283 A pointer to a \fBhash_entry_t\fP.
 284 .PP
 285 \fBReturns: \fP
 286 .in +1c
 287 A pointer to a \fBhash_table_t\fP.
 288 .SS "#define he_value(entry)"
 289 .PP
 290 .PP
 291  This macro retrieves the value associated with the hash table entry. It may be treated as an lvalue to change that value. Care should be taken when using this option.
 292 .PP
 293 \fBParameters: \fP
 294 .in +1c
 295 .TP
 296 \fB\fIentry\fP\fP
 297 A pointer to a \fBhash_entry_t\fP.
 298 .PP
 299 \fBReturns: \fP
 300 .in +1c
 301 A pointer to \fCvoid\fP representing the value associated with this entry.
 302 .SS "#define he_verify(entry)"
 303 .PP
 304 .PP
 305  This macro verifies that a given pointer actually does point to a hash table entry.
 306 .PP
 307 \fBParameters: \fP
 308 .in +1c
 309 .TP
 310 \fB\fIentry\fP\fP
 311 A pointer to a \fBhash_entry_t\fP.
 312 .PP
 313 \fBReturns: \fP
 314 .in +1c
 315 Boolean true if \fCentry\fP is a valid hash table entry or false otherwise.
 316 .SS "#define ht_comp(table)"
 317 .PP
 318 .PP
 319  This macro retrieves the comparison function pointer.
 320 .PP
 321 \fBParameters: \fP
 322 .in +1c
 323 .TP
 324 \fB\fItable\fP\fP
 325 A pointer to a \fBhash_table_t\fP.
 326 .PP
 327 \fBReturns: \fP
 328 .in +1c
 329 A \fBhash_comp_t\fP.
 330 .SS "#define ht_count(table)"
 331 .PP
 332 .PP
 333  This macro retrieves the total number of items actually in the hash table.
 334 .PP
 335 \fBParameters: \fP
 336 .in +1c
 337 .TP
 338 \fB\fItable\fP\fP
 339 A pointer to a \fBhash_table_t\fP.
 340 .PP
 341 \fBReturns: \fP
 342 .in +1c
 343 An \fCunsigned long\fP containing a count of the number of items in the hash table.
 344 .SS "#define ht_extra(table)"
 345 .PP
 346 .PP
 347  This macro retrieves the extra pointer data associated with a particular hash table.
 348 .PP
 349 \fBParameters: \fP
 350 .in +1c
 351 .TP
 352 \fB\fItable\fP\fP
 353 A pointer to a \fBhash_table_t\fP.
 354 .PP
 355 \fBReturns: \fP
 356 .in +1c
 357 A pointer to \fCvoid\fP.
 358 .SS "#define ht_flags(table)"
 359 .PP
 360 .PP
 361  This macro retrieves the flags associated with the hash table. Only \fBHASH_FLAG_AUTOGROW\fP and \fBHASH_FLAG_AUTOSHRINK\fP have any meaning to the application; all other bits are reserved for use in the library. This macro may be used as an lvalue, but care must be taken to avoid modifying the library-specific bits.
 362 .PP
 363 \fBParameters: \fP
 364 .in +1c
 365 .TP
 366 \fB\fItable\fP\fP
 367 A pointer to a \fBhash_table_t\fP.
 368 .PP
 369 \fBReturns: \fP
 370 .in +1c
 371 An \fCunsigned long\fP containing the flags for the hash table.
 372 .SS "#define ht_frozen(table)"
 373 .PP
 374 .PP
 375  This macro returns a non-zero value if the table is currently frozen. The hash table may be frozen if there is an iteration in progress.
 376 .PP
 377 \fBParameters: \fP
 378 .in +1c
 379 .TP
 380 \fB\fItable\fP\fP
 381 A pointer to a \fBhash_table_t\fP.
 382 .PP
 383 \fBReturns: \fP
 384 .in +1c
 385 A zero value if the table is not frozen or a non-zero value if the table is frozen.
 386 .SS "#define ht_func(table)"
 387 .PP
 388 .PP
 389  This macro retrieves the hash function pointer.
 390 .PP
 391 \fBParameters: \fP
 392 .in +1c
 393 .TP
 394 \fB\fItable\fP\fP
 395 A pointer to a \fBhash_table_t\fP.
 396 .PP
 397 \fBReturns: \fP
 398 .in +1c
 399 A \fBhash_func_t\fP.
 400 .SS "#define ht_modulus(table)"
 401 .PP
 402 .PP
 403  This macro retrieves the number of buckets allocated for the hash table. An application may wish to save this value between invocations to avoid the overhead of growing the table while filling it with data.
 404 .PP
 405 \fBParameters: \fP
 406 .in +1c
 407 .TP
 408 \fB\fItable\fP\fP
 409 A pointer to a \fBhash_table_t\fP.
 410 .PP
 411 \fBReturns: \fP
 412 .in +1c
 413 An \fCunsigned long\fP containing the number of buckets allocated for the hash table.
 414 .SS "#define ht_rsize(table)"
 415 .PP
 416 .PP
 417  This macro retrieves the resize callback function pointer.
 418 .PP
 419 \fBParameters: \fP
 420 .in +1c
 421 .TP
 422 \fB\fItable\fP\fP
 423 A pointer to a \fBhash_table_t\fP.
 424 .PP
 425 \fBReturns: \fP
 426 .in +1c
 427 A \fBhash_resize_t\fP.
 428 .SS "#define ht_size(table)"
 429 .PP
 430 .PP
 431  This macro returns the physical size of the bucket array allocated by the library for this hash table.
 432 .PP
 433 \fBParameters: \fP
 434 .in +1c
 435 .TP
 436 \fB\fItable\fP\fP
 437 A pointer to a \fBhash_table_t\fP.
 438 .PP
 439 \fBReturns: \fP
 440 .in +1c
 441 A \fCsize_t\fP.
 442 .SS "#define ht_verify(table)"
 443 .PP
 444 .PP
 445  This macro verifies that a given pointer actually does point to a hash table.
 446 .PP
 447 \fBParameters: \fP
 448 .in +1c
 449 .TP
 450 \fB\fItable\fP\fP
 451 A pointer to a \fBhash_table_t\fP.
 452 .PP
 453 \fBReturns: \fP
 454 .in +1c
 455 Boolean true if \fCtable\fP is a valid hash table or false otherwise.
 456 .SS "#define st_rsize(table)"
 457 .PP
 458 .PP
 459  This macro retrieves the resize callback function pointer.
 460 .PP
 461 \fBParameters: \fP
 462 .in +1c
 463 .TP
 464 \fB\fItable\fP\fP
 465 A pointer to a \fBsmat_table_t\fP.
 466 .PP
 467 \fBReturns: \fP
 468 .in +1c
 469 A \fBsmat_resize_t\fP.
 470 .SH "TYPEDEF DOCUMENTATION"
 471 .PP
 472 .SS "typedef unsigned long(* hash_comp_t)(\fBhash_table_t\fP *, \fBdb_key_t\fP *, \fBdb_key_t\fP *)"
 473 .PP
 474 .PP
 475  This function pointer references a callback used to compare entries in a hash table. It should return 0 for identical entries and non-zero otherwise. No assumptions should be made about the order in which the two keys are passed to this function.
 476 .SS "typedef struct _hash_entry_s hash_entry_t"
 477 .PP
 478 .PP
 479  This structure represents a single entry of a hash table.
 480 .SS "typedef unsigned long(* hash_func_t)(\fBhash_table_t\fP *, \fBdb_key_t\fP *)"
 481 .PP
 482 .PP
 483  This function is associated with a hash table, and is responsible for generating a hash value. The full 32-bit range of an \fCunsigned long\fP should be used--do *not* reduce the hash value by the modulus of the hash table.
 484 .SS "typedef unsigned long(* hash_iter_t)(\fBhash_table_t\fP *, \fBhash_entry_t\fP *, void *)"
 485 .PP
 486 .PP
 487  This function pointer references a callback used by \fBht_iter\fP() and \fBht_flush\fP(). It should return 0 for success. A non-zero return value will terminate the operation and will become the return value of the \fBht_iter\fP() or \fBht_flush\fP() call.
 488 .SS "typedef unsigned long(* hash_resize_t)(\fBhash_table_t\fP *, unsigned long)"
 489 .PP
 490 .PP
 491  This function pointer references a callback that will be called with both the old and new hash table sizes whenever a hash table is resized. It should return non-zero only when the resize should be inhibited.
 492 .SS "typedef struct _hash_table_s hash_table_t"
 493 .PP
 494 .PP
 495  This structure is the basis of all hash tables maintained by this library.
 496 .SH "FUNCTION DOCUMENTATION"
 497 .PP
 498 .SS "unsigned long he_init (\fBhash_entry_t\fP * entry, void * value)"
 499 .PP
 500 .PP
 501  This function dynamically initializes a hash table entry.
 502 .PP
 503 \fBParameters: \fP
 504 .in +1c
 505 .TP
 506 \fB\fIentry\fP\fP
 507 A pointer to a \fBhash_entry_t\fP to be initialized.
 508 .TP
 509 \fB\fIvalue\fP\fP
 510 A pointer to \fCvoid\fP which will be the value of the hash table entry.
 511 .PP
 512 \fBReturn values: \fP
 513 .in +1c
 514 .TP
 515 \fB\fIDB_ERR_BADARGS\fP\fP
 516 A \fCNULL\fP pointer was passed for \fCentry\fP.
 517 .SS "unsigned long ht_add (\fBhash_table_t\fP * table, \fBhash_entry_t\fP * entry, \fBdb_key_t\fP * key)"
 518 .PP
 519 .PP
 520  This function adds an entry to a hash table.
 521 .PP
 522 \fBParameters: \fP
 523 .in +1c
 524 .TP
 525 \fB\fItable\fP\fP
 526 A pointer to a \fBhash_table_t\fP.
 527 .TP
 528 \fB\fIentry\fP\fP
 529 A pointer to a \fBhash_entry_t\fP to be added to the table.
 530 .TP
 531 \fB\fIkey\fP\fP
 532 A pointer to a \fBdb_key_t\fP containing the key for the entry.
 533 .PP
 534 \fBReturn values: \fP
 535 .in +1c
 536 .TP
 537 \fB\fIDB_ERR_BADARGS\fP\fP
 538 An invalid argument was given.
 539 .TP
 540 \fB\fIDB_ERR_BUSY\fP\fP
 541 The entry is already in a table.
 542 .TP
 543 \fB\fIDB_ERR_FROZEN\fP\fP
 544 The table is currently frozen.
 545 .TP
 546 \fB\fIDB_ERR_NOTABLE\fP\fP
 547 The bucket table has not been allocated and automatic growth is not enabled.
 548 .TP
 549 \fB\fIDB_ERR_DUPLICATE\fP\fP
 550 The entry is a duplicate of an existing entry.
 551 .TP
 552 \fB\fIDB_ERR_UNRECOVERABLE\fP\fP
 553 An unrecoverable error occurred while resizing the table.
 554 .SS "unsigned long ht_find (\fBhash_table_t\fP * table, \fBhash_entry_t\fP ** entry_p, \fBdb_key_t\fP * key)"
 555 .PP
 556 .PP
 557  This function looks up an entry matching the given \fCkey\fP.
 558 .PP
 559 \fBParameters: \fP
 560 .in +1c
 561 .TP
 562 \fB\fItable\fP\fP
 563 A pointer to a \fBhash_table_t\fP.
 564 .TP
 565 \fB\fIentry_p\fP\fP
 566 A pointer to a pointer to a \fBhash_entry_t\fP. This is a result parameter. If \fCNULL\fP is passed, the lookup will be performed and an appropriate error code returned.
 567 .TP
 568 \fB\fIkey\fP\fP
 569 A pointer to a \fBdb_key_t\fP describing the item to find.
 570 .PP
 571 \fBReturn values: \fP
 572 .in +1c
 573 .TP
 574 \fB\fIDB_ERR_BADARGS\fP\fP
 575 An argument was invalid.
 576 .TP
 577 \fB\fIDB_ERR_NOENTRY\fP\fP
 578 No matching entry was found.
 579 .SS "unsigned long ht_flush (\fBhash_table_t\fP * table, \fBhash_iter_t\fP flush_func, void * extra)"
 580 .PP
 581 .PP
 582  This function flushes a hash table--that is, it removes each entry from the table. If a \fCflush_func\fP is specified, it will be called on the entry after it has been removed from the table, and may safely call \fCfree()\fP.
 583 .PP
 584 \fBParameters: \fP
 585 .in +1c
 586 .TP
 587 \fB\fItable\fP\fP
 588 A pointer to a \fBhash_table_t\fP.
 589 .TP
 590 \fB\fIflush_func\fP\fP
 591 A pointer to a callback function used to perform user-specified actions on an entry after removing it from the table. May be \fCNULL\fP. See the documentation for \fBhash_iter_t\fP for more information.
 592 .TP
 593 \fB\fIextra\fP\fP
 594 A \fCvoid\fP pointer that will be passed to \fCflush_func\fP.
 595 .PP
 596 \fBReturn values: \fP
 597 .in +1c
 598 .TP
 599 \fB\fIDB_ERR_BADARGS\fP\fP
 600 An argument was invalid.
 601 .TP
 602 \fB\fIDB_ERR_FROZEN\fP\fP
 603 The hash table is frozen.
 604 .SS "unsigned long ht_free (\fBhash_table_t\fP * table)"
 605 .PP
 606 .PP
 607  This function releases the memory used by the bucket table in an empty hash table.
 608 .PP
 609 \fBParameters: \fP
 610 .in +1c
 611 .TP
 612 \fB\fItable\fP\fP
 613 A pointer to a \fBhash_table_t\fP.
 614 .PP
 615 \fBReturn values: \fP
 616 .in +1c
 617 .TP
 618 \fB\fIDB_ERR_BADARGS\fP\fP
 619 An invalid argument was given.
 620 .TP
 621 \fB\fIDB_ERR_FROZEN\fP\fP
 622 The table is frozen.
 623 .TP
 624 \fB\fIDB_ERR_NOTEMPTY\fP\fP
 625 The table is not empty.
 626 .SS "unsigned long ht_init (\fBhash_table_t\fP * table, unsigned long flags, \fBhash_func_t\fP func, \fBhash_comp_t\fP comp, \fBhash_resize_t\fP resize, void * extra, unsigned long init_mod)"
 627 .PP
 628 .PP
 629  This function dynamically initializes a hash table.
 630 .PP
 631 \fBParameters: \fP
 632 .in +1c
 633 .TP
 634 \fB\fItable\fP\fP
 635 A pointer to a \fBhash_table_t\fP to be initialized.
 636 .TP
 637 \fB\fIflags\fP\fP
 638 A bit-wise OR of \fBHASH_FLAG_AUTOGROW\fP and \fBHASH_FLAG_AUTOSHRINK\fP. If neither behavior is desired, use 0.
 639 .TP
 640 \fB\fIfunc\fP\fP
 641 A \fBhash_func_t\fP function pointer for a hash function.
 642 .TP
 643 \fB\fIcomp\fP\fP
 644 A \fBhash_comp_t\fP function pointer for a comparison function.
 645 .TP
 646 \fB\fIresize\fP\fP
 647 A \fBhash_resize_t\fP function pointer for determining whether resizing is permitted and/or for notification of the resize.
 648 .TP
 649 \fB\fIextra\fP\fP
 650 Extra pointer data that should be associated with the hash table.
 651 .TP
 652 \fB\fIinit_mod\fP\fP
 653 An initial modulus for the table. This will presumably be extracted by \fBht_modulus\fP() in a previous invocation of the application. A 0 value is valid.
 654 .PP
 655 \fBReturn values: \fP
 656 .in +1c
 657 .TP
 658 \fB\fIDB_ERR_BADARGS\fP\fP
 659 An invalid argument was given.
 660 .TP
 661 \fB\fIENOMEM\fP\fP
 662 Unable to allocate memory.
 663 .SS "unsigned long ht_iter (\fBhash_table_t\fP * table, \fBhash_iter_t\fP iter_func, void * extra)"
 664 .PP
 665 .PP
 666  This function iterates over every entry in a hash table (in an unspecified order), executing the given \fCiter_func\fP on each entry.
 667 .PP
 668 \fBParameters: \fP
 669 .in +1c
 670 .TP
 671 \fB\fItable\fP\fP
 672 A pointer to a \fBhash_table_t\fP.
 673 .TP
 674 \fB\fIiter_func\fP\fP
 675 A pointer to a callback function used to perform user-specified actions on an entry in a hash table. \fCNULL\fP is an invalid value. See the documentation for \fBhash_iter_t\fP for more information.
 676 .TP
 677 \fB\fIextra\fP\fP
 678 A \fCvoid\fP pointer that will be passed to \fCiter_func\fP.
 679 .PP
 680 \fBReturn values: \fP
 681 .in +1c
 682 .TP
 683 \fB\fIDB_ERR_BADARGS\fP\fP
 684 An argument was invalid.
 685 .TP
 686 \fB\fIDB_ERR_FROZEN\fP\fP
 687 The hash table is frozen.
 688 .SS "unsigned long ht_move (\fBhash_table_t\fP * table, \fBhash_entry_t\fP * entry, \fBdb_key_t\fP * key)"
 689 .PP
 690 .PP
 691  This function moves an existing entry in the hash table to correspond to the new key.
 692 .PP
 693 \fBParameters: \fP
 694 .in +1c
 695 .TP
 696 \fB\fItable\fP\fP
 697 A pointer to a \fBhash_table_t\fP.
 698 .TP
 699 \fB\fIentry\fP\fP
 700 A pointer to a \fBhash_entry_t\fP to be moved. It must already be in the hash table.
 701 .TP
 702 \fB\fIkey\fP\fP
 703 A pointer to a \fBdb_key_t\fP describing the new key for the entry.
 704 .PP
 705 \fBReturn values: \fP
 706 .in +1c
 707 .TP
 708 \fB\fIDB_ERR_BADARGS\fP\fP
 709 An invalid argument was given.
 710 .TP
 711 \fB\fIDB_ERR_UNUSED\fP\fP
 712 Entry is not in a hash table.
 713 .TP
 714 \fB\fIDB_ERR_WRONGTABLE\fP\fP
 715 Entry is not in this hash table.
 716 .TP
 717 \fB\fIDB_ERR_FROZEN\fP\fP
 718 Hash table is frozen.
 719 .TP
 720 \fB\fIDB_ERR_DUPLICATE\fP\fP
 721 New key is a duplicate of an existing key.
 722 .TP
 723 \fB\fIDB_ERR_READDFAILED\fP\fP
 724 Unable to re-add entry to table.
 725 .SS "unsigned long ht_remove (\fBhash_table_t\fP * table, \fBhash_entry_t\fP * entry)"
 726 .PP
 727 .PP
 728  This function removes the given element from the specified hash table.
 729 .PP
 730 \fBParameters: \fP
 731 .in +1c
 732 .TP
 733 \fB\fItable\fP\fP
 734 A pointer to a \fBhash_table_t\fP.
 735 .TP
 736 \fB\fIentry\fP\fP
 737 A pointer to a \fBhash_entry_t\fP to be removed from the table.
 738 .PP
 739 \fBReturn values: \fP
 740 .in +1c
 741 .TP
 742 \fB\fIDB_ERR_BADARGS\fP\fP
 743 An invalid argument was given.
 744 .TP
 745 \fB\fIDB_ERR_UNUSED\fP\fP
 746 Entry is not in a hash table.
 747 .TP
 748 \fB\fIDB_ERR_WRONGTABLE\fP\fP
 749 Entry is not in this hash table.
 750 .TP
 751 \fB\fIDB_ERR_FROZEN\fP\fP
 752 Hash table is frozen.
 753 .TP
 754 \fB\fIDB_ERR_UNRECOVERABLE\fP\fP
 755 An unrecoverable error occurred while resizing the table.
 756 .SS "unsigned long ht_resize (\fBhash_table_t\fP * table, unsigned long new_size)"
 757 .PP
 758 .PP
 759  This function resizes a hash table to the given \fCnew_size\fP. If \fCnew_size\fP is 0, then an appropriate new size based on the current number of items in the hash table will be selected.
 760 .PP
 761 \fBParameters: \fP
 762 .in +1c
 763 .TP
 764 \fB\fItable\fP\fP
 765 A pointer to a \fBhash_table_t\fP.
 766 .TP
 767 \fB\fInew_size\fP\fP
 768 A new size value for the table.
 769 .PP
 770 \fBReturn values: \fP
 771 .in +1c
 772 .TP
 773 \fB\fIDB_ERR_BADARGS\fP\fP
 774 An argument was invalid.
 775 .TP
 776 \fB\fIDB_ERR_FROZEN\fP\fP
 777 The table is currently frozen.
 778 .TP
 779 \fB\fIDB_ERR_UNRECOVERABLE\fP\fP
 780 A catastrophic error was encountered. The table is now unusable.
 781 .TP
 782 \fB\fIENOMEM\fP\fP
 783 No memory could be allocated for the new bucket table.