# 画面設計書 4-エラーコード

## 概要

libuvのエラーコード定義と関連API関数のリファレンスページ（errors.rst）に関する画面設計書。エラーコード定数の一覧と、エラーメッセージ取得・エラー名取得・システムエラー変換のAPI定義を提供する。

### 本画面の処理概要

本画面はlibuvのエラーハンドリング機構を解説するAPIリファレンスページである。全てのlibuvエラーコード定数を一覧し、エラー情報を取得するための関数群を定義する。

**業務上の目的・背景**：libuvのAPI関数は失敗時に負の整数値をエラーコードとして返す。開発者がエラーの原因を特定し適切に対処するために、各エラーコードの意味とエラー情報取得APIの使い方を理解する必要がある。Unixではerrnoの符号反転値、Windowsではlibuv独自の負数が使用されるため、プラットフォーム間の差異を吸収する変換APIも提供される。

**画面へのアクセス方法**：APIドキュメント一覧ページ（api.rst）の "Error handling" リンク押下、または `/errors.html` に直接アクセスする。

**主要な操作・処理内容**：
1. エラーコード定数の参照 - UV_E2BIG, UV_EACCES等の全エラーコードとその説明の確認
2. UV_ERRNO_MAPマクロの参照 - 全エラーコードを列挙するイテレーションマクロの使い方
3. uv_strerror()/uv_strerror_r()の参照 - エラーコードからエラーメッセージ文字列への変換
4. uv_err_name()/uv_err_name_r()の参照 - エラーコードからエラー名文字列への変換
5. uv_translate_sys_error()の参照 - プラットフォーム依存エラーコードからlibuvエラーコードへの変換

**画面遷移**：
- 遷移元：APIドキュメント一覧（api.rst）
- 遷移先：なし（末端リファレンスページ）

**権限による表示制御**：なし。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 177 | エラーメッセージ取得 | 主機能 | uv_strerror()/uv_strerror_r()によるエラーコードから説明文字列の取得API定義 |
| 178 | エラー名取得 | 主機能 | uv_err_name()/uv_err_name_r()によるエラーコードから名前文字列の取得API定義 |
| 179 | システムエラー変換 | 主機能 | uv_translate_sys_error()によるシステムエラーコード変換のAPI定義 |

## 画面種別

APIリファレンスページ（エラーハンドリング）

## URL/ルーティング

- ソースファイル: `docs/src/errors.rst`
- 生成先URL: `/errors.html`
- Sphinxアンカー: `.. _errors:`

## 入出力項目

| 項目名 | 入出力 | 型 | 説明 |
|--------|--------|-----|------|
| ページタイトル | 出力 | テキスト | "Error handling" |
| エラーコード一覧 | 出力 | 定義リスト | 全エラーコード定数とその説明 |
| API関数定義 | 出力 | 関数シグネチャ+説明 | 6つのAPI関数定義 |

## 表示項目

### Error constants セクション

主要なエラーコード定数（全56件）を表示する。以下は代表的なもの：

| エラーコード | 説明 |
|-------------|------|
| UV_E2BIG | argument list too long |
| UV_EACCES | permission denied |
| UV_EADDRINUSE | address already in use |
| UV_EAGAIN | resource temporarily unavailable |
| UV_ECONNREFUSED | connection refused |
| UV_ECONNRESET | connection reset by peer |
| UV_EINVAL | invalid argument |
| UV_ENOMEM | not enough memory |
| UV_ENOENT | no such file or directory |
| UV_ETIMEDOUT | connection timed out |
| UV_EOF | end of file |
| UV_UNKNOWN | unknown error |

### API セクション

| API関数 | シグネチャ | 説明 |
|---------|-----------|------|
| UV_ERRNO_MAP | `UV_ERRNO_MAP(iter_macro)` | 全エラーコードに対してiter_macroを展開するマクロ |
| uv_strerror | `const char* uv_strerror(int err)` | エラーコードからメッセージ文字列を返却。未知コードではメモリリークあり |
| uv_strerror_r | `char* uv_strerror_r(int err, char* buf, size_t buflen)` | エラーメッセージをユーザーバッファに書き込み（v1.22.0追加） |
| uv_err_name | `const char* uv_err_name(int err)` | エラーコードからエラー名文字列を返却。未知コードではメモリリークあり |
| uv_err_name_r | `char* uv_err_name_r(int err, char* buf, size_t buflen)` | エラー名をユーザーバッファに書き込み（v1.22.0追加） |
| uv_translate_sys_error | `int uv_translate_sys_error(int sys_errno)` | プラットフォーム依存エラーをlibuvエラーに変換（v1.10.0で公開） |

## イベント仕様

### 1-Sphinx相互参照リンク押下

API関数説明内の型参照リンク押下で、対応するAPIリファレンスページへ遷移する。

## データベース更新仕様

### 操作別データベース影響一覧

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| N/A | N/A | N/A | データベースアクセスなし |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|--------------|----------|
| N/A | N/A | N/A | 静的HTMLのため動的メッセージなし |

## 例外処理

本画面は静的リファレンスドキュメントのため、画面固有の例外処理は存在しない。

## 備考

- Unixではエラーコードはerrnoの符号反転値（-errno）として定義される
- WindowsではlibuvがABI安定のために独自の負数を定義する
- `uv_strerror()` と `uv_err_name()` は未知のエラーコードに対してメモリリークが発生する。高頻度呼び出しには `_r` サフィックス版を使用すべき
- UV_ERRNO_MAPマクロはuv.hのヘッダ内で定義され、全エラーコードのswitch-case生成等に活用される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | errno.h | `include/uv/errno.h` | UV__ERR マクロ（27-29行目）。Unixでは `-(x)`、条件付きで `(x)` |
| 1-2 | uv.h | `include/uv.h` | UV_ERRNO_MAP マクロ（74行目以降）。全エラーコードの定義リスト |

**読解のコツ**: UV_ERRNO_MAPは `XX(name, msg)` 形式のXマクロパターンを使用している。このマクロを展開する側で `XX` を定義することで、switch-caseの自動生成やエラー名テーブルの生成等に活用される。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | uv-common.c | `src/uv-common.c` | uv_strerror(), uv_err_name() 等のエラーAPI関数実装（198-251行目） |

**主要処理フロー**:
1. **uv-common.c 198行目**: `uv__unknown_err_code()` - 未知エラーコードのメッセージ生成（メモリリーク源）
2. **uv-common.c 211行目**: `uv_err_name_r()` - UV_ERRNO_MAPを展開したswitch-caseでバッファにコピー
3. **uv-common.c 222行目**: `uv_err_name()` - UV_ERRNO_MAPを展開したswitch-caseで静的文字列を返却
4. **uv-common.c 234行目**: `uv_strerror_r()` - UV_ERRNO_MAPを展開したswitch-caseでバッファにコピー
5. **uv-common.c 245行目**: `uv_strerror()` - UV_ERRNO_MAPを展開したswitch-caseで静的文字列を返却

#### Step 3: プラットフォーム固有の実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | errno.h | `include/uv/errno.h` | プラットフォーム条件分岐によるエラーコード値の定義 |

**主要処理フロー**:
- **errno.h 26-29行目**: `EDOM > 0` の条件で `UV__ERR(x)` が `-(x)` または `(x)` として定義

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

```
uv_strerror(err) [src/uv-common.c:245]
    |
    +-- UV_ERRNO_MAP(UV_STRERROR_GEN) でswitch-case展開
    |       +-- case UV_E2BIG: return "argument list too long"
    |       +-- case UV_EACCES: return "permission denied"
    |       +-- ...
    |
    +-- uv__unknown_err_code(err) [uv-common.c:198]
            +-- snprintf() + uv__strdup() (メモリリーク)

uv_err_name(err) [src/uv-common.c:222]
    |
    +-- UV_ERRNO_MAP(UV_ERR_NAME_GEN) でswitch-case展開
    |       +-- case UV_E2BIG: return "E2BIG"
    |       +-- ...
    |
    +-- uv__unknown_err_code(err)
```

### データフロー図

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

int err         -->  uv_strerror(err)          -->  const char* メッセージ文字列
(負の整数)           UV_ERRNO_MAP展開               "permission denied" 等

int err         -->  uv_err_name(err)          -->  const char* エラー名文字列
(負の整数)           UV_ERRNO_MAP展開               "EACCES" 等

int sys_errno   -->  uv_translate_sys_error()  -->  int libuvエラーコード
(POSIX errno        プラットフォーム変換             UV_EACCES 等
 or Win32 error)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| errors.rst | `docs/src/errors.rst` | テンプレート | エラーコードページのRSTソース |
| errno.h | `include/uv/errno.h` | ソース | エラーコードマクロ定義ヘッダ |
| uv.h | `include/uv.h` | ソース | UV_ERRNO_MAPマクロ定義（74行目以降） |
| uv-common.c | `src/uv-common.c` | ソース | uv_strerror(), uv_err_name() 等の実装 |
| error.c | `src/win/error.c` | ソース | Windows固有のエラー変換実装 |
