_lsearch_s

Статья
10/16/2008

Performs a linear search for a value. A version of _lsearch with security enhancements as described in Security Enhancements in the CRT.

void *_lsearch_s(
   const void *key,
   void *base,
   unsigned int *num,
   size_t size,
   int (__cdecl *compare)(void *, const void *, const void *),
   void * context
);

Параметры

key
Object to search for.
base
Pointer to the base of array to be searched.
num
Number of elements.
size
Size of each array element in bytes.
compare
Pointer to the comparison routine. The second parameter is a pointer to the key for search. The third parameter is a pointer to an array element to be compared with the key.
context
A pointer to an object that might be accessed in the comparison function.

Возвращаемое значение

If key is found, _lsearch_s returns a pointer to the element of the array at base that matches key. If key is not found, _lsearch_s returns a pointer to the newly added item at the end of the array.

If invalid parameters are passed to the function, the invalid parameter handler is invoked, as described in Parameter Validation. If execution is allowed to continue, then errno is set to EINVAL and the function returns NULL. For more information, see errno, _doserrno, _sys_errlist, and _sys_nerr.

Error Conditions

key	base	compare	num	size	errno
NULL	any	any	any	any	EINVAL
any	NULL	any	!= 0	any	EINVAL
any	any	any	any	zero	EINVAL
any	any	NULL	an	any	EINVAL

Заметки

The _lsearch_s function performs a linear search for the value key in an array of num elements, each of width bytes. Unlike bsearch_s, _lsearch_s does not require the array to be sorted. If key is not found, then _lsearch_s adds it to the end of the array and increments num.

The compare function is a pointer to a user-supplied routine that compares two array elements and returns a value specifying their relationship. The compare function also takes the pointer to the context as the first argument. _lsearch_s calls compare one or more times during the search, passing pointers to two array elements on each call. compare must compare the elements and then return either nonzero (meaning the elements are different) or 0 (meaning the elements are identical).

The context pointer can be useful if the searched data structure is part of an object and the compare function needs to access members of the object. For example, code in the compare function can cast the void pointer into the appropriate object type and access members of that object. The addition of the context pointer makes _lsearch_s more secure because additional context can be used to avoid reentrancy bugs associated with using static variables to make data available to the compare function.