# 機能設計書 65-パイプ既存FDオープン

## 概要

本ドキュメントは、既存のファイルディスクリプタまたはHANDLEをパイプハンドルに関連付ける機能（`uv_pipe_open()`）の設計仕様を記述する。

### 本機能の処理概要

既存のOSレベルファイルディスクリプタ（Unix）またはHANDLE（Windows）を、初期化済みの`uv_pipe_t`ハンドルに関連付けてlibuvの管理下に置く。

**業務上の目的・背景**：子プロセスの標準入出力リダイレクト、継承FDの活用、外部で作成されたパイプの統合のために、既存FDをlibuvイベントループで管理する需要がある。

**機能の利用シーン**：`uv_spawn()`で作成された子プロセスの標準入出力パイプの操作、`uv_pipe()`で作成されたパイプペアの一方をlibuvハンドルとして使用する場合など。

**主要な処理内容**：
1. FDの有効性確認と重複チェック
2. ノンブロッキングモード設定（Unix）
3. アクセスモード判定（読み取り/書き込み）
4. ストリームとしてのオープン処理

**関連システム・外部連携**：Unix fcntl()、Windows NtQueryInformationFile API。

**権限による制御**：渡されるFDが有効なパイプであることが前提。型チェックは行われない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 19 | パイプ | 主機能 | uv_pipe_open()による既存FD関連付けのAPI定義 |

## 機能種別

リソース関連付け

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| handle | uv_pipe_t* | Yes | パイプハンドル | 初期化済み |
| file | uv_file | Yes | 関連付けるFD | 有効なFD/HANDLE |

### 入力データソース

呼び出し元が保持するFD（pipe(2)、socketpair(2)、uv_pipe()、uv_spawn()等で取得）。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | int | 成功時は0、失敗時は負のエラーコード |

### 出力先

関数の戻り値。成功時はハンドルがストリームとしてオープン済み状態になる。

## 処理フロー

### 処理シーケンス

```
1. FD有効性・重複チェック
   └─ (Unix) uv__fd_exists()、fcntl(fd, F_GETFL)
   └─ (Windows) uv__get_osfhandle()、状態チェック
2. ノンブロッキング設定（Unix）
3. アクセスモード判定
   └─ O_ACCMODE / FILE_ACCESS_INFORMATION
4. ストリームオープン
   └─ uv__stream_open()
```

### フローチャート

```mermaid
flowchart TD
    A[uv_pipe_open] --> B{FD有効?}
    B -->|No| C[UV_EBADF]
    B -->|Yes| D[アクセスモード取得]
    D --> E[READABLE/WRITABLE判定]
    E --> F[uv__stream_open]
    F --> G[return 0]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-65-01 | FD型チェックなし | 渡されたFDの型はチェックされない | 常時 |
| BR-65-02 | ノンブロッキング自動設定 | v1.2.1以降、FDは自動的にノンブロッキング設定される | Unix |
| BR-65-03 | stdio FD複製 | FD 0-2はDuplicateHandle()で複製 | Windows |
| BR-65-04 | IPC双方向必須 | IPCパイプでは読み書き両方のアクセス権が必要 | Windows IPC |

### 計算ロジック

`mode != O_WRONLY` → READABLE、`mode != O_RDONLY` → WRITABLE

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| UV_EBADF | 不正FD | FD無効、fcntl()失敗 | 有効なFDを渡す |
| UV_EEXIST | FD重複 | 同一ループで使用中（Unix） | 別FDを使用 |
| UV_EINVAL | パラメータ不正 | パイプサーバー状態、アクセス権不足 | 状態を確認 |
| UV_EBUSY | ビジー | 既に接続済み（Windows） | 別ハンドルを使用 |

### リトライ仕様

該当なし。

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

該当なし。

## パフォーマンス要件

O(1)で完了する。

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

渡されるFDの出所を信頼できることを確認すべき。

## 備考

- macOSではkqueue互換のためuv__stream_try_select()が呼ばれる
- FDの型チェックは行われないため、パイプ以外でも初期化成功の可能性あり

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | uv_pipe_open()のAPI宣言（876行目） |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | pipe.c (Unix) | `src/unix/pipe.c` | uv_pipe_open()実装（195-228行目） |

**主要処理フロー**:
- **201-202行目**: `uv__fd_exists()`でFD重複チェック
- **204-206行目**: `fcntl(fd, F_GETFL)`でアクセスモード取得
- **211-213行目**: `uv__nonblock(fd, 1)`
- **221-225行目**: O_ACCMODEからフラグ決定
- **227行目**: `uv__stream_open()`

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | pipe.c (Win) | `src/win/pipe.c` | uv_pipe_open()実装（2421-2480行目） |

**主要処理フロー**:
- **2422行目**: OSハンドル取得
- **2444-2455行目**: stdio FD複製処理
- **2461-2467行目**: NtQueryInformationFile()
- **2476-2479行目**: アクセス権からフラグ決定

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

```
uv_pipe_open()
    ├─ (Unix)
    │   ├─ uv__fd_exists()
    │   ├─ fcntl(fd, F_GETFL)
    │   ├─ uv__nonblock()
    │   └─ uv__stream_open()
    └─ (Windows)
        ├─ uv__get_osfhandle()
        ├─ DuplicateHandle()  [stdio FD]
        ├─ NtQueryInformationFile()
        └─ フラグ設定
```

### データフロー図

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

uv_pipe_t* ──┐
              ├──> uv_pipe_open() ──> ストリームオープン済みハンドル
uv_file fd ──┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダー | API宣言（876行目） |
| pipe.c (Unix) | `src/unix/pipe.c` | ソース | Unix実装（195-228行目） |
| pipe.c (Win) | `src/win/pipe.c` | ソース | Windows実装（2421-2480行目） |
| pipe.rst | `docs/src/pipe.rst` | ドキュメント | APIドキュメント（44-52行目） |
