_searchenv_s, _wsearchenv_s

使用環境路徑來搜尋檔案。 這些版本的 _searchenv具有_wsearchenv安全性增強功能，如CRT中的安全性功能中所述。

重要

這個 API 不能用於在 Windows 執行階段中執行的應用程式。 如需詳細資訊，請參閱 CRT functions not supported in Universal Windows Platform apps (通用 Windows 平台應用程式中不支援的 CRT 函式)。

語法

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緩衝區的大小。

傳回值

如果成功，就是零，如果失敗，則為錯誤碼。

如果 filename 是空字串，則傳回值是 ENOENT。

錯誤條件

filename	varname	pathname	numberOfElements	傳回值	pathname 的內容。
任意	任意	NULL	任意	EINVAL	n/a
NULL	任意	任意	任意	EINVAL	未變更
任意	任意	任意	<= 0	EINVAL	未變更

如果發生上述任何錯誤狀況，則會叫用無效的參數處理程式，如參數驗證中所述。 如果允許繼續執行，這些函式會將 errno 設為 EINVAL，並傳回 EINVAL。

備註

_searchenv_s 常式會搜尋指定網域中的目標檔案。 varname 變數可以是指定目錄路徑清單的任何環境或使用者定義變數，例如 PATH、LIB 和 INCLUDE。 因為 _searchenv_s 會區分大小寫，所以 varname 應該要與環境變數的大小寫相符。 如果 varname 不符合進程環境中定義的環境變數名稱，則函式會傳回零，而且 pathname 變數不會變更。

此常式會先搜尋目前工作目錄中的檔案。 如果找不到檔案，它會在環境變數所指定的目錄旁尋找。 如果目標檔案在這些目錄其中之一，則會將新建立的路徑複製到 pathname。 如果找不到檔案 filename ， pathname 則包含空的 Null 終止字串。

pathname 緩衝區應該要有至少 _MAX_PATH 字元的長度，藉此容納全部長度的建構路徑名稱。 否則，_searchenv_s 可能會讓 pathname 緩衝區滿溢，並造成未預期的行為。

_wsearchenv_s 是 _searchenv_s的寬字元版本； _wsearchenv_s 的引數是寬字元字串。 否則，_wsearchenv_s 和 _searchenv_s 的行為即會相同。

C++ 利用多載樣板簡化了這些函式的使用方式。多載可自動推斷緩衝區長度 (因而不須指定大小引數)，也可以將不安全的舊函式自動取代成較新且安全的對應函式。 如需詳細資訊，請參閱安全範本多載。

根據預設，此函式的全域狀態會限定於應用程式。 若要變更此行為，請參閱 CRT 中的全域狀態。

一般文字常式對應

Tchar.h 常式	_UNICODE 和 _MBCS 未定義	_MBCS 已定義	_UNICODE 已定義
_tsearchenv_s	_searchenv_s	_searchenv_s	_wsearchenv_s

需求

常式	必要的標頭
_searchenv_s	<stdlib.h>
_wsearchenv_s	<stdlib.h> 或 <wchar.h>

如需相容性詳細資訊，請參閱相容性。

範例

// 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

另請參閱

目錄控制件
_searchenv, _wsearchenv
getenv, _wgetenv
_putenv, _wputenv