_searchenv_s、_wsearchenv_s_searchenv_s, _wsearchenv_s

環境のパスを使用してファイルを検索します。Searches for a file by using environment paths. これらの _searchenv および _wsearchenv のバージョンは、「Security Features in the CRT」(CRT のセキュリティ機能) で説明されているように、セキュリティが強化されています。These versions of _searchenv, _wsearchenv have security enhancements, as described in Security Features in the CRT.

重要

この API は、Windows ランタイムで実行するアプリケーションでは使用できません。This API cannot be used in applications that execute in the Windows Runtime. 詳細については、「ユニバーサル Windows プラットフォーム アプリでサポートされていない CRT 関数」を参照してください。For more information, see CRT functions not supported in Universal Windows Platform apps.

構文Syntax

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

パラメーターParameters

ファイル名filename
検索するファイルの名前。Name of the file to search for.

varnamevarname
検索する環境。Environment to search.

pathnamepathname
完全パスを格納するバッファー。Buffer to store the complete path.

numberOfElementsnumberOfElements
サイズ、 pathnameバッファー。Size of the pathname buffer.

戻り値Return Value

正常終了した場合は 0 を返します。失敗した場合はエラー コードを返します。Zero if successful; an error code on failure.

場合filename空の文字列には、戻り値はENOENTします。If filename is an empty string, the return value is ENOENT.

エラー条件Error Conditions

ファイル名filename varnamevarname pathnamepathname numberOfElementsnumberOfElements 戻り値Return value 内容パス名Contents of pathname
任意any 任意any NULLNULL 任意any EINVALEINVAL 適用なしn/a
NULLNULL 任意any 任意any 任意any EINVALEINVAL 変更されないnot changed
任意any 任意any 任意any <= 0<= 0 EINVALEINVAL 変更されないnot changed

上記のいずれかのエラー条件が発生すると、「パラメーターの検証」で説明されているように無効なパラメーター ハンドラ―が呼び出されます。If any of these error conditions occurs, the invalid parameter handler is invoked, as described in Parameter Validation. 実行の継続が許可された場合に、これらの関数が設定errnoEINVAL戻ってEINVALします。If execution is allowed to continue, these functions set errno to EINVAL and return EINVAL.

RemarksRemarks

_Searchenv_s日常的な指定したドメインでターゲット ファイルを検索します。The _searchenv_s routine searches for the target file in the specified domain. Varname変数が指定できる任意の環境またはユーザー定義の変数などのディレクトリのパスの一覧を示すパスLIB、およびインクルード.The varname variable can be any environment or user-defined variable that specifies a list of directory paths, such as PATH, LIB, and INCLUDE. _Searchenv_sと小文字は区別varname環境変数の大文字と小文字が一致する必要があります。Because _searchenv_s is case-sensitive, varname should match the case of the environment variable. 場合varnameプロセスの環境で定義されている環境変数の名前と一致しません、関数は 0 を返します、 pathname変数は変更されません。If varname does not match the name of an environment variable defined in the process's environment, the function returns zero and the pathname variable is unchanged.

このルーチンは最初に現在の作業ディレクトリでファイルを検索します。The routine searches first for the file in the current working directory. ファイルが見つからなかった場合、環境変数で指定されている次のディレクトリを検索します。If it does not find the file, it looks next through the directories specified by the environment variable. 新しく作成されたパスをコピーする場合は、対象のファイルは、これらのディレクトリのいずれかでは、 pathnameします。If the target file is in one of those directories, the newly created path is copied into pathname. 場合、 filenameファイルが見つからないpathname null で終わる空の文字列が含まれています。If the filename file is not found, pathname contains an empty null-terminated string.

Pathnameバッファーは以上である必要があります _MAX_PATH作成されるパス名の長さを格納します。The pathname buffer should be at least _MAX_PATH characters long to accommodate the full length of the constructed path name. それ以外の場合、 _searchenv_sオーバーランの可能性があります、 pathname予期しない動作のバッファー。Otherwise, _searchenv_s might overrun the pathname buffer resulting in unexpected behavior.

_wsearchenv_sのワイド文字バージョンは、 _searchenv_s; 引数 _wsearchenv_sはワイド文字列です。_wsearchenv_s is a wide-character version of _searchenv_s; the arguments to _wsearchenv_s are wide-character strings. _wsearchenv_s_searchenv_s動作は同じです。_wsearchenv_s and _searchenv_s behave identically otherwise.

C++ では、これらの関数の使用はテンプレートのオーバーロードによって簡素化されます。オーバーロードでは、バッファー長を自動的に推論できる (サイズの引数を指定する必要がなくなる) だけでなく、古くてセキュリティが万全ではない関数を新しく安全な関数に自動的に置き換えることができます。In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. 詳細については、「 Secure Template Overloads」を参照してください。For more information, see Secure Template Overloads.

汎用テキスト ルーチンのマップGeneric-Text Routine Mappings

Tchar.h のルーチンTchar.h routine _UNICODE および _MBCS が未定義の場合_UNICODE and _MBCS not defined _MBCS が定義されている場合_MBCS defined _UNICODE が定義されている場合_UNICODE defined
_tsearchenv_s_tsearchenv_s _searchenv_s_searchenv_s _searchenv_s_searchenv_s _wsearchenv_s_wsearchenv_s

必要条件Requirements

ルーチンによって返される値Routine 必須ヘッダーRequired header
_searchenv_s_searchenv_s <stdlib.h><stdlib.h>
_wsearchenv_s_wsearchenv_s <stdlib.h> または <wchar.h><stdlib.h> or <wchar.h>

互換性の詳細については、「 互換性」を参照してください。For more compatibility information, see Compatibility.

Example

// 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 2010\VC\BIN\CL.EXE

関連項目See also

ディレクトリ制御Directory Control
_searchenv、_wsearchenv_searchenv, _wsearchenv
getenv、 _wgetenvgetenv, _wgetenv
_putenv、_wputenv_putenv, _wputenv