getenv_s、_wgetenv_s

現在の環境から値を取得します。getenv、_wgetenv これらのバージョンのに CRT のセキュリティ機能に説明されているように、のセキュリティが強化があります。

重要
この API は Windows ランタイムで実行されるアプリケーションで使用することはできません。詳細については、でサポート /ZW CRT 関数" "を参照してください。

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

パラメーター

• pReturnValue
  変数が見つからない場合、または必要なバッファー サイズは 0。

• buffer
  環境変数の値を格納するバッファー。

• numberOfElements
  buffer のサイズ。

• varname
  環境変数名。

戻り値

正常終了した場合はゼロ; 失敗した場合はエラー コード。

エラー条件

pReturnValue	buffer	numberOfElements	varname	戻り値
NULL	任意	任意	任意	EINVAL
任意	NULL	0 より大きい	任意	EINVAL
任意	任意	任意	NULL	EINVAL

これらのエラー条件のいずれかに パラメーターの検証に説明されているように、無効なパラメーター ハンドラーが実行されます。実行の継続が許可された場合、この関数は errno を EINVAL に設定し、EINVAL を返します。

また、バッファーが小さすぎる場合は、ERANGE が返されます。無効なパラメーター ハンドラーは呼び出されません。これらは pReturnValueの必要なバッファー サイズを書き出し、より大きなバッファーをの関数を再びプログラムを呼び出すことができます。

解説

getenv_s 関数は、環境変数のリストから varname を検索します。Windows オペレーティング システムでは、getenv_s 関数は大文字と小文字を区別しません。getenv_s と _putenv_s は、環境にアクセスするには _environ グローバル変数が指す環境のコピーを使用します。getenv_s は、ランタイム ライブラリから、つまりオペレーティング システムによってプロセス用に作成された環境 "segment" でアクセスできるデータ構造体でのみ動作します。したがって、主要 か wmain に envp の引数を使用するプログラムは、無効な情報を取得することがあります。

ワイド文字を扱う場合は、getenv_s ではなく _wgetenv_s を使用します。_wgetenv_s の場合、引数にはワイド文字列を指定します。また戻り値もワイド文字列です。_wenviron グローバル変数は _environ と同じですが、ワイド文字を扱えるという点で異なっています。

SBCS ASCII プログラムなどの MBCS プログラムでは、環境がマルチバイト文字列で構成されているため、_wenviron の初期値は NULL です。その後、(MBCS) 環境が既に存在する場合、_wputenvへの最初の呼び出し、または _wgetenv_sへの最初の呼び出しで、対応するワイド文字列環境が _wenvironによって作成され、その後されます。

同様に、Unicode (_wmain) プログラムでは、環境がワイド文字列で構成されているため、_environ の初期値は NULL です。その後、_putenv を最初に呼び出すとき、または (Unicode) 環境が既に存在する場合に getenv_s を最初に呼び出すときは、対応する MBCS 環境が作成され、その後は作成された MBCS 環境が _environ によって参照されます。

環境の 2 種類のコピーがプログラムに (MBCS および Unicode) がに存在する場合、ランタイム システムは、両方のコピーを保持する必要があります。これにより、実行時間が発生します。たとえば、_putenvを呼び出すと、_wputenv の呼び出しは、2 種類の環境文字列が対応するように自動的に実行されます。

注意
まれに、ランタイム システムが Unicode 環境とマルチバイトのバージョンの両方を保持している場合、2 種類の環境のバージョンは、対応しないことがあります。これは、一意の Unicode 文字列に、一意のマルチバイト文字列マップでも、一意の Unicode 文字列のマルチバイト文字列への割り当てが必ずしも一意ではないために発生します。詳細については、「_environ、_wenviron」を参照してください。

[!メモ]

_putenv_s 系関数と _getenv_s 系関数はスレッド セーフではありません。_getenv_s は _putenv_s が文字列とそれによって発生しだいのあるエラーを変更中に文字列ポインターを返すことができます。これらの関数の呼び出しが同期されていることを確認する必要があります。

C++ では、これらの関数の使用はテンプレート オーバーロードによって簡素化されています; はオーバーロードでは、バッファー長を自動的に推論し、サイズ引数を指定する必要がなくなります。詳細については、「セキュリティ保護されたテンプレート オーバーロード」を参照してください。

汎用テキスト ルーチンのマップ

TCHAR.H のルーチン	_UNICODE および _MBCS が未定義の場合	_MBCS が定義されている場合	_UNICODE が定義されている場合
_tgetenv_s	getenv_s	getenv_s	_wgetenv_s

TZ の環境変数、使用 getenv_s、_putenvと _tzsetの値を確認または変更するには、または、必要に応じて。TZ の詳細については、「_tzset」および「_daylight、_dstbias、_timezone、および _tzname」を参照してください。

必要条件

ルーチン	必須ヘッダー
getenv_s	<stdlib.h>
_wgetenv_s	<stdlib.h> または <wchar.h>

追加の互換性の詳細については、互換性を参照してください。

使用例

// 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);
}

同等の .NET Framework 関数

System::Environment::GetEnvironmentVariable

参照

関連項目

プロセス制御と環境制御

環境定数

_putenv、_wputenv

_dupenv_s、_wdupenv_s