diff options
Diffstat (limited to 'man3p/lsearch.3p')
| -rw-r--r-- | man3p/lsearch.3p | 141 |
1 files changed, 141 insertions, 0 deletions
diff --git a/man3p/lsearch.3p b/man3p/lsearch.3p new file mode 100644 index 000000000..223edd09b --- /dev/null +++ b/man3p/lsearch.3p @@ -0,0 +1,141 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "LSEARCH" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" lsearch +.SH NAME +lsearch, lfind \- linear search and update +.SH SYNOPSIS +.LP +\fB#include <search.h> +.br +.sp +void *lsearch(const void *\fP\fIkey\fP\fB, void *\fP\fIbase\fP\fB, +size_t *\fP\fInelp\fP\fB, size_t\fP +\fIwidth\fP\fB, +.br +\ \ \ \ \ \ int (*\fP\fIcompar\fP\fB)(const void *, const void *)); +.br +void *lfind(const void *\fP\fIkey\fP\fB, const void *\fP\fIbase\fP\fB, +size_t *\fP\fInelp\fP\fB, +.br +\ \ \ \ \ \ size_t width, int (*\fP\fIcompar\fP\fB)(const void *, +const void *)); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIlsearch\fP() function shall linearly search the table and return +a pointer into the table for the matching entry. If the +entry does not occur, it shall be added at the end of the table. The +\fIkey\fP argument points to the entry to be sought in the +table. The \fIbase\fP argument points to the first element in the +table. The \fIwidth\fP argument is the size of an element in +bytes. The \fInelp\fP argument points to an integer containing the +current number of elements in the table. The integer to which +\fInelp\fP points shall be incremented if the entry is added to the +table. The \fIcompar\fP argument points to a comparison +function which the application shall supply (for example, \fIstrcmp\fP()). +It is called +with two arguments that point to the elements being compared. The +application shall ensure that the function returns 0 if the +elements are equal, and non-zero otherwise. +.LP +The \fIlfind\fP() function shall be equivalent to \fIlsearch\fP(), +except that if the entry is not found, it is not added to +the table. Instead, a null pointer is returned. +.SH RETURN VALUE +.LP +If the searched for entry is found, both \fIlsearch\fP() and \fIlfind\fP() +shall return a pointer to it. Otherwise, +\fIlfind\fP() shall return a null pointer and \fIlsearch\fP() shall +return a pointer to the newly added element. +.LP +Both functions shall return a null pointer in case of error. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Storing Strings in a Table +.LP +This fragment reads in less than or equal to TABSIZE strings of length +less than or equal to ELSIZE and stores them in a table, +eliminating duplicates. +.sp +.RS +.nf + +\fB#include <stdio.h> +#include <string.h> +#include <search.h> +.sp + +#define TABSIZE 50 +#define ELSIZE 120 +.sp + +\&... + char line[ELSIZE], tab[TABSIZE][ELSIZE]; + size_t nel = 0; + ... + while (fgets(line, ELSIZE, stdin) != NULL && nel < TABSIZE) + (void) lsearch(line, tab, &nel, + ELSIZE, (int (*)(const void *, const void *)) strcmp); + ... +\fP +.fi +.RE +.SS Finding a Matching Entry +.LP +The following example finds any line that reads \fB"This is a test."\fP +\&. +.sp +.RS +.nf + +\fB#include <search.h> +#include <string.h> +\&... +char line[ELSIZE], tab[TABSIZE][ELSIZE]; +size_t nel = 0; +char *findline; +void *entry; +.sp + +findline = "This is a test.\\n"; +.sp + +entry = lfind(findline, tab, &nel, ELSIZE, ( + int (*)(const void *, const void *)) strcmp); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +The comparison function need not compare every byte, so arbitrary +data may be contained in the elements in addition to the +values being compared. +.LP +Undefined results can occur if there is not enough room in the table +to add a new item. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIhcreate\fP() , \fItsearch\fP() , the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI<search.h>\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 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 . |