_putenv_s、_wputenv_s

[アーティクル]
09/17/2008

更新 : 2007 年 11 月

新しい環境変数を作成します。あるいは既存の環境変数を変更または削除します。これらの関数は、「CRT のセキュリティ強化」に説明されているように、_putenv、_wputenv のセキュリティが強化されたバージョンです。

errno_t _putenv_s(
   const char *name,
   const char *value 
);
errno_t _wputenv_s(
   const wchar_t *name,
   const wchar_t *value
);

パラメータ

name
環境変数名。
value
環境変数の設定値。

戻り値

正常終了した場合は 0 を返し、失敗した場合はエラーコードを返します。

エラー条件

name	value	戻り値
NULL	any	EINVAL
any	NULL	EINVAL

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

解説

_putenv_s 関数は、新しい環境変数を追加するか、既存の環境変数の値を変更します。環境変数は、プロセスが実行される環境を定義します (たとえば、プログラムとリンクするライブラリの既定の検索パスなど)。ワイド文字を扱う場合は、_putenv_s ではなく _wputenv_s を使用します。この場合、_wputenv_s の envstring 引数には、ワイド文字列を指定します。

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

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

name は追加または変更する環境変数の名前であり、value は変数の値です。name が既に環境に設定されている場合は、その値が value に置き換えられます。それ以外の場合は、新しい name 変数とその value が環境に追加されます。value に空の文字列 ("") を指定すると、環境から変数を削除できます。

_putenv_s 関数と _wputenv_s 関数は、現在のプロセスのローカル環境にしか影響しません。これらの関数を使用して、コマンドレベルの環境は変更できません。つまり、これらの関数で変更できるのは、ランタイムライブラリにアクセスできるデータ構造だけであり、オペレーティングシステムでのプロセス用に作成される環境セグメントは変更しません。現在実行中のプロセスが終了すると、呼び出しプロセス (ほとんどの場合はオペレーティングシステムレベル) の環境が復元されます。ただし、変更された環境は、_spawn、_exec、または system の各関数で作成された新しいプロセスに渡すことができます。新しいプロセスは、_putenv_s 関数および _wputenv_s 関数によって追加された新しい項目を取得します。

環境エントリは直接変更せず、_putenv_s 関数または _wputenv_s 関数を使用して変更します。特に、_environ[] グローバル配列の要素を直接解放すると、無効なメモリアドレスが指定される可能性があります。

getenv 関数および _putenv_s 関数は、_environ グローバル変数を使用して環境テーブルにアクセスします。したがって、_wgetenv 関数および _wputenv_s 関数は _wenviron を使用します。_putenv_s 関数および _wputenv_s 関数は、_environ および _wenviron の値を変更する場合があるため、main の envp 引数、および wmain の _wenvp 引数は無効になります。したがって、環境情報にアクセスする場合は、_environ または _wenviron を使用する方が安全です。_putenv_s 関数および _wputenv_s 関数とグローバル変数の関係については、_environ、_wenviron の説明を参照してください。

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