hcreate.3p (5922B)
- '\" et
- .TH HCREATE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- hcreate,
- hdestroy,
- hsearch
- \(em manage hash search table
- .SH SYNOPSIS
- .LP
- .nf
- #include <search.h>
- .P
- int hcreate(size_t \fInel\fP);
- void hdestroy(void);
- ENTRY *hsearch(ENTRY \fIitem\fP, ACTION \fIaction\fP);
- .fi
- .SH DESCRIPTION
- The
- \fIhcreate\fR(),
- \fIhdestroy\fR(),
- and
- \fIhsearch\fR()
- functions shall manage hash search tables.
- .P
- The
- \fIhcreate\fR()
- function shall allocate sufficient space for the table, and the
- application shall ensure it is called before
- \fIhsearch\fR()
- is used. The
- .IR nel
- argument is an estimate of the maximum number of entries that the table
- shall contain. This number may be adjusted upward by the algorithm in
- order to obtain certain mathematically favorable circumstances.
- .P
- The
- \fIhdestroy\fR()
- function shall dispose of the search table, and may be followed by
- another call to
- \fIhcreate\fR().
- After the call to
- \fIhdestroy\fR(),
- the data can no longer be considered accessible.
- .P
- The
- \fIhsearch\fR()
- function is a hash-table search routine. It shall return a pointer into a
- hash table indicating the location at which an entry can be found. The
- .IR item
- argument is a structure of type
- .BR ENTRY
- (defined in the
- .IR <search.h>
- header) containing two pointers:
- .IR item.key
- points to the comparison key (a
- .BR "char *" ),
- and
- .IR item.data
- (a
- .BR "void *" )
- points to any other data to be associated with that key. The
- comparison function used by
- \fIhsearch\fR()
- is
- \fIstrcmp\fR().
- The
- .IR action
- argument is a member of an enumeration type
- .BR ACTION
- indicating the disposition of the entry if it cannot be found in the
- table. ENTER indicates that the item should be inserted in the table
- at an appropriate point. FIND indicates that no entry should be made.
- Unsuccessful resolution is indicated by the return of a null pointer.
- .P
- These functions need not be thread-safe.
- .SH "RETURN VALUE"
- The
- \fIhcreate\fR()
- function shall return 0 if it cannot allocate sufficient space for the
- table; otherwise, it shall return non-zero.
- .P
- The
- \fIhdestroy\fR()
- function shall not return a value.
- .P
- The
- \fIhsearch\fR()
- function shall return a null pointer if either the action is FIND and
- the item could not be found or the action is ENTER and the table is
- full.
- .SH ERRORS
- The
- \fIhcreate\fR()
- and
- \fIhsearch\fR()
- functions may fail if:
- .TP
- .BR ENOMEM
- Insufficient storage space is available.
- .LP
- .IR "The following sections are informative."
- .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.
- .sp
- .RS 4
- .nf
- #include <stdio.h>
- #include <search.h>
- #include <string.h>
- .P
- struct info { /* This is the info stored in the table */
- int age, room; /* other than the key. */
- };
- .P
- #define NUM_EMPL 5000 /* # of elements in search table. */
- .P
- 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];
- .P
- int i = 0;
- .P
- /* 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) {
- .P
- /* Put information in structure, and structure in item. */
- item.key = str_ptr;
- item.data = info_ptr;
- str_ptr += strlen(str_ptr) + 1;
- info_ptr++;
- .P
- /* Put item into table. */
- (void) hsearch(item, ENTER);
- }
- .P
- /* Access table. */
- item.key = name_to_find;
- while (scanf("%s", item.key) != EOF) {
- if ((found_item = hsearch(item, FIND)) != NULL) {
- .P
- /* 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;
- }
- .fi
- .P
- .RE
- .SH "APPLICATION USAGE"
- The
- \fIhcreate\fR()
- and
- \fIhsearch\fR()
- functions may use
- \fImalloc\fR()
- to allocate space.
- .SH RATIONALE
- None.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "\fIbsearch\fR\^(\|)",
- .IR "\fIlsearch\fR\^(\|)",
- .IR "\fImalloc\fR\^(\|)",
- .IR "\fIstrcmp\fR\^(\|)",
- .IR "\fItdelete\fR\^(\|)"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "\fB<search.h>\fP"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 by the Institute of
- Electrical and Electronics Engineers, Inc and The Open Group.
- In the event of any discrepancy between this version and the original IEEE and
- The Open Group Standard, the original IEEE and The Open Group Standard
- is the referee document. The original Standard can be obtained online at
- http://www.opengroup.org/unix/online.html .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .