# 帳票設計書 19-エラー名称文字列

## 概要

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

### 本帳票の処理概要

uv_err_name() および uv_err_name_r() APIは、libuvエラーコード（負の整数値）に対応するエラー名称（UV_ENOENT、UV_EACCES等のシンボル名）を文字列として返却する関数である。

**業務上の目的・背景**：エラーハンドリングにおいて、エラーコードの数値だけでなく、その名称（シンボル名）を文字列として取得できることは、ログ出力やデバッグにおいて有用である。Node.jsではSystemErrorオブジェクトのcodeプロパティ（"ENOENT"等）としてこのAPIの値が利用される。uv_strerror()が人間可読なメッセージを返すのに対し、本APIはプログラム的に識別可能な名称を返す。

**帳票の利用シーン**：エラーログへのシンボル名出力、Node.jsのSystemError.codeプロパティ生成、エラー種別の文字列比較、デバッグ情報の出力。

**主要な出力内容**：
1. エラー名称文字列（const char*型、例："ENOENT"、"EACCES"）

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

**帳票の利用者**：libuvを利用するアプリケーション開発者、Node.jsランタイム内部、デバッグツール開発者

## 帳票種別

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

## 利用画面

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

## 出力形式

### 基本仕様

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

## 帳票レイアウト

### レイアウト概要

```
┌─────────────────────────────────────┐
│  エラー名称文字列                     │
│  例: "ENOENT"                       │
│  例: "EACCES"                       │
│  例: "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 | "ENOENT" |
| UV_EACCES | "EACCES" |
| UV_EINVAL | "EINVAL" |
| UV_ENOMEM | "ENOMEM" |
| UV_EBUSY | "EBUSY" |
| UV_EAGAIN | "EAGAIN" |
| UV_ECONNREFUSED | "ECONNREFUSED" |
| UV_ETIMEDOUT | "ETIMEDOUT" |
| UV_EOF | "EOF" |
| UV_UNKNOWN | "UNKNOWN" |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| N/A | switchによる定数文字列マッピング | N/A | #nameプリプロセッサ文字列化を使用 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[uv_err_name / uv_err_name_r 呼び出し] --> B{UV_ERRNO_MAPに該当?}
    B -->|Yes uv_err_name| C[#nameで文字列化した定数を返却]
    B -->|Yes uv_err_name_r| D[uv__strscpyでbufにコピー]
    B -->|No uv_err_name| E[uv__unknown_err_code 呼び出し]
    E --> F[snprintfで"Unknown system error %d"を生成]
    F --> G[uv__strdupでコピーして返却]
    B -->|No uv_err_name_r| H[snprintfでbufに"Unknown system error %d"を書込]
    D --> I[bufを返却]
    H --> I
```

## エラー処理

### エラーケース一覧

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

## パフォーマンス要件

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

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

uv_strerror()と同様に、uv_err_name()は未知エラーコード時に動的メモリ確保を行う。uv_err_name_r()はユーザー提供バッファに書き込むため安全である。

## 備考

- uv_err_name()はUV_ERR_NAME_GENマクロで #name を使い、プリプロセッサの文字列化機能でエラー名称を生成する。
- uv_err_name_r()はUV_ERR_NAME_GEN_Rマクロで uv__strscpy を使い、バッファに名称をコピーする。
- uv_strerror()との違い：uv_err_name()はシンボル名（"ENOENT"）を返し、uv_strerror()は説明文（"no such file or directory"）を返す。
- 未知エラーコードに対するuv_err_name()の動的メモリ確保はuv_strerror()と同じuv__unknown_err_code()を使用する。

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | 74-160行目: UV_ERRNO_MAPマクロ。XX(name, msg)形式。nameがエラー名称の元となる |

**読解のコツ**: #name はCプリプロセッサの文字列化演算子。UV_ERR_NAME_GENマクロ内で #name とすることで、ENOENTのようなシンボルが"ENOENT"文字列に変換される。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | uv.h | `include/uv.h` | 428-429行目: uv_err_name()とuv_err_name_r()の宣言 |
| 2-2 | uv-common.c | `src/uv-common.c` | 222行目: uv_err_name()実装。#nameで文字列化 |
| 2-3 | uv-common.c | `src/uv-common.c` | 211行目: uv_err_name_r()実装。uv__strscpyでバッファにコピー |

**主要処理フロー（uv_err_name）**:
1. **221行目**: UV_ERR_NAME_GENマクロ定義: case UV_name: return #name;
2. **222行目**: uv_err_name関数開始。switch(err)
3. **224行目**: UV_ERRNO_MAP(UV_ERR_NAME_GEN)でswitchのcase群を展開
4. **226行目**: マッチしない場合はuv__unknown_err_code(err)を呼び出し

**主要処理フロー（uv_err_name_r）**:
1. **208行目**: UV_ERR_NAME_GEN_Rマクロ定義: case UV_name: uv__strscpy(buf, #name, buflen); break;
2. **211行目**: uv_err_name_r関数開始。switch(err)
3. **213行目**: UV_ERRNO_MAP(UV_ERR_NAME_GEN_R)でswitchのcase群を展開
4. **214行目**: マッチしない場合はsnprintfで"Unknown system error %d"を書き込み

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

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

uv_err_name_r(err, buf, buflen)
    │
    ├─ (既知エラー) uv__strscpy(buf, #name, buflen)
    │
    └─ (未知エラー) snprintf(buf, buflen, "Unknown system error %d", err)
```

### データフロー図

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

int err      ───▶  switch(err) {                ───▶  const char* / char*
                     UV_ERRNO_MAP展開              (エラー名称文字列)
                     ├─ 既知: #name 文字列化
                     └─ 未知: 動的生成
                   }
```

### 関連ファイル一覧

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