hdestroy man page on OpenBSD

Man page or keyword search:  
man Server   11362 pages
apropos Keyword Search (all sections)
Output format
OpenBSD logo
[printable version]

HCREATE(3)		  OpenBSD Programmer's Manual		    HCREATE(3)

NAME
     hcreate, hdestroy, hsearch - manage hash search table

SYNOPSIS
     #include <search.h>

     int
     hcreate(size_t nel);

     void
     hdestroy(void);

     ENTRY *
     hsearch(ENTRY item, ACTION action);

DESCRIPTION
     The hcreate(), hdestroy(), and hsearch() functions manage hash search
     tables.

     The hcreate() function allocates and initializes the table.  The nel
     argument specifies an estimate of the maximum number of entries to be
     held by the table.	 Unless further memory allocation fails, supplying an
     insufficient nel value will not result in functional harm, although a
     performance degradation may occur.	 Initialization using the hcreate()
     function is mandatory prior to any access operations using hsearch().

     The hdestroy() function destroys a table previously created using
     hcreate().	 After a call to hdestroy(), the data can no longer be
     accessed.

     The hsearch() function is used to search to the hash table.  It returns a
     pointer into the hash table indicating the address of an item.  The item
     argument is of type ENTRY, defined in the <search.h> header.  This is a
     structure type that contains two pointers:

	   char *key	comparison key
	   void *data	pointer to data associated with key

     The key comparison function used by hsearch() is strcmp(3).

     The action argument is of type ACTION, an enumeration type which defines
     the following values:

	   ENTER    Insert item into the hash table.  If an existing item with
		    the same key is found, it is not replaced.	Note that the
		    key and data elements of item are used directly by the new
		    table entry.  The storage for the key must not be modified
		    during the lifetime of the hash table.

	   FIND	    Search the hash table without inserting item.

     Note that the comparison key must be allocated using malloc(3) or
     calloc(3) if action is ENTER and hdestroy() will be called.  This is
     because hdestroy() will call free(3) for each comparison key (but not
     data).  Typically the comparison key is allocated by using strdup(3).

RETURN VALUES
     If successful, the hcreate() function returns a non-zero value.
     Otherwise, a value of 0 is returned and errno is set to indicate the
     error.

     The hdestroy() functions returns no value.

     If successful, the hsearch() function returns a pointer to a hash table
     entry matching the provided key.  If the action is FIND and the item was
     not found, or if the action is ENTER and the insertion failed, NULL is
     returned and errno is set to indicate the error.  If the action is ENTER
     and an entry already existed in the table matching the given key, the
     existing entry is returned and is not replaced.

ERRORS
     The hcreate() and hsearch() functions will fail if:

     [ENOMEM]	   Insufficient memory is available.

SEE ALSO
     bsearch(3), lsearch(3), malloc(3), strcmp(3)

STANDARDS
     The hcreate(), hdestroy() and hsearch() functions conform to X/Open
     Portability Guide Issue 4.2 (``XPG4.2'').

HISTORY
     The hcreate(), hdestroy() and hsearch() functions first appeared in AT&T
     System V UNIX.

CAVEATS
     At least the following limitations can be mentioned:

     o	 The interface permits the use of only one hash table at a time.

     o	 Individual hash table entries can be added, but not deleted.

     o	 The standard is indecipherable about the internal memory usage of the
	 functions, mentioning only that ``hcreate() and hsearch() functions
	 may use malloc() to allocate space''.	This limits the portability of
	 the functions, given that other implementations may not free(3) the
	 buffer pointed by key.

OpenBSD 4.9			 July 28, 2010			   OpenBSD 4.9
[top]

List of man pages available for OpenBSD

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net