_searchenv_s、_wsearchenv_s
更新 : 2007 年 11 月
環境変数で定義されたパスを使用してファイルを検索します。これらの関数は、「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 |
n/a |
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 のバッファ オーバーランが発生し、予測できない動作が発生することがあります。
ワイド文字を扱う場合は、_searchenv_s ではなく _wsearchenv_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 );
}
Path for CL.EXE:
C:\Program Files\Microsoft Visual Studio 2005\VC7\BIN\CL.EXE
.NET Framework の相当するアイテム
適用できません。標準 C 関数を呼び出すには、PInvoke を使用します。詳細については、「プラットフォーム呼び出しの例」を参照してください。