_searchenv_s, _wsearchenv_s

Mencari file dengan menggunakan jalur lingkungan. Versi _searchenv, _wsearchenv ini memiliki peningkatan keamanan, seperti yang dijelaskan dalam Fitur keamanan di CRT.

Penting

API ini tidak dapat digunakan dalam aplikasi yang dijalankan di Windows Runtime. Untuk informasi selengkapnya, lihat Fungsi CRT yang tidak didukung di aplikasi Platform Windows Universal.

Sintaks

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

Parameter

filename
Nama file yang akan dicari.

varname
Lingkungan untuk dicari.

pathname
Buffer untuk menyimpan jalur lengkap.

numberOfElements
pathname Ukuran buffer.

Nilai hasil

Nol jika berhasil; kode kesalahan pada kegagalan.

Jika filename adalah string kosong, nilai yang dikembalikan adalah ENOENT.

Kondisi kesalahan

filename	varname	pathname	numberOfElements	Nilai hasil	Isi dari pathname
any	any	NULL	any	EINVAL	n/a
NULL	any	any	any	EINVAL	tidak diubah
any	any	any	<=0	EINVAL	tidak diubah

Jika salah satu kondisi kesalahan ini terjadi, handler parameter yang tidak valid dipanggil, seperti yang dijelaskan dalam Validasi parameter. Jika eksekusi diizinkan untuk melanjutkan, fungsi-fungsi ini diatur errno ke EINVAL dan mengembalikan EINVAL.

Keterangan

Rutinitas _searchenv_s mencari file target di domain yang ditentukan. Variabel varname dapat berupa lingkungan apa pun atau variabel yang ditentukan pengguna yang menentukan daftar jalur direktori, seperti PATH, , LIBdan INCLUDE. Karena _searchenv_s peka huruf besar/kecil, varname harus cocok dengan kasus variabel lingkungan. Jika varname tidak cocok dengan nama variabel lingkungan yang ditentukan dalam lingkungan proses, fungsi mengembalikan nol, dan pathname variabel tidak berubah.

Rutinitas mencari file terlebih dahulu di direktori kerja saat ini. Jika tidak menemukan file, file akan terlihat di samping direktori yang ditentukan oleh variabel lingkungan. Jika file target berada di salah satu direktori tersebut, jalur yang baru dibuat disalin ke dalam pathname. filename Jika file tidak ditemukan, pathname berisi string kosong yang dihentikan null.

Buffer pathname harus setidaknya _MAX_PATH panjang karakter untuk mengakomodasi panjang penuh nama jalur yang dibangun. Jika tidak, _searchenv_s mungkin menimpa pathname buffer yang mengakibatkan perilaku tak terduga.

_wsearchenv_s adalah versi karakter luas dari _searchenv_s; argumen untuk _wsearchenv_s adalah string karakter lebar. _wsearchenv_s dan _searchenv_s berulah secara identik jika tidak.

Di C++, menggunakan fungsi-fungsi ini disederhanakan oleh kelebihan beban templat; kelebihan beban dapat menyimpulkan panjang buffer secara otomatis (menghilangkan kebutuhan untuk menentukan argumen ukuran) dan mereka dapat secara otomatis mengganti fungsi lama yang tidak aman dengan rekan-rekan yang lebih baru dan aman. Untuk informasi selengkapnya, lihat Mengamankan kelebihan beban templat.

Secara default, status global fungsi ini dicakup ke aplikasi. Untuk mengubah perilaku ini, lihat Status global di CRT.

Pemetaan rutin teks generik

Rutinitas Tchar.h	_UNICODE dan _MBCS tidak ditentukan	_MBCS Didefinisikan	_UNICODE Didefinisikan
_tsearchenv_s	_searchenv_s	_searchenv_s	_wsearchenv_s

Persyaratan

Rutin	Header yang diperlukan
_searchenv_s	<stdlib.h>
_wsearchenv_s	<stdlib.h> atau <wchar.h>

Untuk informasi kompatibilitas selengkapnya, lihat Kompatibilitas.

Contoh

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

Baca juga

Kontrol direktori
_searchenv, _wsearchenv
getenv, _wgetenv
_putenv, _wputenv