.SH NAME
hcreate, hdestroy, hsearch \- hash table management
.SH SYNOPSIS
+.nf
.B #include <search.h>
.sp
.BI "int hcreate(size_t " nel );
.BI "ENTRY *hsearch(ENTRY " item ", ACTION " action );
.sp
.B "void hdestroy(void);"
-.sp 2
+.sp
.B #define _GNU_SOURCE
.br
.B #include <search.h>
.sp
.BI "int hcreate_r(size_t " nel ", struct hsearch_data *" tab );
.sp
-.BI "int hsearch_r(ENTRY " item ", ACTION " action ,
-.BI "ENTRY **" ret ", struct hsearch_data *" tab );
+.BI "int hsearch_r(ENTRY " item ", ACTION " action ", ENTRY **" ret ,
+.BI " struct hsearch_data *" tab );
.sp
.BI "void hdestroy_r(struct hsearch_data *" tab );
+.fi
.SH DESCRIPTION
The three functions
.BR hcreate (),
allow the user to create a hash table (only one at a time)
which associates a key with any data.
.PP
-First the table must be created with the function \fBhcreate()\fP.
+First the table must be created with the function \fBhcreate\fP().
The argument \fInel\fP is an estimate of the maximum number of entries
in the table.
-The function \fBhcreate()\fP may adjust this value upward to improve the
+The function \fBhcreate\fP() may adjust this value upward to improve the
performance of the resulting hash table.
.PP
-The corresponding function \fBhdestroy()\fP frees the memory occupied by
+The corresponding function \fBhdestroy\fP() frees the memory occupied by
the hash table so that a new table can be constructed.
.PP
The argument \fIitem\fP is of type \fBENTRY\fP, which is a typedef defined in
\fI<search.h>\fP and includes these elements:
+.RS
.sp
.nf
- typedef struct entry {
- char *\fIkey\fP;
- void *\fIdata\fP;
- } ENTRY;
+typedef struct entry {
+ char *\fIkey\fP;
+ void *\fIdata\fP;
+} ENTRY;
+.RE
.fi
.sp
-The field \fIkey\fP points to the NUL-terminated string which is the
+The field \fIkey\fP points to the null-terminated string which is the
search key.
The field \fIdata\fP points to the data associated with that key.
-The function \fBhsearch()\fP searches the hash table for an
+The function \fBhsearch\fP() searches the hash table for an
item with the same key as \fIitem\fP (where "the same" is determined using
.BR strcmp (3)),
and if successful returns a pointer to it.
-The argument \fIaction\fP determines what \fBhsearch()\fP does
-after an unsuccessful search. A value of \fBENTER\fP instructs it to
+The argument \fIaction\fP determines what \fBhsearch\fP() does
+after an unsuccessful search.
+A value of \fBENTER\fP instructs it to
insert a copy of \fIitem\fP, while a value of \fBFIND\fP means to return
-\fBNULL\fP.
+NULL.
.PP
The three functions
.BR hcreate_r (),
.BR hsearch_r (),
.BR hdestroy_r ()
are reentrant versions that allow the use of more than one table.
-The last argument used identifies the table. The struct it points to
+The last argument used identifies the table.
+The struct it points to
must be zeroed before the first call to
-.BR hcreate_r() .
+.BR hcreate_r ().
.SH "RETURN VALUE"
-\fBhcreate()\fP and \fBhcreate_r()\fP return 0 when allocation of the memory
+\fBhcreate\fP() and \fBhcreate_r\fP() return 0 when allocation of the memory
for the hash table fails, non-zero otherwise.
.LP
-\fBhsearch()\fP returns \fBNULL\fP if \fIaction\fP is \fBENTER\fP and
+\fBhsearch\fP() returns NULL if \fIaction\fP is \fBENTER\fP and
the hash table is full, or \fIaction\fP is \fBFIND\fP and \fIitem\fP
cannot be found in the hash table.
.LP
-\fBhsearch_r()\fP returns 0 if \fIaction\fP is \fBENTER\fP and
+\fBhsearch_r\fP() returns 0 if \fIaction\fP is \fBENTER\fP and
the hash table is full, and non-zero otherwise.
.SH ERRORS
POSIX documents
.B ESRCH
The \fIaction\fP parameter is \fBFIND\fP and no corresponding element
is found in the table.
-.SH "CONFORMS TO"
+.SH "CONFORMING TO"
The functions
.BR hcreate (),
.BR hsearch (),
and
.BR hdestroy ()
-are from SVID, and are described in POSIX 1003.1-2001.
+are from SVr4, and are described in POSIX.1-2001.
The functions
.BR hcreate_r (),
.BR hsearch_r (),
.BR hdestroy_r ()
are GNU extensions.
.SH BUGS
-SVID and POSIX 1003.1-2001 specify that \fIaction\fP
+SVr4 and POSIX.1-2001 specify that \fIaction\fP
is significant only for unsuccessful searches, so that an ENTER
-should not do anything for a successful search. The libc and glibc
+should not do anything for a successful search.
+The libc and glibc
implementations update the \fIdata\fP for the given \fIkey\fP
in this case.
.\" Tue Jan 29 09:27:40 2002: fixed in latest glibc snapshot
some of them.
.nf
- #include <stdio.h>
- #include <stdlib.h>
- #include <search.h>
-
- char *data[] = { "alpha", "bravo", "charlie", "delta",
- "echo", "foxtrot", "golf", "hotel", "india", "juliet",
- "kilo", "lima", "mike", "november", "oscar", "papa",
- "quebec", "romeo", "sierra", "tango", "uniform",
- "victor", "whisky", "x-ray", "yankee", "zulu"
- };
+#include <stdio.h>
+#include <stdlib.h>
+#include <search.h>
+
+char *data[] = { "alpha", "bravo", "charlie", "delta",
+ "echo", "foxtrot", "golf", "hotel", "india", "juliet",
+ "kilo", "lima", "mike", "november", "oscar", "papa",
+ "quebec", "romeo", "sierra", "tango", "uniform",
+ "victor", "whisky", "x-ray", "yankee", "zulu"
+};
- int main() {
- ENTRY e, *ep;
- int i;
-
- /* starting with small table, and letting it grow does not work */
- hcreate(30);
- for (i = 0; i < 24; i++) {
- e.key = data[i];
- /* data is just an integer, instead of a
- pointer to something */
- e.data = (void *)i;
- ep = hsearch(e, ENTER);
- /* there should be no failures */
- if (ep == NULL) {
+int
+main(void)
+{
+ ENTRY e, *ep;
+ int i;
+
+ /* starting with small table, and letting it grow does not work */
+ hcreate(30);
+ for (i = 0; i < 24; i++) {
+ e.key = data[i];
+ /* data is just an integer, instead of a
+ pointer to something */
+ e.data = (void *)i;
+ ep = hsearch(e, ENTER);
+ /* there should be no failures */
+ if (ep == NULL) {
fprintf(stderr, "entry failed\\n");
exit(1);
- }
- }
- for (i = 22; i < 26; i++) {
- /* print two entries from the table, and
- show that two are not in the table */
- e.key = data[i];
- ep = hsearch(e, FIND);
- printf("%9.9s \-> %9.9s:%d\\n", e.key,
- ep ? ep\->key : "NULL",
- ep ? (int)(ep->data) : 0);
- }
- return 0;
+ }
}
-
+ for (i = 22; i < 26; i++) {
+ /* print two entries from the table, and
+ show that two are not in the table */
+ e.key = data[i];
+ ep = hsearch(e, FIND);
+ printf("%9.9s \-> %9.9s:%d\\n", e.key,
+ ep ? ep\->key : "NULL", ep ? (int)(ep->data) : 0);
+ }
+ return 0;
+}
.fi
.SH "SEE ALSO"
.BR bsearch (3),
.BR lsearch (3),
.BR malloc (3),
-.BR tsearch (3)
+.BR tsearch (3),
+.BR feature_test_macros (7)
projects / thirdparty / man-pages.git / blobdiff