# 帳票設計書 18-エラーメッセージ文字列

## 概要

本ドキュメントは、libuvライブラリが提供するエラーメッセージ文字列取得機能（uv_strerror / uv_strerror_r）の帳票設計書である。

### 本帳票の処理概要

uv_strerror() および uv_strerror_r() APIは、libuvエラーコード（負の整数値）に対応する人間可読なエラーメッセージ文字列を返却する関数である。

**業務上の目的・背景**：libuvのAPIは失敗時に負の整数値（UV_ENOENTやUV_EACCES等）を返す。これらの数値だけではエラーの内容が分かりにくいため、開発者やエンドユーザーに向けた可読なメッセージに変換する必要がある。本APIはエラーコードから"no such file or directory"や"permission denied"といった説明文字列への変換を提供する。

**帳票の利用シーン**：エラーログへの出力、ユーザー向けエラーメッセージの生成、デバッグ時のエラー内容確認、例外メッセージの構築（Node.jsのSystemErrorメッセージ等）。

**主要な出力内容**：
1. エラーメッセージ文字列（const char*型）

**帳票の出力タイミング**：エラーコードを引数にuv_strerror()を呼び出した時点で即座に文字列ポインタを返却する。同期的に動作する。

**帳票の利用者**：libuvを利用するアプリケーション開発者、Node.jsランタイム内部、エラーハンドリングフレームワーク

## 帳票種別

文字列レポート（定数文字列返却型）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| N/A | C API呼び出し | N/A | uv_strerror(err) / uv_strerror_r(err, buf, buflen) 関数呼び出し |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | 文字列（const char* / char*） |
| 用紙サイズ | N/A |
| 向き | N/A |
| ファイル名 | N/A（関数戻り値） |
| 出力方法 | 関数戻り値（uv_strerror）/ バッファ書き込み（uv_strerror_r） |
| 文字コード | ASCII |

## 帳票レイアウト

### レイアウト概要

```
┌─────────────────────────────────────┐
│  エラーメッセージ文字列               │
│  例: "no such file or directory"    │
│  例: "permission denied"            │
│  例: "Unknown system error -4094"   │
└─────────────────────────────────────┘
```

### ヘッダー部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| N/A | N/A | ヘッダー部は存在しない | N/A | N/A |

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 | 列幅 |
|----|-------|------|-------------|---------|-----|
| 1 | エラーメッセージ | エラーコードに対応する説明文 | UV_ERRNO_MAPマクロ定義 | NUL終端文字列 | 可変長 |

### フッター部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| N/A | N/A | フッター部は存在しない | N/A | N/A |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| err | libuvエラーコード（負の整数値） | Yes |
| buf（_r版のみ） | 出力先バッファ | Yes（_r版） |
| buflen（_r版のみ） | バッファサイズ | Yes（_r版） |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| N/A | N/A | N/A |

### 改ページ条件

改ページは発生しない。

## データベース参照仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| UV_ERRNO_MAP | エラーコードとメッセージのマッピング | エラーコードでswitch分岐 |

### テーブル別参照項目詳細

#### UV_ERRNO_MAPマクロ（主要なエラーメッセージ）

| エラーコード | メッセージ |
|------------|---------|
| UV_ENOENT | "no such file or directory" |
| UV_EACCES | "permission denied" |
| UV_EINVAL | "invalid argument" |
| UV_ENOMEM | "not enough memory" |
| UV_EBUSY | "resource busy or locked" |
| UV_EAGAIN | "resource temporarily unavailable" |
| UV_ECONNREFUSED | "connection refused" |
| UV_ETIMEDOUT | "connection timed out" |
| UV_EOF | "end of file" |
| UV_UNKNOWN | "unknown error" |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| N/A | switchによる定数文字列マッピング | N/A | 計算は行わない |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[uv_strerror / uv_strerror_r 呼び出し] --> B{UV_ERRNO_MAPに該当?}
    B -->|Yes| C[対応するメッセージ文字列を返却]
    B -->|No| D{uv_strerror?}
    D -->|uv_strerror| E[uv__unknown_err_code 呼び出し]
    E --> F[snprintfで"Unknown system error %d"を生成]
    F --> G[uv__strdupでコピー]
    G --> H[コピーされた文字列を返却]
    D -->|uv_strerror_r| I[snprintfでbufに"Unknown system error %d"を書込]
    I --> J[bufを返却]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| 未知のエラーコード | UV_ERRNO_MAPに定義されていないエラーコード | "Unknown system error %d" | 動的に文字列を生成して返却 |
| メモリ確保失敗（uv_strerror） | uv__strdupが失敗した場合 | "Unknown system error" | フォールバック文字列を返却 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 1件（単一文字列） |
| 目標出力時間 | ナノ秒〜マイクロ秒オーダー |
| 同時出力数上限 | 制限なし（既知エラーはスレッドセーフ） |

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

uv_strerror()は内部でuv__strdupによるメモリ確保を行う場合がある（未知エラーコード時）。この場合、返却されたメモリはlibuvが管理する静的でないメモリとなるため、理論上メモリリークの可能性がある。uv_strerror_r()はユーザー提供バッファに書き込むため、この問題は発生しない。

## 備考

- uv_strerror()は未知エラーコードに対してuv__strdupで動的メモリを確保する。返却された文字列は呼び出し側で解放できないため、繰り返し呼び出すとメモリリークの原因となる。スレッドセーフでない場合もある。
- uv_strerror_r()はユーザー提供のバッファに書き込むため、スレッドセーフかつメモリリークの心配がない。推奨される使用方法である。
- エラーメッセージはUV_ERRNO_MAPマクロで一元管理されている（include/uv.h 74-160行目）。

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | 74-160行目: UV_ERRNO_MAPマクロ。全エラーコードとメッセージの定義 |

**読解のコツ**: UV_ERRNO_MAPは XX(name, msg) 形式のXマクロパターン。各展開先でnameとmsgが異なる用途に使われる。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | uv.h | `include/uv.h` | 425-426行目: uv_strerror()とuv_strerror_r()の宣言 |
| 2-2 | uv-common.c | `src/uv-common.c` | 245行目: uv_strerror()実装。switch文でUV_ERRNO_MAPを展開 |
| 2-3 | uv-common.c | `src/uv-common.c` | 234行目: uv_strerror_r()実装。バッファにsnprintfで書き込み |

**主要処理フロー（uv_strerror）**:
1. **244行目**: UV_STRERROR_GENマクロ定義: case UV_name: return msg;
2. **245行目**: uv_strerror関数開始。switch(err)
3. **247行目**: UV_ERRNO_MAP(UV_STRERROR_GEN)でswitchのcase群を展開
4. **249行目**: マッチしない場合はuv__unknown_err_code(err)を呼び出し

**主要処理フロー（uv_strerror_r）**:
1. **231行目**: UV_STRERROR_GEN_Rマクロ定義: case UV_name: snprintf(buf, buflen, "%s", msg); break;
2. **234行目**: uv_strerror_r関数開始。switch(err)
3. **236行目**: UV_ERRNO_MAP(UV_STRERROR_GEN_R)でswitchのcase群を展開
4. **237行目**: マッチしない場合はsnprintfで"Unknown system error %d"を書き込み

#### Step 3: 未知エラー処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | uv-common.c | `src/uv-common.c` | 198行目: uv__unknown_err_code関数。snprintfで文字列生成後uv__strdupでコピー |

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

```
uv_strerror(err)
    │
    ├─ (既知エラー) UV_ERRNO_MAP展開 → 定数文字列返却
    │
    └─ (未知エラー) uv__unknown_err_code(err)
           ├─ snprintf(buf, "Unknown system error %d", err)
           └─ uv__strdup(buf)

uv_strerror_r(err, buf, buflen)
    │
    ├─ (既知エラー) snprintf(buf, buflen, "%s", msg)
    │
    └─ (未知エラー) snprintf(buf, buflen, "Unknown system error %d", err)
```

### データフロー図

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

int err      ───▶  switch(err) {                ───▶  const char* / char*
                     UV_ERRNO_MAP展開              (エラーメッセージ文字列)
                     ├─ 既知: 定数文字列
                     └─ 未知: 動的生成
                   }
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダー | UV_ERRNO_MAP定義（74行目）、API宣言（425行目） |
| uv-common.c | `src/uv-common.c` | ソース | uv_strerror（245行目）、uv_strerror_r（234行目）、uv__unknown_err_code（198行目） |
