Libc-262.tar.gz

[apple/libc.git] / stdlib / hcreate.3

diff --git a/stdlib/hcreate.3 b/stdlib/hcreate.3
new file mode 100644 (file)
index 0000000..1619c98
--- /dev/null
+++ b/stdlib/hcreate.3
@@ -0,0 +1,206 @@
+.\" $FreeBSD: src/lib/libc/stdlib/hcreate.3,v 1.2 2001/07/09 15:54:36 ru Exp $
+.\"
+.Dd May 8, 2001
+.Os
+.Dt HCREATE 3
+.Sh NAME
+.Nm hcreate , hdestroy , hsearch
+.Nd manage hash search table
+.Sh LIBRARY
+.Lb libc
+.Sh SYNOPSIS
+.In search.h
+.Ft int
+.Fn hcreate "size_t nel"
+.Ft void
+.Fn hdestroy void
+.Ft ENTRY *
+.Fn hsearch "ENTRY item" "ACTION action"
+.Sh DESCRIPTION
+The
+.Fn hcreate ,
+.Fn hdestroy ,
+and
+.Fn hsearch
+functions manage hash search tables.
+.Pp
+The
+.Fn hcreate
+function allocates sufficient space for the table, and the application should
+ensure it is called before
+.Fn hsearch
+is used.
+The
+.Fa nel
+argument is an estimate of the maximum
+number of entries that the table should contain.
+This number may be adjusted upward by the
+algorithm in order to obtain certain mathematically favorable circumstances.
+.Pp
+The
+.Fn hdestroy
+function disposes of the search table, and may be followed by another call to
+.Fn hcreate .
+After the call to
+.Fn hdestroy ,
+the data can no longer be considered accessible.
+.Pp
+The
+.Fn hsearch
+function is a hash-table search routine.
+It returns a pointer into a hash table
+indicating the location at which an entry can be found.
+The
+.Fa item
+argument is a structure of type
+.Vt ENTRY
+(defined in the
+.Aq Pa search.h
+header) containing two pointers:
+.Fa item.key
+points to the comparison key (a
+.Vt "char *" ) ,
+and
+.Fa item.data
+(a
+.Vt "void *" )
+points to any other data to be associated with
+that key.
+The comparison function used by
+.Fn hsearch
+is
+.Xr strcmp 3 .
+The
+.Fa action
+argument is a
+member of an enumeration type
+.Vt ACTION
+indicating the disposition of the entry if it cannot be
+found in the table.
+.Dv ENTER
+indicates that the
+.Fa item
+should be inserted in the table at an
+appropriate point.
+.Dv FIND
+indicates that no entry should be made.
+Unsuccessful resolution is
+indicated by the return of a
+.Dv NULL
+pointer.
+.Sh RETURN VALUES
+The
+.Fn hcreate
+function returns 0 if it cannot allocate sufficient space for the table;
+otherwise, it returns non-zero.
+.Pp
+The
+.Fn hdestroy
+function does not return a value.
+.Pp
+The
+.Fn hsearch
+function returns a
+.Dv NULL
+pointer if either the
+.Fa action
+is
+.Dv FIND
+and the
+.Fa item
+could not be found or the
+.Fa action
+is
+.Dv ENTER
+and the table is full.
+.Sh ERRORS
+The
+.Fn hcreate
+and
+.Fn hsearch
+functions may fail if:
+.Bl -tag -width Er
+.It Bq Er ENOMEM
+Insufficient storage space is available.
+.El
+.Sh EXAMPLES
+The following example reads in strings followed by two numbers
+and stores them in a hash table, discarding duplicates.
+It then reads in strings and finds the matching entry in the hash
+table and prints it out.
+.Bd -literal
+#include <stdio.h>
+#include <search.h>
+#include <string.h>
+
+struct info {                  /* This is the info stored in the table */
+       int age, room;          /* other than the key. */
+};
+
+#define NUM_EMPL       5000    /* # of elements in search table. */
+
+int
+main(void)
+{
+       char string_space[NUM_EMPL*20]; /* Space to store strings. */
+       struct info info_space[NUM_EMPL]; /* Space to store employee info. */
+       char *str_ptr = string_space; /* Next space in string_space. */
+       struct info *info_ptr = info_space; /* Next space in info_space. */
+       ENTRY item;
+       ENTRY *found_item; /* Name to look for in table. */
+       char name_to_find[30];
+       int i = 0;
+
+       /* Create table; no error checking is performed. */
+       (void) hcreate(NUM_EMPL);
+
+       while (scanf("%s%d%d", str_ptr, &info_ptr->age,
+           &info_ptr->room) != EOF && i++ < NUM_EMPL) {
+               /* Put information in structure, and structure in item. */
+               item.key = str_ptr;
+               item.data = info_ptr;
+               str_ptr += strlen(str_ptr) + 1;
+               info_ptr++;
+               /* Put item into table. */
+               (void) hsearch(item, ENTER);
+       }
+
+       /* Access table. */
+       item.key = name_to_find;
+       while (scanf("%s", item.key) != EOF) {
+               if ((found_item = hsearch(item, FIND)) != NULL) {
+                       /* If item is in the table. */
+                       (void)printf("found %s, age = %d, room = %d\en",
+                           found_item->key,
+                           ((struct info *)found_item->data)->age,
+                           ((struct info *)found_item->data)->room);
+               } else
+                       (void)printf("no such employee %s\en", name_to_find);
+       }
+       return 0;
+}
+.Ed
+.Sh SEE ALSO
+.Xr bsearch 3 ,
+.Xr lsearch 3 ,
+.Xr malloc 3 ,
+.Xr strcmp 3 ,
+.Xr tsearch 3
+.Sh STANDARDS
+The
+.Fn hcreate ,
+.Fn hdestroy ,
+and
+.Fn hsearch
+functions conform to
+.St -xpg4.2 .
+.Sh HISTORY
+The
+.Fn hcreate ,
+.Fn hdestroy ,
+and
+.Fn hsearch
+functions first appeared in
+.At V .
+.Sh BUGS
+The interface permits the use of only one hash table at a time.