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

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

LIBRARY
  Standard C Library (libc)

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.

  tableptr
      Points at the hash table. This table is kept in the thread's address
      space.

  lengthptr
      Points at the size of the hash table.

  mptr
      Points at the log base 2 version of the hash table length.

  countptr
      Points at the number of entries in the hash table.

  length
      Specifies the length of the hash table.

  m   Specifies the log base 2 version of the hash table length.

  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.

SEE ALSO
  Functions: bsearch(3), lsearch(3), tsearch(3), qsort(3)

  Standards: standards(5)

Index for Section 3

Alphabetical listing for H

Top of page