getenv_s、_wgetenv_sgetenv_s, _wgetenv_s

現在の環境から値を取得します。Gets a value from the current environment. これらの getenv および _wgetenvgets のバージョンは、「Security Features in the CRT」(CRT のセキュリティ機能) で説明されているように、セキュリティが強化されています。These versions of getenv, _wgetenv have security enhancements, as described in Security Features in the CRT.

重要

この API は、Windows ランタイムで実行するアプリケーションでは使用できません。This API cannot be used in applications that execute in the Windows Runtime. 詳細については、「ユニバーサル Windows プラットフォーム アプリでサポートされていない CRT 関数」を参照してください。For more information, see CRT functions not supported in Universal Windows Platform apps.

構文Syntax

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

パラメーターParameters

pReturnValuepReturnValue
必要なバッファー サイズ。変数が見つからない場合は 0。The buffer size that's required, or 0 if the variable is not found.

バッファーbuffer
環境変数の値を格納するバッファー。Buffer to store the value of the environment variable.

numberOfElementsnumberOfElements
バッファーのサイズ。Size of buffer.

varnamevarname
環境変数名。Environment variable name.

戻り値Return Value

正常に終了した場合は 0 を返し、それ以外の場合は失敗に関するエラー コードを返します。Zero if successful; otherwise, an error code on failure.

エラー条件Error Conditions

pReturnValuepReturnValue バッファーbuffer numberOfElementsnumberOfElements varnamevarname 戻り値Return Value
NULLNULL 任意any 任意any 任意any EINVALEINVAL
任意any NULLNULL >0>0 任意any EINVALEINVAL
任意any 任意any 任意any NULLNULL EINVALEINVAL

これらのいずれかのエラー条件の場合は、「Parameter Validation」(パラメーターの検証) で説明されているように、無効なパラメーター ハンドラーが呼び出されます。Any of these error conditions invokes an invalid parameter handler, as described in Parameter Validation. 実行の継続が許可された場合、関数はerrnoeinvalに設定し、 einvalを返します。If execution is allowed to continue, the functions set errno to EINVAL and return EINVAL.

また、バッファーが小さすぎる場合、これらの関数はERANGEを返します。Also, if the buffer is too small, these functions return ERANGE. 無効なパラメーター ハンドラーは呼び出されません。They do not invoke an invalid parameter handler. これらは、必要なバッファーサイズをPreturnvalue値として書き込みます。これにより、プログラムはより大きなバッファーを使用して関数を再度呼び出すことができます。They write out the required buffer size in pReturnValue, and thereby enable programs to call the function again with a larger buffer.

RemarksRemarks

Getenv_s関数は、変数varnameの環境変数の一覧を検索します。The getenv_s function searches the list of environment variables for varname. Windows オペレーティングシステムでは、 getenv_sは大文字と小文字が区別されません。getenv_s is not case sensitive in the Windows operating system. getenv_s_putenv_sは、グローバル変数 _environが指す環境のコピーを使用して環境にアクセスします。getenv_s and _putenv_s use the copy of the environment that's pointed to by the global variable _environ to access the environment. getenv_sは、ランタイムライブラリからアクセスできるデータ構造体でのみ動作し、オペレーティングシステムによってプロセス用に作成された環境 "セグメント" では動作しません。getenv_s operates only on the data structures that are accessible to the run-time library and not on the environment "segment" that's created for the process by the operating system. そのため、 mainまたはwmainに対してenvp引数を使用するプログラムは、無効な情報を取得する可能性があります。Therefore, programs that use the envp argument to main or wmain might retrieve invalid information.

_wgetenv_sは、 getenv_sのワイド文字バージョンです。 _wgetenv_sの引数と戻り値はワイド文字列です。_wgetenv_s is a wide-character version of getenv_s; the argument and return value of _wgetenv_s are wide-character strings. _Wenvironグローバル変数は、 _environのワイド文字バージョンです。The _wenviron global variable is a wide-character version of _environ.

MBCS プログラム (SBCS ASCII プログラムなど) では、環境がマルチバイト文字列で構成されているため、 _wenvironは最初はNULLになります。In an MBCS program (for example, in an SBCS ASCII program), _wenviron is initially NULL because the environment is composed of multibyte-character strings. 次に、 _wputenvへの最初の呼び出しで、または _wgetenv_sの最初の呼び出しで、(MBCS) 環境が既に存在する場合は、対応するワイド文字列環境が作成され、その後、 _wenvironによってポイントされます。Then, on the first call to _wputenv, or on the first call to _wgetenv_s, if an (MBCS) environment already exists, a corresponding wide-character string environment is created and is then pointed to by _wenviron.

同様に、Unicode ( _wmain) プログラムでは、環境がワイド文字列で構成されているため、 _environは最初はNULLになります。Similarly in a Unicode (_wmain) program, _environ is initially NULL because the environment is composed of wide-character strings. 次に、 _putenvへの最初の呼び出しで、または (Unicode) 環境が既に存在する場合にgetenv_sを初めて呼び出すときに、対応する MBCS 環境が作成され、次に _environによってポイントされます。Then, on the first call to _putenv, or on the first call to getenv_s if a (Unicode) environment already exists, a corresponding MBCS environment is created and is then pointed to by _environ.

2 つの環境のコピー (MBCS および Unicode) がプログラムに同時に存在する場合、ランタイム システムは、両方のコピーを保持する必要があるため、実行時間が長くなります。When two copies of the environment (MBCS and Unicode) exist simultaneously in a program, the run-time system must maintain both copies, and this causes slower execution time. たとえば、 _putenvを呼び出すと、2つの環境文字列が対応するように _wputenvの呼び出しも自動的に実行されます。For example, when you call _putenv, a call to _wputenv is also executed automatically so that the two environment strings correspond.

注意事項

まれに、ランタイム システムが Unicode 環境とマルチバイト環境の両方を保持している場合、これら 2 つの環境が正確に対応しないことがあります。In rare instances, when the run-time system is maintaining both a Unicode version and a multibyte version of the environment, the two environment versions may not correspond exactly. これは、一意のマルチバイト文字列はすべて一意の Unicode 文字列に対応していますが、一意の Unicode 文字列は必ずしも一意のマルチバイト文字列に対応していないために発生します。This happens because, although any unique multibyte-character string maps to a unique Unicode string, the mapping from a unique Unicode string to a multibyte-character string is not necessarily unique. 詳細については、「_environ、_wenviron」をご覧ください。For more information, see _environ, _wenviron.

注意

_Putenv_sおよび _getenv_sファミリの関数はスレッドセーフではありません。The _putenv_s and _getenv_s families of functions are not thread-safe. _getenv_sは文字列を変更している間に文字列ポインターを返すことがあり、その結果、ランダムにエラーが発生します。_getenv_s could return a string pointer while _putenv_s is modifying the string and thereby cause random failures. これらの関数の呼び出しが同期されていることを確認する必要があります。Make sure that calls to these functions are synchronized.

C++ では、テンプレートのオーバーロードによってこれらの関数を簡単に使用できます。オーバーロードでは、バッファー長を自動的に推論できるため、サイズ引数を指定する必要がなくなります。In C++, use of these functions is simplified by template overloads; the overloads can infer buffer length automatically and thereby eliminate the need to specify a size argument. 詳細については、「セキュリティ保護されたテンプレート オーバーロード」を参照してください。For more information, see Secure Template Overloads.

汎用テキスト ルーチンのマップGeneric-Text Routine Mappings

TCHAR.H のルーチンTCHAR.H routine _UNICODE および _MBCS が未定義の場合_UNICODE & _MBCS not defined _MBCS が定義されている場合_MBCS defined _UNICODE が定義されている場合_UNICODE defined
_tgetenv_s_tgetenv_s getenv_sgetenv_s getenv_sgetenv_s _wgetenv_s_wgetenv_s

TZ環境変数の値を確認または変更するには、必要に応じて、 getenv_s_putenv、および _tzsetを使用します。To check or change the value of the TZ environment variable, use getenv_s, _putenv, and _tzset, as required. TZの詳細については、「 _tzset 」および「夏時間」、「_tzname」、「」を参照してください。For more information about TZ, see _tzset and _daylight, _dstbias, _timezone, and _tzname.

必要条件Requirements

ルーチンによって返される値Routine 必須ヘッダーRequired header
getenv_sgetenv_s <stdlib.h><stdlib.h>
_wgetenv_s_wgetenv_s <stdlib.h> または <wchar.h><stdlib.h> or <wchar.h>

互換性の詳細については、「 互換性」を参照してください。For additional compatibility information, see Compatibility.

Example

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

関連項目See also

プロセス制御と環境制御Process and Environment Control
環境定数Environmental Constants
_putenv、_wputenv_putenv, _wputenv
_dupenv_s、_wdupenv_s_dupenv_s, _wdupenv_s