diff options
Diffstat (limited to '')
| -rw-r--r-- | man3/hsearch.3 | 45 |
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> |