Поделиться через

getenv_s, _wgetenv_s

  • Статья

Получает значение из текущей среды. Эти версии имеют _wgetenvулучшения безопасности, как описано в функциях getenvбезопасности в CRT.

Внимание

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

Синтаксис

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. getenv_s не учитывает регистр в операционной системе Windows. getenv_s и _putenv_s используют копию среды, указанную глобальной переменной _environ, для получения среды. getenv_s работает только в структурах данных, доступных в библиотеке времени выполнения, а не в "сегменте" среды, созданном для процесса операционной системой. Таким образом, программы, использующие аргумент main или wmain которые могут получить недопустимые envp сведения.

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

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

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

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

Внимание

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

Примечание.

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

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

По умолчанию глобальное состояние этой функции ограничивается приложением. Чтобы изменить это поведение, см . статью "Глобальное состояние" в 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>

Дополнительные сведения о совместимости см. в разделе Совместимость.

Пример

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