diff options
Diffstat (limited to 'upstream/archlinux/man3p/hcreate.3p')
| -rw-r--r-- | upstream/archlinux/man3p/hcreate.3p | 213 |
1 files changed, 213 insertions, 0 deletions
diff --git a/upstream/archlinux/man3p/hcreate.3p b/upstream/archlinux/man3p/hcreate.3p new file mode 100644 index 00000000..8e41d25d --- /dev/null +++ b/upstream/archlinux/man3p/hcreate.3p @@ -0,0 +1,213 @@ +'\" 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 . |