getenv_s, _wgetenv_s

Статья
06/09/2015

Получает значение из текущей среды. В этих версиях getenv, _wgetenv усовершенствована безопасность, как описано в разделе Функции безопасности в CRT.

Важно!

Этот API не может использоваться в приложениях, выполняемых в Среда выполнения Windows.Дополнительные сведения см. в статье Функции CRT, которые не поддерживаются с ключом /ZW.

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	any	any	any	EINVAL
any	NULL	>0	any	EINVAL
any	any	any	NULL	EINVAL

При любом из этих условий ошибки вызывается обработчик недопустимого параметра, как описано в разделе Проверка параметров. Если продолжение выполнения разрешено, эти функции устанавливают для errno значение EINVAL и возвращают EINVAL.

Кроме того, если буфер слишком мал, эти функции возвращают ERANGE. Они не вызывают обработчик недопустимого параметра. Они записывают необходимый размер буфера в pReturnValue, поэтому программы могут вызвать функцию снова с большим буфером.

Заметки

Функция getenv_s ищет список переменных среды для varname. getenv_s не учитывает регистр в операционной системе Windows. getenv_s и _putenv_s используют копию среды, указанную в глобальной переменной _environ, для получения среды. getenv_s работает только в структурах данных, доступных в библиотеке среды выполнения, а не в «сегменте» среды, созданном для процесса операционной системой. Поэтому программы, использующие аргумент envp в main или wmain, могут извлекать неверную информацию.

_wgetenv_s — это двухбайтовая версия функции getenv_s; аргумент и возвращаемое значение _wgetenv_s являются строками двухбайтовых символов. Глобальная переменная _wenviron является версией _environ для расширенных символов.

В программе с многобайтовой кодировкой (например, в программе с кодировкой SBCS ASCII), _wenviron инициализируется NULL, поскольку среда состоит из строк многобайтовой кодировки. Затем при первом вызове функции _wputenv или _wgetenv_s, если среда (многобайтовой кодировки) уже существует, создается среда для поддержки расширенных строк, на нее затем устанавливается указатель _wenviron.

Аналогично в программе Юникода (_wmain), _environ инициализируется NULL, поскольку среда состоит из расширенных строк. При первом вызове функции _putenv или getenv_s, если среда (Юникода) уже существует, создается среда для поддержки многобайтовых строк, на нее затем устанавливается указатель _environ.

Когда две копии среды (многобайтовой кодировки и Юникода) существуют одновременно в программе, система времени выполнения должна поддерживать обе копии, что отрицательно сказывается на скорости выполнения программы. Например, при вызове _putenv, вызов _wputenv также выполняется автоматически, чтобы две строки среды совпадали.

Предупреждение

В редких случаях, когда система времени выполнения поддерживает и версию Юникода, и многобайтовую версию, эти две версии среды могут не соответствовать точно.Это происходит потому, что, хотя любая уникальная расширенная строка сопоставлена уникальной строке Юникода, сопоставление уникальной строки Юникода со строкой многобайтовой кодировки не обязательно будет уникальными.Для получения дополнительной информации см. _environ, _wenviron.

Примечание

Семейства функций _putenv_s и _getenv_s не являются потокобезопасными._getenv_s может вернуть указатель строки, в то время как _putenv_s изменяет строку, что может вызвать случайные сбои.Убедитесь, что вызовы этих функций синхронизированы.

В C++ использование этих функций упрощено шаблонными перегрузками; перегрузки могут определить длину буфера автоматически, устранена необходимость указывать аргумент size. Дополнительные сведения см. в разделе Безопасные перегрузки шаблонов.

Универсальное текстовое сопоставление функций

Подпрограмма 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);
}