_searchenv_s、_wsearchenv_s

[アーティクル]
08/09/2011

環境変数で定義されたパスを使用してファイルを検索します。これらの関数は、「CRT のセキュリティ機能」に説明されているように、_searchenv、_wsearchenv のセキュリティが強化されたバージョンです。

errno_t _searchenv_s(
   const char *filename,
   const char *varname,
   char *pathname,
   size_t numberOfElements
);
errno_t _wsearchenv_s(
   const wchar_t *filename,
   const wchar_t *varname,
   wchar_t *pathname,
   size_t numberOfElements
);
template <size_t size>
errno_t _searchenv_s(
   const char *filename,
   const char *varname,
   char (&pathname)[size]
); // C++ only
template <size_t size>
errno_t _wsearchenv_s(
   const wchar_t *filename,
   const wchar_t *varname,
   wchar_t (&pathname)[size]
); // C++ only

パラメーター

[入力] filename
検索するファイルの名前。
[入力] varname
検索する環境。
[出力] pathname
絶対パスを格納するバッファー。
[入力] numberOfElements
pathname バッファーのサイズ。

戻り値

正常終了した場合は 0 を返します。失敗した場合はエラーコードを返します。

filename が空の文字列の場合、戻り値は ENOENT になります。

エラー条件

filename	varname	pathname	numberOfElements	戻り値	pathname の内容
any	any	NULL	any	EINVAL	適用なし
NULL	any	any	any	EINVAL	変更されない
any	any	any	0 以下	EINVAL	変更されない

上記のいずれかのエラー条件が発生すると、「パラメーターの検証」に説明されているように、無効なパラメーターハンドラーが呼び出されます。実行の継続が許可された場合、これらの関数は errno を EINVAL に設定し、EINVAL を返します。

解説

_searchenv_s ルーチンは、対象のファイルを指定されたドメイン内で検索します。 varname 変数には、PATH、LIB、INCLUDE など、ディレクトリパスの一覧を指定する環境変数またはユーザー定義の変数を指定できます。 _searchenv_s は大文字と小文字を区別するため、varname と環境変数の大文字と小文字を一致させる必要があります。 varname がプロセスの環境で定義されている環境変数と一致しない場合、この関数は 0 を返し、 pathname 変数は変更されません。

このルーチンは、最初に現在の作業ディレクトリ内でファイルを検索します。目的のファイルが見つからないと、環境変数で指定されたディレクトリを検索します。対象のファイルが環境変数で指定されたディレクトリで見つかった場合、新しく作成したパスを pathname が示すバッファーにコピーします。 filename に指定したファイルが見つからない場合、pathname が示すバッファーに、null で終わる空の文字列が格納されます。

見つかったパス名全体を格納するには、pathname のバッファー長を _MAX_PATH の文字数以上に設定する必要があります。領域が足りないと、_searchenv_s では、pathname のバッファーオーバーランが発生し、予測できない動作が発生することがあります。

_wsearchenv_s は _searchenv_s のワイド文字バージョンであり、_wsearchenv_s の引数はワイド文字列です。それ以外では、_wsearchenv_s と _searchenv_s の動作は同じです。

C++ では、これらの関数の使用はテンプレートのオーバーロードによって簡素化されます。オーバーロードでは、バッファー長を自動的に推論できる (サイズの引数を指定する必要がなくなる) だけでなく、古くてセキュリティが万全ではない関数を新しく安全な関数に自動的に置き換えることができます。詳細については、「セキュリティ保護されたテンプレートオーバーロード」を参照してください。

汎用テキストルーチンのマップ

Tchar.h のルーチン	_UNICODE および _MBCS が未定義の場合	_MBCS が定義されている場合	_UNICODE が定義されている場合
_tsearchenv_s	_searchenv_s	_searchenv_s	_wsearchenv_s

必要条件

ルーチン	必須ヘッダー
_searchenv_s	<stdlib.h>
_wsearchenv_s	<stdlib.h> または <wchar.h>

互換性の詳細については、「C ランタイムライブラリ」の「互換性」を参照してください。

使用例

// crt_searchenv_s.c
/* This program searches for a file in
 * a directory specified by an environment variable.
 */

#include <stdlib.h>
#include <stdio.h>

int main( void )
{
   char pathbuffer[_MAX_PATH];
   char searchfile[] = "CL.EXE";
   char envvar[] = "PATH";
   errno_t err;

   /* Search for file in PATH environment variable: */
   err = _searchenv_s( searchfile, envvar, pathbuffer, _MAX_PATH );
   if (err != 0)
   {
      printf("Error searching the path. Error code: %d\n", err);
   }
   if( *pathbuffer != '\0' )
      printf( "Path for %s:\n%s\n", searchfile, pathbuffer );
   else
      printf( "%s not found\n", searchfile );
}