# 機能設計書 114-FSリクエスト情報取得

## 概要

本ドキュメントは、libuvのFSリクエスト結果情報取得機能群の設計仕様を記述する。`uv_fs_get_type()` / `uv_fs_get_result()` / `uv_fs_get_system_error()` / `uv_fs_get_ptr()` / `uv_fs_get_path()` / `uv_fs_get_statbuf()` の6つのアクセサ関数について定義する。

### 本機能の処理概要

FSリクエスト情報取得関数群は、完了したuv_fs_tリクエストから結果情報を安全に取り出すためのアクセサ（getter）関数群である。リクエスト構造体の内部フィールドに直接アクセスする代わりに、これらの関数を使用することでAPI互換性を保ちながらリクエスト結果を取得できる。

**業務上の目的・背景**：uv_fs_t構造体の内部レイアウトはプラットフォームやバージョンによって異なる可能性がある。アクセサ関数を使用することで、構造体の内部変更に影響されない安定したAPIを提供し、アプリケーションの移植性・互換性を向上させる。

**機能の利用シーン**：uv_fs_*操作のコールバック関数内で、操作の種別・結果・エラー情報・データポインタ・パス・stat情報を取得する際に使用される。

**主要な処理内容**：
1. uv_fs_get_type(): リクエストのFS操作種別（uv_fs_type）を返す
2. uv_fs_get_result(): 操作結果（バイト数やFD番号）を返す
3. uv_fs_get_system_error(): システムエラーコードを返す（resultの符号反転）
4. uv_fs_get_ptr(): 結果データポインタを返す
5. uv_fs_get_path(): 操作対象パスを返す
6. uv_fs_get_statbuf(): stat結果バッファへのポインタを返す

**関連システム・外部連携**：特になし。libuvの内部構造体へのアクセスを抽象化する。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 24 | ファイルシステム操作 | 主機能 | uv_fs_get_type()/result()/system_error()/ptr()/path()/statbuf()のAPI定義 |

## 機能種別

データ取得処理（アクセサ関数群）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| req | const uv_fs_t* / uv_fs_t* | Yes | ファイルシステムリクエスト | NULLでないこと |

### 入力データソース

ユーザーが以前に実行し完了したuv_fs_*操作のリクエスト構造体。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| uv_fs_get_type() | uv_fs_type | FS操作種別（UV_FS_OPEN, UV_FS_READ等） |
| uv_fs_get_result() | ssize_t | 操作結果（成功時はバイト数やFD、エラー時は負のエラーコード） |
| uv_fs_get_system_error() | int | POSIXシステムエラーコード（正の値） |
| uv_fs_get_ptr() | void* | 操作結果データへのポインタ（READLINK時のパス文字列等） |
| uv_fs_get_path() | const char* | 操作対象ファイルパス |
| uv_fs_get_statbuf() | uv_stat_t* | stat結果バッファへのポインタ |

### 出力先

関数の戻り値として直接返却。

## 処理フロー

### 処理シーケンス

```
各getter関数は単純なフィールドアクセスを行う:
1. uv_fs_get_type(req)     → return req->fs_type
2. uv_fs_get_result(req)   → return req->result
3. uv_fs_get_system_error(req) → return -req->result（符号反転）
4. uv_fs_get_ptr(req)      → return req->ptr
5. uv_fs_get_path(req)     → return req->path
6. uv_fs_get_statbuf(req)  → return &req->statbuf
```

### フローチャート

```mermaid
flowchart TD
    A[getter関数呼び出し] --> B{関数種別}
    B -->|get_type| C[return req->fs_type]
    B -->|get_result| D[return req->result]
    B -->|get_system_error| E[return -req->result]
    B -->|get_ptr| F[return req->ptr]
    B -->|get_path| G[return req->path]
    B -->|get_statbuf| H[return &req->statbuf]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-114-1 | 符号反転変換 | get_system_errorは内部エラーコード（負値）を正の値のPOSIXエラーに変換する | get_system_error呼び出し時 |
| BR-114-2 | statbufアドレス返却 | get_statbufはコピーではなく構造体メンバのアドレスを直接返す | get_statbuf呼び出し時 |
| BR-114-3 | 操作完了前提 | これらの関数はuv_fs_*操作完了後にのみ有効な値を返す | コールバック内 |

### 計算ロジック

`uv_fs_get_system_error()` は `-req->result` を返す。libuvの内部エラーコードは負の値で表現されるため、符号を反転することでPOSIXの正のエラーコードに変換する。

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

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

該当なし。

## エラー処理

### エラーケース一覧

特にエラー処理は行わない。NULLポインタが渡された場合の動作は未定義。

### リトライ仕様

該当なし。

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

該当なし。

## パフォーマンス要件

- すべてインライン可能な単純フィールドアクセスであり、オーバーヘッドはほぼゼロ

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

- 特になし。読み取り専用のアクセサ関数。

## 備考

- get_system_errorの実装はUnix（src/unix/fs.c L2303）とWindows（src/win/fs.c L3809）で異なる
- Unix版は`-req->result`、Windows版はシステム固有のエラーコードを返す可能性がある
- その他のgetter関数はsrc/uv-data-getter-setters.cに統一的に実装されている

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | **L1449-1460**: uv_fs_s構造体定義。fs_type, result, ptr, path, statbufフィールド |
| 1-2 | uv.h | `include/uv.h` | **L1462-1467**: 6つのgetter関数のAPI宣言 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | uv-data-getter-setters.c | `src/uv-data-getter-setters.c` | **L93-111**: get_type/get_result/get_ptr/get_path/get_statbufの実装 |
| 2-2 | fs.c (Unix) | `src/unix/fs.c` | **L2303-2305**: get_system_error()のUnix実装（-req->result） |

**主要処理フロー**:
- **L93-95**: uv_fs_get_type: return req->fs_type
- **L97-99**: uv_fs_get_result: return req->result
- **L101-103**: uv_fs_get_ptr: return req->ptr
- **L105-107**: uv_fs_get_path: return req->path
- **L109-111**: uv_fs_get_statbuf: return &req->statbuf
- **L2303-2305**: uv_fs_get_system_error: return -req->result

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

```
uv_fs_get_type(req)          [src/uv-data-getter-setters.c L93]  → req->fs_type
uv_fs_get_result(req)        [src/uv-data-getter-setters.c L97]  → req->result
uv_fs_get_system_error(req)  [src/unix/fs.c L2303]               → -req->result
uv_fs_get_ptr(req)           [src/uv-data-getter-setters.c L101] → req->ptr
uv_fs_get_path(req)          [src/uv-data-getter-setters.c L105] → req->path
uv_fs_get_statbuf(req)       [src/uv-data-getter-setters.c L109] → &req->statbuf
```

### データフロー図

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

uv_fs_t* req  ──> フィールドアクセス   ──> 各フィールド値
  .fs_type    ──> get_type()           ──> uv_fs_type
  .result     ──> get_result()         ──> ssize_t
  .result     ──> get_system_error()   ──> int (符号反転)
  .ptr        ──> get_ptr()            ──> void*
  .path       ──> get_path()           ──> const char*
  .statbuf    ──> get_statbuf()        ──> uv_stat_t*
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダー | 6つのgetter関数のAPI宣言 |
| uv-data-getter-setters.c | `src/uv-data-getter-setters.c` | ソース | 5つのgetter関数の共通実装 |
| fs.c (Unix) | `src/unix/fs.c` | ソース | get_system_error()のUnix実装 |
| fs.c (Win) | `src/win/fs.c` | ソース | get_system_error()のWindows実装 |
