mirror of https://github.com/mkerrisk/man-pages
142 lines
4.1 KiB
Plaintext
142 lines
4.1 KiB
Plaintext
|
.\" 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 .
|