_lsearch_s

[アーティクル]
09/17/2008

更新 : 2007 年 11 月

値のリニアサーチを実行します。この関数は、「CRT のセキュリティ強化」に説明されているように、_lsearch のセキュリティが強化されたバージョンです。

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
検索するオブジェクト。
base
検索する配列のベースへのポインタ。
num
要素の数。
size
各配列要素のサイズ (バイト単位)。
compare
比較ルーチンへのポインタ。2 番目のパラメータは、検索用のキーへのポインタです。3 番目のパラメータは、キーと比較される配列要素へのポインタです。
context
比較関数の中でアクセスされる可能性のあるオブジェクトへのポインタ。

戻り値

key が見つかった場合、_lsearch_s は、key に一致する base の指す配列要素へのポインタを返します。key が見つからなかった場合、_lsearch_s は、配列の末尾に新しく追加された項目へのポインタを返します。

この関数に無効なパラメータが渡されると、「パラメータの検証」に説明されているように、無効なパラメータハンドラが呼び出されます。実行の継続が許可された場合、errno が EINVAL に設定され、関数から 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	0	EINVAL
any	any	NULL	an	any	EINVAL

解説

_lsearch_s 関数は、width のバイト数ごとに、num 要素の配列で key 値のリニアサーチを実行します。bsearch_s とは異なり、_lsearch_s では、配列を並べ替える必要がありません。key が見つからなかった場合、_lsearch_s 関数は、その key を配列の末尾に追加し、num をインクリメントします。

compare 関数はユーザーが指定したルーチンへのポインタです。このルーチンは、2 つの配列要素を比較し、その関係を示す値を返します。また、compare 関数は最初の引数として、コンテキストへのポインタ使用します。_lsearch_s 関数は、検索中に compare を 1 回または複数回呼び出し、そのたびに 2 つの配列要素へのポインタを渡します。compare では必ず要素を比較し、0 以外の値 (2 つの要素が異なることを示す) または 0 (2 つの要素が同一であることを示す) のいずれかを返します。

context ポインタは、検索対象のデータ構造体がオブジェクトの一部であり、compare 関数がそのオブジェクトのメンバにアクセスする必要がある場合に役立ちます。たとえば、compare 関数のコードが void ポインタを適切なオブジェクト型にキャストして、そのオブジェクトのメンバにアクセスできます。context ポインタの追加により、_lsearch_s 関数のセキュリティが強化されます。これは、追加のコンテキストを使用することで、compare 関数に対してデータを利用可能にする静的変数の使用に関連したバグの再入を回避できるためです。