summaryrefslogtreecommitdiffstats
path: root/man3/hsearch.3
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--man3/hsearch.345
1 files changed, 22 insertions, 23 deletions
diff --git a/man3/hsearch.3 b/man3/hsearch.3
index dd801df..93e6794 100644
--- a/man3/hsearch.3
+++ b/man3/hsearch.3
@@ -14,7 +14,7 @@
.\" 2008-09-03, mtk, restructured somewhat, in part after suggestions from
.\" Timothy S. Nelson <wayland@wayland.id.au>
.\"
-.TH hsearch 3 2023-07-20 "Linux man-pages 6.05.01"
+.TH hsearch 3 2023-10-31 "Linux man-pages 6.7"
.SH NAME
hcreate, hdestroy, hsearch, hcreate_r, hdestroy_r,
hsearch_r \- hash table management
@@ -24,18 +24,18 @@ Standard C library
.SH SYNOPSIS
.nf
.B #include <search.h>
-.PP
+.P
.BI "int hcreate(size_t " nel );
.B "void hdestroy(void);"
-.PP
+.P
.BI "ENTRY *hsearch(ENTRY " item ", ACTION " action );
-.PP
+.P
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
.B #include <search.h>
-.PP
+.P
.BI "int hcreate_r(size_t " nel ", struct hsearch_data *" htab );
.BI "void hdestroy_r(struct hsearch_data *" htab );
-.PP
+.P
.BI "int hsearch_r(ENTRY " item ", ACTION " action ", ENTRY **" retval ,
.BI " struct hsearch_data *" htab );
.fi
@@ -48,7 +48,7 @@ and
allow the caller to create and manage a hash search table
containing entries consisting of a key (a string) and associated data.
Using these functions, only one hash table can be used at a time.
-.PP
+.P
The three functions
.BR hcreate_r (),
.BR hsearch_r (),
@@ -62,7 +62,7 @@ on which the function is to operate.
The programmer should treat this structure as opaque
(i.e., do not attempt to directly access or modify
the fields in this structure).
-.PP
+.P
First a hash table must be created using
.BR hcreate ().
The argument \fInel\fP specifies the maximum number of entries
@@ -71,7 +71,7 @@ in the table.
The implementation may adjust this value upward to improve the
performance of the resulting hash table.
.\" e.g., in glibc it is raised to the next higher prime number
-.PP
+.P
The
.BR hcreate_r ()
function performs the same task as
@@ -82,7 +82,7 @@ The structure pointed to by
.I htab
must be zeroed before the first call to
.BR hcreate_r ().
-.PP
+.P
The function
.BR hdestroy ()
frees the memory occupied by the hash table that was created by
@@ -97,17 +97,17 @@ function performs the analogous task for a hash table described by
.IR *htab ,
which was previously created using
.BR hcreate_r ().
-.PP
+.P
The
.BR hsearch ()
function 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.
-.PP
+.P
The argument \fIitem\fP is of type \fIENTRY\fP, which is defined in
\fI<search.h>\fP as follows:
-.PP
+.P
.in +4n
.EX
typedef struct entry {
@@ -116,11 +116,11 @@ typedef struct entry {
} ENTRY;
.EE
.in
-.PP
+.P
The field \fIkey\fP points to a null-terminated string which is the
search key.
The field \fIdata\fP points to data that is associated with that key.
-.PP
+.P
The argument \fIaction\fP determines what
.BR hsearch ()
does after an unsuccessful search.
@@ -139,7 +139,7 @@ is
then
.I data
is ignored.)
-.PP
+.P
The
.BR hsearch_r ()
function is like
@@ -161,7 +161,7 @@ return nonzero on success.
They return 0 on error, with
.I errno
set to indicate the error.
-.PP
+.P
On success,
.BR hsearch ()
returns a pointer to an entry in the hash table.
@@ -184,7 +184,7 @@ can fail for the following reasons:
.B EINVAL
.I htab
is NULL.
-.PP
+.P
.BR hsearch ()
and
.BR hsearch_r ()
@@ -205,7 +205,7 @@ was
and
.I key
was not found in the table.
-.PP
+.P
POSIX.1 specifies only the
.\" PROX.1-2001, POSIX.1-2008
.B ENOMEM
@@ -233,7 +233,6 @@ T{
.BR hdestroy_r ()
T} Thread safety MT-Safe race:htab
.TE
-.sp 1
.SH STANDARDS
.TP
.BR hcreate ()
@@ -271,7 +270,7 @@ Typically, this means that
.I nel
should be at least 25% larger than the maximum number of elements
that the caller expects to store in the table.
-.PP
+.P
The
.BR hdestroy ()
and
@@ -296,12 +295,12 @@ should not do anything for a successful search.
In libc and glibc (before glibc 2.3), the
implementation violates the specification,
updating the \fIdata\fP for the given \fIkey\fP in this case.
-.PP
+.P
Individual hash table entries can be added, but not deleted.
.SH EXAMPLES
The following program inserts 24 items into a hash table, then prints
some of them.
-.PP
+.P
.\" SRC BEGIN (hsearch.c)
.EX
#include <search.h>