_lsearch_s

项目
06/09/2015

Performs a linear search for a value. A version of _lsearch with security enhancements as described in 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 参数验证. If execution is allowed to continue, then errno is set to EINVAL and the function returns NULL. 有关更多信息，请参见 errno、_doserrno、_sys_errlist 和 _sys_nerr。

错误情况

key	base	compare	num	size	errno
NULL	any	any	any	any	EINVAL
any	NULL	any	!= 0	any	EINVAL
any	any	any	any	零	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.