Index for Section 3

Alphabetical listing for H

Bottom of page

hsearch(3)
NAME
  hsearch, hcreate, hdestroy, hsearch_r, hcreate_r, hdestroy_r - Manage hash
  tables

LIBRARY
  Standard C Library (libc)

SYNOPSIS
  #include <search.h>

  ENTRY *hsearch(
	  ENTRY item,
	  ACTION action);

  int hcreate(
	  size_t nel);

  void hdestroy(void);

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

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

  void hdestroy_r(
	  struct hsearch_data *hsearch_data);

STANDARDS
  Interfaces documented on this reference page conform to industry standards
  as follows:

  hsearch(), hcreate(), hdestroy(): XSH4.2

  Refer to the standards(5) reference page for more information about
  industry standards and associated tags.

PARAMETERS
  item	    Identifies a structure of the type ENTRY as defined in the
	    search.h header file. It contains two pointers:

	    char *key Points to the comparison key string.

	    void *data
		      Points to any other data associated with the char *key
		      parameter.

	    Pointers to types other than char should be cast as char *.

  action    Specifies a value for an ACTION enum type, which indicates what
	    is to be done with an item key when it cannot be found in the
	    hash table.	 The following two actions can be specified for this
	    parameter:

	    ENTER     Enter the key specified by the item parameter into the
		      hash table at the appropriate place.  When the table is
		      full, a null pointer is returned.

	    FIND      Do not enter the item key into the table, but return a
		      null pointer when an item key cannot be found in the
		      hash table.

  nel	    Specifies an estimate of the maximum number of entries that the
	    hash table will contain. Under some circumstances, the hcreate()
	    function may make the hash table larger than specified to obtain
	    mathematically favorable conditions for access to the hash table.

  target    Points to the item actually found.

  hsearch_data
	    Consists of data for the hash table.

DESCRIPTION
  The hsearch(), hcreate(), and hdestroy() functions are used to manage hash
  table operations:

    ·  The hcreate() function initializes the hash table. You must call the
       hcreate() function before calling the hsearch() function.

    ·  The hsearch() function searches a hash table.  It returns a pointer
       into a hash table that indicates where a given entry can be found. The
       hsearch() function uses open addressing with a hash function.

    ·  The hdestroy() function deletes the hash table.	This allows you to
       start a new hash table because only one table may be active at a time.
       After the call to hdestroy(), the hash table data should no longer be
       considered accessible.

  [Tru64 UNIX]	The hsearch_r(), hcreate_r(), and hdestroy_r() functions are
  reentrant versions of hsearch(), hcreate(), and hdestroy().  Upon
  successful completion, the hsearch_r() function returns 0 (zero).  Upon
  failure, it returns -1 and sets errno.

  [Tru64 UNIX]	Threads can share hash tables by using the hcreate_r,
  hsearch_r, and hdestroy_r functions with a common hsearch_data value.	 To
  prevent corruption of data when sharing a hash table, locks must be used
  around calls that use the common hsearch_data value.

RETURN VALUES
  The hsearch() function returns a null pointer when the action parameter is
  FIND and the key pointed to by item cannot be found or when the specified
  action is ENTER and the hash table is full.

  Upon successful completion, the hcreate() function returns a nonzero value.
  Otherwise, when sufficient space for the table cannot be allocated, the
  hcreate() function returns a value of 0 (zero).


ERRORS
  If any of the following conditions occur, the hsearch() function sets errno
  to the corresponding value:

  [ENOMEM]  The table is full.

  [ESRCH]   [Tru64 UNIX]  The search failed.

RELATED INFORMATION
  Functions: bsearch(3), lsearch(3), tsearch(3), qsort(3)

  Standards: standards(5)

Index for Section 3

Alphabetical listing for H

Top of page