# 機能設計書 165-環境変数個別操作

## 概要

本ドキュメントは、libuv の `uv_os_getenv()` / `uv_os_setenv()` / `uv_os_unsetenv()` APIによる環境変数の個別取得・設定・削除機能について記述する。

### 本機能の処理概要

本機能は、特定の環境変数を名前で取得、設定、削除するためのクロスプラットフォームAPIを提供する。

**業務上の目的・背景**：アプリケーションでは特定の環境変数（PATH、HOME、HTTP_PROXY等）を個別に参照・変更する必要がある。Unixの`getenv()`/`setenv()`/`unsetenv()`とWindowsの`GetEnvironmentVariableW()`/`SetEnvironmentVariableW()`の差異を吸収し、統一的なインターフェースを提供する。libuvは追加としてバッファサイズのハンドリングと入力バリデーションを提供する。

**機能の利用シーン**：アプリケーション設定の読み込み（環境変数ベース）、プロキシ設定の取得、ロケール情報の参照、子プロセス実行前の環境変数設定、テスト環境でのモック設定に利用される。

**主要な処理内容**：
1. `uv_os_getenv()`: 指定名の環境変数値をバッファに取得する
2. `uv_os_setenv()`: 指定名の環境変数に値を設定する（既存値を上書き）
3. `uv_os_unsetenv()`: 指定名の環境変数を削除する

**関連システム・外部連携**：POSIX `getenv()` / `setenv()` / `unsetenv()`（Unix）、Windows `GetEnvironmentVariableW()` / `SetEnvironmentVariableW()`を使用する。

**権限による制御**：特に権限による制御はない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 29 | その他ユーティリティ | 主機能 | uv_os_getenv()/setenv()/unsetenv()による環境変数個別操作のAPI定義 |

## 機能種別

データ取得・設定・削除

## 入力仕様

### 入力パラメータ

#### uv_os_getenv()

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| name | const char* | Yes | 環境変数名 | NULLでないこと |
| buffer | char* | Yes | 値を格納するバッファ | NULLでないこと |
| size | size_t* | Yes | バッファサイズ（入出力パラメータ） | NULLでないこと、*size > 0 |

#### uv_os_setenv()

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| name | const char* | Yes | 環境変数名 | NULLでないこと |
| value | const char* | Yes | 設定する値 | NULLでないこと |

#### uv_os_unsetenv()

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| name | const char* | Yes | 環境変数名 | NULLでないこと |

### 入力データソース

呼び出し元から直接渡されるパラメータ / OS環境変数テーブル

## 出力仕様

### 出力データ

#### uv_os_getenv()

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | int | 成功時0、エラー時負のエラーコード |
| buffer | char* | 環境変数の値 |
| *size | size_t | 値の長さ（NULL終端を含まない） |

#### uv_os_setenv() / uv_os_unsetenv()

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | int | 成功時0、エラー時負のエラーコード |

### 出力先

呼び出し元に直接返却 / OS環境変数テーブルへの反映

## 処理フロー

### 処理シーケンス

```
uv_os_getenv():
1. 入力バリデーション（name, buffer, size, *sizeがNULLまたは0でないこと）
   └─ 無効な場合UV_EINVALを返却
2. getenv(name)で環境変数値を取得
   └─ NULLの場合UV_ENOENTを返却
3. 値の長さを計算
4. バッファサイズが不足する場合
   └─ *size = len + 1を設定しUV_ENOBUFSを返却
5. memcpy()でバッファに値をコピー
6. *size = lenを設定して成功を返却

uv_os_setenv():
1. 入力バリデーション（name, valueがNULLでないこと）
   └─ 無効な場合UV_EINVALを返却
2. setenv(name, value, 1)で環境変数を設定（既存値上書き）
   └─ 失敗時はerrnoベースのエラーコードを返却

uv_os_unsetenv():
1. 入力バリデーション（nameがNULLでないこと）
   └─ 無効な場合UV_EINVALを返却
2. unsetenv(name)で環境変数を削除
   └─ 失敗時はerrnoベースのエラーコードを返却
```

### フローチャート

```mermaid
flowchart TD
    A[uv_os_getenv name, buffer, size] --> B{入力バリデーション}
    B -->|不正| C[UV_EINVAL返却]
    B -->|OK| D[getenv name]
    D --> E{結果NULL?}
    E -->|Yes| F[UV_ENOENT返却]
    E -->|No| G[len = strlen var]
    G --> H{len >= *size?}
    H -->|Yes| I[*size = len+1, UV_ENOBUFS]
    H -->|No| J[memcpy buffer, var, len+1]
    J --> K[*size = len, return 0]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 既存値上書き | uv_os_setenv()は既存の環境変数値を常に上書きする（setenvの第3引数=1） | uv_os_setenv呼び出し時 |
| BR-02 | バッファ不足時サイズ返却 | uv_os_getenv()でバッファ不足の場合、必要サイズを*sizeに返す | len >= *size |
| BR-03 | 未設定変数のエラー | 指定名の環境変数が存在しない場合UV_ENOENTを返す | getenvがNULLを返した場合 |

### 計算ロジック

該当なし

## データベース操作仕様

該当なし（データベースは使用しない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| UV_EINVAL | バリデーションエラー | name/buffer/sizeがNULL、*size=0 | 有効なパラメータを指定する |
| UV_ENOENT | 未設定 | 指定名の環境変数が存在しない | 環境変数名を確認する |
| UV_ENOBUFS | バッファ不足 | バッファサイズが不足 | *sizeの値以上のバッファを確保して再呼び出し |
| UV_ENOMEM | メモリ不足 | setenvのメモリ確保失敗 | メモリを解放してリトライ |

### リトライ仕様

UV_ENOBUFSの場合、返却された*sizeに基づきバッファを再確保して再呼び出しする。

## トランザクション仕様

該当なし

## パフォーマンス要件

POSIXのgetenv/setenv/unsetenvの直接ラッパーであり、特段のパフォーマンス要件はない。

## セキュリティ考慮事項

- 環境変数にはパスワードやトークンなどの機密情報が含まれる可能性がある
- setenv/unsetenvはプロセスグローバルに影響するため、マルチスレッド環境では注意が必要
- getenvの戻り値のライフタイムに注意（libuvではmemcpyでコピーするため安全）

## 備考

- Unix実装では内部的にPOSIXの`getenv()` / `setenv()` / `unsetenv()`を使用
- `uv_os_getenv()` はgetenv()の結果をmemcpyでコピーするため、スレッドセーフ性が向上
- `setenv()` の第3引数overwrite=1で常に上書き

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

本機能固有のデータ構造は使用しない。標準Cの文字列バッファでやり取りする。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | L1371-1373: uv_os_getenv()/setenv()/unsetenv()のAPI宣言 |

#### Step 2: uv_os_getenv()を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | core.c | `src/unix/core.c` | L1580-1603: uv_os_getenv()のUnix実装 |

**主要処理フロー**:
1. **1584-1585行目**: 入力バリデーション（name, buffer, size, *sizeのNULL/0チェック）
2. **1587行目**: getenv(name)で値取得
3. **1589-1590行目**: NULL（未設定）の場合UV_ENOENT
4. **1594-1596行目**: バッファ不足の場合UV_ENOBUFS（必要サイズ返却）
5. **1599-1600行目**: memcpyでコピーし、*sizeに長さを設定

#### Step 3: uv_os_setenv()/uv_os_unsetenv()を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | core.c | `src/unix/core.c` | L1606-1614: uv_os_setenv()のUnix実装 |
| 3-2 | core.c | `src/unix/core.c` | L1617-1624: uv_os_unsetenv()のUnix実装 |

**主要処理フロー**:
- **1607-1608行目**: name/valueのNULLチェック
- **1610-1611行目**: setenv(name, value, 1)呼び出し、overwrite=1
- **1618-1619行目**: nameのNULLチェック
- **1621-1622行目**: unsetenv(name)呼び出し

### プログラム呼び出し階層図

```
uv_os_getenv() [src/unix/core.c:1580]
    |
    +-- getenv() [POSIX]
    +-- strlen()
    +-- memcpy()

uv_os_setenv() [src/unix/core.c:1606]
    |
    +-- setenv(name, value, 1) [POSIX]

uv_os_unsetenv() [src/unix/core.c:1617]
    |
    +-- unsetenv(name) [POSIX]
```

### データフロー図

```
[入力]                    [処理]                           [出力]

name (const char*) ───> getenv() で値取得             ───> buffer に値をコピー
buffer (char*)           strlen() + memcpy()                *size に長さを設定
size (size_t*)                                              戻り値 (0 or エラー)

name, value        ───> setenv(name, value, 1)        ───> OS環境変数テーブル更新
name               ───> unsetenv(name)                ───> OS環境変数テーブルから削除
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダー | API宣言（L1371-1373） |
| core.c | `src/unix/core.c` | ソース | Unix実装（L1580-1624） |
| util.c | `src/win/util.c` | ソース | Windows実装 |
