# 機能設計書 167-テンポラリディレクトリ取得

## 概要

本ドキュメントは、libuv の `uv_os_tmpdir()` APIによるシステムの一時ディレクトリパス取得機能について記述する。

### 本機能の処理概要

本機能は、システムの一時ディレクトリ（テンポラリディレクトリ）のパスを取得するためのクロスプラットフォームAPIを提供する。複数の環境変数を優先度順にチェックし、いずれも未設定の場合はOSのデフォルトパスを返す。

**業務上の目的・背景**：一時ファイルの作成先ディレクトリは、OSやユーザー設定によって異なる。Unix系OSではTMPDIR、TMP、TEMP、TEMPDIRの各環境変数が使われ、Windowsではまた異なるAPIを使用する。本機能はこれらの差異を吸収し、一貫したインターフェースで一時ディレクトリを取得できるようにする。

**機能の利用シーン**：一時ファイルの作成先決定、ダウンロードファイルの一時保存先、ビルドシステムの中間ファイル格納場所の決定に利用される。Node.jsの`os.tmpdir()`はこのAPIを基盤としている。

**主要な処理内容**：
1. TMPDIR、TMP、TEMP、TEMPDIRの各環境変数を順にチェックする
2. いずれの環境変数も未設定の場合はデフォルトパスを使用する（通常"/tmp"、Android"/data/local/tmp"）
3. 末尾のスラッシュを除去する
4. バッファにパスをコピーして返却する

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

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 29 | その他ユーティリティ | 主機能 | uv_os_tmpdir()による一時ディレクトリ取得のAPI定義 |

## 機能種別

システム情報取得

## 入力仕様

### 入力パラメータ

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

### 入力データソース

OS環境変数（TMPDIR, TMP, TEMP, TEMPDIR）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | int | 成功時0、エラー時負のエラーコード |
| buffer | char* | 一時ディレクトリのパス（末尾スラッシュなし） |
| *size | size_t | パス文字列の長さ（NULL終端を含まない） |

### 出力先

呼び出し元に直接返却

## 処理フロー

### 処理シーケンス

```
1. 入力バリデーション
   └─ buffer/sizeがNULL、*sizeが0の場合UV_EINVALを返却
2. 環境変数を優先度順にチェック（CHECK_ENV_VARマクロ使用）
   a. TMPDIR
   b. TMP
   c. TEMP
   d. TEMPDIR
3. いずれも未設定の場合
   └─ Android: "/data/local/tmp"
   └─ その他:  "/tmp"
4. 値の長さをチェック
   └─ バッファ不足の場合: *size = len + 1、UV_ENOBUFS返却
5. 末尾スラッシュの除去（長さ > 1 かつ末尾が'/'の場合）
6. memcpy()でバッファにコピーし、NULL終端を設定
7. *size = lenを設定して成功を返却
```

### フローチャート

```mermaid
flowchart TD
    A[uv_os_tmpdir呼び出し] --> B{入力バリデーション}
    B -->|不正| C[UV_EINVAL返却]
    B -->|OK| D[getenv TMPDIR]
    D -->|設定あり| L[return_buffer]
    D -->|未設定| E[getenv TMP]
    E -->|設定あり| L
    E -->|未設定| F[getenv TEMP]
    F -->|設定あり| L
    F -->|未設定| G[getenv TEMPDIR]
    G -->|設定あり| L
    G -->|未設定| H{Android?}
    H -->|Yes| I[buf = /data/local/tmp]
    H -->|No| J[buf = /tmp]
    I --> L
    J --> L
    L --> M{len >= *size?}
    M -->|Yes| N[*size=len+1, UV_ENOBUFS]
    M -->|No| O[末尾スラッシュ除去]
    O --> P[memcpy + NULL終端]
    P --> Q[*size=len, return 0]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 環境変数優先度 | TMPDIR > TMP > TEMP > TEMPDIR の順で確認する | 常時 |
| BR-02 | デフォルトパス | 環境変数が全て未設定の場合"/tmp"を使用（Androidは"/data/local/tmp"） | 全環境変数未設定時 |
| BR-03 | 末尾スラッシュ除去 | パスの長さが1より大きく末尾がスラッシュの場合、除去する | 常時 |

### 計算ロジック

該当なし

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| UV_EINVAL | バリデーションエラー | buffer/sizeがNULL、*size=0 | 有効なパラメータを指定する |
| UV_ENOBUFS | バッファ不足 | バッファサイズが不足 | *sizeの値以上のバッファを確保して再呼び出し |

### リトライ仕様

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

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

該当なし

## パフォーマンス要件

getenv()の呼び出しのみで完了するため極めて高速。

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

- 環境変数TMPDIR等は外部から設定可能であり、信頼性が低い場合がある
- 返却されたパスが実在し、書き込み権限があることを呼び出し側で確認すべき
- 一時ディレクトリへの書き込みにはシンボリックリンク攻撃などのリスクがある

## 備考

- CHECK_ENV_VARマクロを使用して環境変数チェックを簡潔に記述している
- マクロは関数内で定義・使用後即座にundef される
- Androidの場合は`/data/local/tmp`がデフォルト（`__ANDROID__`マクロで分岐）
- `include/uv.h` L1314 で定義

---

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

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

### 推奨読解順序

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

本機能固有のデータ構造は特にない。標準Cの`char*`バッファと`size_t`でやり取りする。

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

#### Step 2: エントリーポイントを理解する

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

**主要処理フロー**:
1. **1305-1306行目**: 入力バリデーション
2. **1308-1314行目**: CHECK_ENV_VARマクロ定義（getenv + gotoパターン）
3. **1317-1320行目**: TMPDIR, TMP, TEMP, TEMPDIRの順でチェック
4. **1325-1329行目**: デフォルトパスの決定（Android分岐あり）
5. **1334-1336行目**: バッファサイズチェック
6. **1340-1342行目**: 末尾スラッシュ除去
7. **1344-1346行目**: memcpyでコピーしNULL終端

**読解のコツ**: CHECK_ENV_VARはローカルマクロで、`getenv(name)`が非NULLの場合に`goto return_buffer`でジャンプする。このパターンにより複数環境変数のフォールバック処理を簡潔に記述している。

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

```
uv_os_tmpdir() [src/unix/core.c:1301]
    |
    +-- getenv("TMPDIR") [POSIX]
    +-- getenv("TMP")    [POSIX]
    +-- getenv("TEMP")   [POSIX]
    +-- getenv("TEMPDIR") [POSIX]
    |
    +-- (いずれも未設定) -> デフォルト "/tmp" or "/data/local/tmp"
    |
    +-- strlen()
    +-- memcpy()
```

### データフロー図

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

buffer (char*)      ───> TMPDIR / TMP / TEMP / TEMPDIR    ───> buffer にパスを格納
size (size_t*)           環境変数を順に確認                      *size にパス長を格納
                         |                                      戻り値 (0 or エラー)
                         +-- 設定あり -> その値を使用
                         |
                         +-- 全未設定 -> "/tmp" をデフォルト
                         |
                         +-- 末尾スラッシュ除去
```

### 関連ファイル一覧

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