# 機能設計書 179-システムエラー変換

## 概要

本ドキュメントは、libuv の `uv_translate_sys_error()` 関数によるシステムエラーコードからlibuvエラーコードへの変換機能について、その設計仕様を記載する。

### 本機能の処理概要

`uv_translate_sys_error()` は、OSネイティブのシステムエラーコード（errno値やWindows エラーコード）をlibuvの統一エラーコード（UV_EACCES等）に変換する関数である。

**業務上の目的・背景**：libuvはクロスプラットフォームライブラリであり、各OSのシステムエラーコードは異なる体系を持つ。Unix系ではPOSIX errno（EACCES=13等）、Windowsでは独自のエラーコード体系（ERROR_ACCESS_DENIED, WSAEACCES等）が使用される。本機能はこれらのプラットフォーム固有エラーコードを、libuvが定義する統一的なエラーコード体系に変換し、アプリケーションがプラットフォームを意識せずにエラー処理を行えるようにする。

**機能の利用シーン**：OS APIの戻り値をlibuvエラーコードに変換する内部処理、カスタムI/O処理でのエラーコード統一、プラットフォーム固有コードとlibuvの橋渡し、エラーハンドリングの統一化などに利用される。

**主要な処理内容**：
1. 入力値が既にlibuvエラーコード（0以下）かどうかの判定
2. プラットフォーム固有のエラーコードマッピング
3. Unix: 正のerrno値を負のlibuvエラーコードに変換
4. Windows: WSA*エラーやERROR_*エラーをlibuvエラーコードに変換

**関連システム・外部連携**：プラットフォーム固有のシステムエラーコード体系。

**権限による制御**：特別な権限は不要である。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 4 | エラーコード | 主機能 | uv_translate_sys_error()によるシステムエラーコード変換のAPI定義 |
| 29 | その他ユーティリティ | 補助機能 | uv_translate_sys_error()によるシステムエラーコード変換のAPI定義 |

## 機能種別

データ変換処理（プラットフォーム固有エラーコードからlibuvエラーコードへの変換）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| sys_errno | int | Yes | プラットフォーム固有のシステムエラーコード | 特に制限なし |

### 入力データソース

OS APIの戻り値、errno変数、WSAGetLastError()等から取得されるシステムエラーコード。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | int | libuvエラーコード（負の整数）。入力が0以下なら入力値をそのまま返す |

### 出力先

呼び出し元に戻り値として返却。

## 処理フロー

### 処理シーケンス

```
1. 入力値の事前チェック
   └─ sys_errno <= 0 ならそのまま返す（既にlibuvエラーコードか成功値）
2. プラットフォーム固有の変換
   └─ Unix: -sys_errno を返す（正のerrnoを負に変換）
   └─ Windows: switch文による詳細なマッピング
3. [Windows] 不明なエラーコードの場合
   └─ UV_UNKNOWN を返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{sys_errno <= 0?}
    B -->|Yes| C[sys_errno をそのまま返す]
    B -->|No| D{プラットフォーム}
    D -->|Unix| E[-sys_errno を返す]
    D -->|Windows| F{switch で既知エラー?}
    F -->|Yes| G[対応する UV_E* を返す]
    F -->|No| H[UV_UNKNOWN を返す]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-179-01 | 0以下の値はパススルー | 入力値が0以下の場合はそのまま返す（既にlibuvエラーコードまたは成功値） | 常時 |
| BR-179-02 | Unix変換 | 正のerrno値は単純に符号反転（-sys_errno）してlibuvエラーコードに変換 | Unix系 |
| BR-179-03 | Windows変換 | WSA*エラーやERROR_*エラーを約80のcase文でlibuvエラーコードにマッピング | Windows |
| BR-179-04 | 不明エラー | Windowsで対応するマッピングがないエラーは UV_UNKNOWN を返す | Windows |

### 計算ロジック

Unix版: `return sys_errno <= 0 ? sys_errno : -sys_errno;`

Windows版: 大規模なswitch文により、約80のWindowsエラーコードを対応するlibuvエラーコードにマッピングする。例:
- `WSAEACCES` / `ERROR_ELEVATION_REQUIRED` / `ERROR_CANT_ACCESS_FILE` -> `UV_EACCES`
- `WSAECONNREFUSED` / `ERROR_CONNECTION_REFUSED` -> `UV_ECONNREFUSED`
- `ERROR_FILE_NOT_FOUND` / `ERROR_PATH_NOT_FOUND` -> `UV_ENOENT`

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

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

該当なし。

### テーブル別操作詳細

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| UV_UNKNOWN | 不明エラー | Windowsでマッピングのないエラーコード | アプリケーション側でsys_errnoの値を確認する |

### リトライ仕様

不要。

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

該当なし。

## パフォーマンス要件

Unix版は1行の計算式、Windows版はswitch文（約80ケース）。いずれも極めて軽量。

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

特別なセキュリティ要件はない。

## 備考

- Unix版の実装は非常にシンプルで、libuvのエラーコードがシステムのerrnoを負の値にしたものと一致する設計に依存している。
- Windows版は多数のWindowsエラーコード（WSA*系、ERROR_*系）をカバーしており、同じlibuvエラーコードに複数のWindowsエラーコードがマッピングされる場合がある。
- `uv_translate_write_sys_error()` という関連関数（src/win/error.c L176-183）はパイプの書き込みエラーに特化した変換を提供する。
- libuv内部では `UV__ERR(errno)` マクロが頻繁に使用されるが、これは実質的に `-errno` と同等の変換を行う。

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | UV_ERRNO_MAP マクロ（74-159行目）。libuvが定義する全エラーコードの一覧 |
| 1-2 | uv.h | `include/uv.h` | エラーコード列挙体（191-194行目）。UV_ERRNO_MAP から UV_ プレフィックス付きの列挙値を生成 |

**読解のコツ**: libuvのエラーコードは全て負の整数値。`UV__ ## code` で定義される内部定数を `UV_ ## code` にマッピングする仕組みが取られている。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | uv.h | `include/uv.h` | API宣言（423行目）: `int uv_translate_sys_error(int sys_errno)` |

#### Step 3: Unix実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | core.c | `src/unix/core.c` | Unix版の `uv_translate_sys_error()` 実装（1518-1521行目） |

**主要処理フロー**:
- **1519行目**: コメント: 0以下なら既にlibuvエラーコード
- **1520行目**: `return sys_errno <= 0 ? sys_errno : -sys_errno;` の1行実装

#### Step 4: Windows実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | error.c | `src/win/error.c` | Windows版の `uv_translate_sys_error()` 実装（66-174行目） |

**主要処理フロー**:
- **67-69行目**: sys_errno <= 0 の事前チェック。0以下ならそのまま返す
- **71-173行目**: 大規模なswitch文。約80のWindowsエラーコードをlibuvエラーコードにマッピング
- **172行目**: default ケースで UV_UNKNOWN を返す

#### Step 5: 関連関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | error.c | `src/win/error.c` | `uv_translate_write_sys_error()` 実装（176-183行目）。パイプ書き込みエラーの特殊変換 |

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

```
uv_translate_sys_error(sys_errno)
    |
    +-- [Unix]
    |   +-- sys_errno <= 0 ? sys_errno : -sys_errno
    |
    +-- [Windows]
        +-- [sys_errno <= 0] return sys_errno
        +-- [sys_errno > 0] switch(sys_errno)
            +-- WSAEACCES -> UV_EACCES
            +-- WSAECONNREFUSED -> UV_ECONNREFUSED
            +-- ERROR_FILE_NOT_FOUND -> UV_ENOENT
            +-- ... (約80のマッピング)
            +-- default -> UV_UNKNOWN
```

### データフロー図

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

sys_errno ────▶ uv_translate_sys_error() ──────▶ int
(OS固有エラー)      |                              (libuvエラーコード)
                    +-- 0以下チェック
                    +-- [Unix] 符号反転
                    +-- [Windows] switch マッピング
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダー | API宣言、UV_ERRNO_MAP マクロ |
| core.c | `src/unix/core.c` | ソース | Unix版の uv_translate_sys_error() 実装 |
| error.c | `src/win/error.c` | ソース | Windows版の uv_translate_sys_error() 実装 |
