Unix/Linux Go Back    


NetBSD 6.1.5 - man page for hdestroy_r (netbsd section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


HCREATE(3)			   BSD Library Functions Manual 		       HCREATE(3)

NAME
     hcreate, hcreate_r, hdestroy, hdestroy_r, hsearch, hsearch_r -- manage hash search table

LIBRARY
     Standard C Library (libc, -lc)

SYNOPSIS
     #include <search.h>

     int
     hcreate(size_t nel);

     int
     hcreate_r(size_t nel, struct hsearch_data *table);

     void
     hdestroy(void);

     void
     hdestroy_r(struct hsearch_data *table);

     ENTRY *
     hsearch(ENTRY item, ACTION action);

     int
     hsearch_r(ENTRY item, ACTION action, ENTRY ** itemp, struct hsearch_data *table);

DESCRIPTION
     The hcreate(), hcreate_r(), hdestroy(), hdestroy_r() hsearch(), and hsearch_r() 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 val-
     ues:

	   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).

     The hcreate_r(), hdestroy_r(), and hsearch_r() functions are re-entrant versions of the
     above functions that can operate on a table supplied by the user.	The hsearch_r() function
     returns 0 if the action is ENTER and the element cannot be created, 1 otherwise.  If the
     element exists or can be created, it will be placed in itemp, otherwise itemp will be set to
     NULL.

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

     The hdestroy() and hdestroy_r() functions return no value.

     If successful, the hsearch() function returns a pointer to 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 exist-
     ing entry is returned and is not replaced.

     The hsearch_r() function returns 1 unless the table is full, when it returns 0.  If
     hsearch() returns 0 or the element is not found, errno is set to indicate the error.

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

     [ENOMEM]		Insufficient memory is available.

     The hsearch() and hsearch_r() functions will also fail if the action is SEARCH and the ele-
     ment is not found:

     [ESRCH]		The item given is not found.

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, Version 2 (``XPG4.2'').

HISTORY
     The hcreate(), hdestroy() and hsearch() functions first appeared in AT&T System V UNIX.  The
     hcreate_r(), hdestroy_r() and hsearch_r() functions are GNU extensions.

CAVEATS
     At least the following limitations can be mentioned:

     o	 The original, non-GNU 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, men-
	 tioning 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.

BSD					September 14, 2011				      BSD
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 02:09 PM.