getenv_s, _wgetenv_s

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

重要

この API は、Windows ランタイムで実行するアプリケーションでは使用できません。 詳細については、「ユニバーサル Windows プラットフォーム アプリでサポートされていない 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
環境変数名。

戻り値

正常に終了した場合は 0 を返し、それ以外の場合は失敗に関するエラー コードを返します。

エラー条件

pReturnValue	buffer	numberOfElements	varname	戻り値
NULL	任意	任意	任意	EINVAL
任意	NULL	>0	任意	EINVAL
任意	任意	任意	NULL	EINVAL

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

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

解説

getenv_s 関数は、環境変数のリストから varname を検索します。 Windows オペレーティング システムでは、getenv_s は大文字と小文字を区別しません。 getenv_s と _putenv_s は、_environ グローバル変数が指す環境のコピーを使用して環境にアクセスします。 getenv_s は、ランタイム ライブラリからアクセスできるデータ構造体だけを対象とし、プロセス用にオペレーティング システムで作成された環境 "セグメント" は参照しません。 そのため、プログラムで main または wmain の引数 envp を使用する場合、無効な情報を取得する可能性があります。

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

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

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

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

注意事項

まれに、ランタイム システムが Unicode 環境とマルチバイト環境の両方を保持している場合、これら 2 つの環境が正確に対応しないことがあります。 これは、一意のマルチバイト文字列はすべて一意の Unicode 文字列に対応していますが、一意の Unicode 文字列は必ずしも一意のマルチバイト文字列に対応していないために発生します。 詳細については、「 _environ」と「 _wenvironの両方を管理できます。

Note

_putenv_s 系関数と _getenv_s 系関数はスレッド セーフではありません。 _putenv_s が文字列を変更している間に _getenv_s が文字列ポインターを返すことがあり、これはランダム エラーの原因になります。 これらの関数の呼び出しが同期されていることを確認する必要があります。

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

既定では、この関数のグローバル状態の適用対象は、アプリケーションになります。 この動作を変更するには、「CRT でのグローバル状態」を参照してください。

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

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>

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

例

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

関連項目

プロセスと環境の制御
環境定数
_putenv, _wputenv
_dupenv_s, _wdupenv_s