Bagikan melalui

getenv_s, _wgetenv_s

  • Artikel

Mendapatkan nilai dari lingkungan saat ini. Versi getenv, _wgetenv 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 getenv_s(
   size_t *pReturnValue,
   char* buffer,
   size_t numberOfElements,
   const char *varname
);
errno_t _wgetenv_s(
   size_t *pReturnValue,
   wchar_t *buffer,
   size_t numberOfElements,
   const wchar_t *varname
);
template <size_t size>
errno_t getenv_s(
   size_t *pReturnValue,
   char (&buffer)[size],
   const char *varname
); // C++ only
template <size_t size>
errno_t _wgetenv_s(
   size_t *pReturnValue,
   wchar_t (&buffer)[size],
   const wchar_t *varname
); // C++ only

Parameter

pReturnValue
Ukuran buffer yang diperlukan, atau 0 jika variabel tidak ditemukan.

buffer
Buffer untuk menyimpan nilai variabel lingkungan.

numberOfElements
bufferUkuran .

varname
Nama variabel lingkungan.

Nilai hasil

Nol jika berhasil; jika tidak, kode kesalahan pada kegagalan.

Kondisi kesalahan

pReturnValue buffer numberOfElements varname Tampilkan Nilai
NULL any any any EINVAL
any NULL >0 any EINVAL
any any any NULL EINVAL

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

Selain itu, jika buffer terlalu kecil, fungsi-fungsi ini mengembalikan ERANGE. Mereka tidak memanggil handler parameter yang tidak valid. Mereka menulis ukuran buffer yang diperlukan dalam pReturnValue, dan dengan demikian memungkinkan program untuk memanggil fungsi lagi dengan buffer yang lebih besar.

Keterangan

Fungsi ini getenv_s mencari daftar variabel lingkungan untuk varname. getenv_s tidak peka huruf besar/kecil dalam sistem operasi Windows. getenv_s dan _putenv_s gunakan salinan lingkungan yang ditujukkan oleh variabel _environ global untuk mengakses lingkungan. getenv_s hanya beroperasi pada struktur data yang dapat diakses oleh pustaka run-time dan bukan pada lingkungan "segmen" yang dibuat untuk proses oleh sistem operasi. Oleh karena itu, program yang menggunakan argumen ke envp main atau wmain mungkin mengambil informasi yang tidak valid.

_wgetenv_s adalah versi karakter yang luas dari getenv_s; argumen dan nilai yang dikembalikan adalah _wgetenv_s string karakter lebar. Variabel _wenviron global adalah versi karakter luas dari _environ.

Dalam program MBCS (misalnya, dalam program SBCS ASCII), _wenviron awalnya NULL karena lingkungan terdiri dari string karakter multibyte. Kemudian, pada panggilan pertama ke _wputenv, atau pada panggilan pertama ke _wgetenv_s, jika lingkungan (MBCS) sudah ada, lingkungan string karakter lebar yang sesuai dibuat dan kemudian ditujukkan oleh _wenviron.

Demikian pula dalam program _environ Unicode (_wmain), awalnya NULL karena lingkungan terdiri dari string karakter luas. Kemudian, pada panggilan pertama ke _putenv, atau pada panggilan pertama ke getenv_s jika lingkungan (Unicode) sudah ada, lingkungan MBCS yang sesuai dibuat dan kemudian ditujukkan oleh _environ.

Ketika dua salinan lingkungan (MBCS dan Unicode) ada secara bersamaan dalam suatu program, eksekusi dapat memakan waktu lebih lama, karena sistem run-time harus mempertahankan kedua salinan. Misalnya, saat Anda memanggil _putenv, panggilan ke _wputenv juga dijalankan secara otomatis sehingga kedua string lingkungan sesuai.

Perhatian

Dalam instans yang jarang terjadi, ketika sistem run-time mempertahankan versi Unicode dan versi multibyte lingkungan, kedua versi lingkungan mungkin tidak sesuai persis. Ini terjadi karena, meskipun string karakter multibyte unik memetakan ke string Unicode yang unik, pemetaan dari string Unicode unik ke string karakter multibyte belum tentu unik. Untuk informasi selengkapnya, lihat _environ, _wenviron.

Catatan

Keluarga _putenv_s fungsi dan _getenv_s tidak aman utas. _getenv_s dapat mengembalikan penunjuk string saat _putenv_s memodifikasi string dan dengan demikian menyebabkan kegagalan acak. Pastikan bahwa panggilan ke fungsi-fungsi ini disinkronkan.

Di C++, penggunaan fungsi-fungsi ini disederhanakan oleh kelebihan beban templat; kelebihan beban dapat menyimpulkan panjang buffer secara otomatis dan dengan demikian menghilangkan kebutuhan untuk menentukan argumen ukuran. 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

TCHAR.H Rutin _UNICODE dan _MBCS tidak ditentukan _MBCS Didefinisikan _UNICODE Didefinisikan
_tgetenv_s getenv_s getenv_s _wgetenv_s

Untuk memeriksa atau mengubah nilai TZ variabel lingkungan, gunakan getenv_s, , _putenvdan _tzset, sesuai kebutuhan. Untuk informasi selengkapnya tentang TZ, lihat _tzset dan _daylight, _dstbias, , _timezonedan _tzname.

Persyaratan

Rutin Header yang diperlukan
getenv_s <stdlib.h>
_wgetenv_s <stdlib.h> atau <wchar.h>

Untuk informasi kompatibilitas selengkapnya, lihat Kompatibilitas.

Contoh

// crt_getenv_s.c
// This program uses getenv_s to retrieve
// the LIB environment variable and then uses
// _putenv to change it to a new value.

#include <stdlib.h>
#include <stdio.h>

int main( void )
{
   char* libvar;
   size_t requiredSize;

   getenv_s( &requiredSize, NULL, 0, "LIB");
   if (requiredSize == 0)
   {
      printf("LIB doesn't exist!\n");
      exit(1);
   }

   libvar = (char*) malloc(requiredSize * sizeof(char));
   if (!libvar)
   {
      printf("Failed to allocate memory!\n");
      exit(1);
   }

   // Get the value of the LIB environment variable.
   getenv_s( &requiredSize, libvar, requiredSize, "LIB" );

   printf( "Original LIB variable is: %s\n", libvar );

   // Attempt to change path. Note that this only affects
   // the environment variable of the current process. The command
   // processor's environment is not changed.
   _putenv_s( "LIB", "c:\\mylib;c:\\yourlib" );

   getenv_s( &requiredSize, NULL, 0, "LIB");

   libvar = (char*) realloc(libvar, requiredSize * sizeof(char));
   if (!libvar)
   {
      printf("Failed to allocate memory!\n");
      exit(1);
   }

   // Get the new value of the LIB environment variable.
   getenv_s( &requiredSize, libvar, requiredSize, "LIB" );

   printf( "New LIB variable is: %s\n", libvar );

   free(libvar);
}

Original LIB variable is: c:\vctools\lib;c:\vctools\atlmfc\lib;c:\vctools\PlatformSDK\lib;c:\vctools\Visual Studio SDKs\DIA Sdk\lib;c:\vctools\Visual Studio SDKs\BSC Sdk\lib
New LIB variable is: c:\mylib;c:\yourlib

Lihat juga

Kontrol proses dan lingkungan
Konstanta lingkungan
_putenv, _wputenv
_dupenv_s, _wdupenv_s