_searchenv、_wsearchenv

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

更新 : 2007 年 11 月

環境変数で定義されたパスを使用してファイルを検索します。これらの関数のセキュリティを強化したバージョンについては、「_searchenv_s、_wsearchenv_s」を参照してください。

void _searchenv(
   const char *filename,
   const char *varname,
   char *pathname 
);
void _wsearchenv(
   const wchar_t *filename,
   const wchar_t *varname,
   wchar_t *pathname 
);
template <size_t size>
void _searchenv(
   const char *filename,
   const char *varname,
   char (&pathname)[size]
); // C++ only
template <size_t size>
void _wsearchenv(
   const wchar_t *filename,
   const wchar_t *varname,
   wchar_t (&pathname)[size]
); // C++ only

パラメータ

filename
検索するファイルの名前。
varname
検索する環境。
pathname
絶対パスを格納するバッファ。

解説

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

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

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

ワイド文字を扱う場合は、_searchenv ではなく _wsearchenv を使用します。_wsearchenv の場合、引数にはワイド文字列を指定します。引数の指定以外では、_wsearchenv と _searchenv の動作は同じです。

filename が空の文字列の場合、これらの関数は ENOENT を返します。

filename が NULL ポインタの場合、「パラメータの検証」に説明されているように、無効なパラメータハンドラが呼び出されます。実行の継続が許可された場合、これらの関数は -1 を返し、errno を EINVAL に設定します。

errno とエラーコードの詳細については、「errno 定数」を参照してください。

C++ では、これらの関数にテンプレートのオーバーロードがあります。このオーバーロードは、これらの関数に対応するセキュリティで保護された新しい関数を呼び出します。詳細については、「セキュリティ保護されたテンプレートオーバーロード」を参照してください。

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

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

必要条件

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

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

使用例

// crt_searchenv.c
// compile with: /W3
// 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";

   // Search for file in PATH environment variable:
   _searchenv( searchfile, envvar, pathbuffer ); // C4996
   // Note: _searchenv is deprecated; consider using _searchenv_s
   if( *pathbuffer != '\0' )
      printf( "Path for %s:\n%s\n", searchfile, pathbuffer );
   else
      printf( "%s not found\n", searchfile );
}

Path for CL.EXE:
C:\Program Files\Microsoft Visual Studio 8\VC\BIN\CL.EXE