# 画面設計書 19-パイプ

## 概要

本ドキュメントは、libuvドキュメントサイトにおける `uv_pipe_t`（パイプハンドル）APIリファレンスページの画面設計書である。Sphinxにより生成されるHTMLページとして、パイプハンドルの型定義・API関数仕様を表示する。

### 本画面の処理概要

パイプハンドルは、Unix上のストリーミングファイル（ローカルドメインソケット、パイプ、FIFO）およびWindows上のネームドパイプに対する抽象化を提供する。`uv_stream_t` のサブクラスであり、ストリーム共通APIに加えてパイプ固有の初期化・バインド・接続・IPC機能・権限変更等のAPIを提供する。

**業務上の目的・背景**：パイプは、同一マシン上のプロセス間通信（IPC）の主要な手段であり、UNIXドメインソケットやWindowsネームドパイプを通じたデータ転送およびハンドル受け渡しに使用される。libuvのパイプハンドルは、クロスプラットフォームでIPC機能を統一的に提供し、子プロセスとの通信、マイクロサービス間通信、ファイルベースのストリーム処理などに活用される。特にIPC機能（ハンドル送受信）は、マルチプロセスサーバーアーキテクチャにおいてソケットの分配に不可欠である。本ページは、パイプハンドルのIPCサポート・バインド・接続・ペア作成・権限変更等の全APIを正確に理解するための公式リファレンスである。

**画面へのアクセス方法**：トップページ → APIドキュメント一覧（api.rst） → パイプ（pipe.rst）の順にナビゲーションリンクを辿ってアクセスする。

**主要な操作・処理内容**：
1. `uv_pipe_t` 型の定義とパブリックメンバー `ipc` の仕様を閲覧する
2. `uv_pipe_init()` によるパイプ初期化（IPC指定）のAPIを確認する
3. `uv_pipe_open()` / `uv_pipe_bind()` / `uv_pipe_bind2()` によるバインドAPIを確認する
4. `uv_pipe_connect()` / `uv_pipe_connect2()` による接続APIを確認する
5. `uv_pipe_getsockname()` / `uv_pipe_getpeername()` によるパイプ名取得APIを確認する
6. `uv_pipe_pending_instances()` / `uv_pipe_pending_count()` / `uv_pipe_pending_type()` によるIPC関連APIを確認する
7. `uv_pipe_chmod()` / `uv_pipe()` のAPIを確認する

**画面遷移**：
- 遷移元：APIドキュメント一覧（api.rst）
- 遷移先：ストリームページ（stream.rst）への参照リンク
- 関連ページ：TCPページ（tcp.rst）、TTYページ（tty.rst）、プロセスページ（process.rst）

**権限による表示制御**：なし（公開ドキュメントサイトのため、全ユーザーが同一内容を閲覧可能）

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 62 | パイプ初期化 | 主機能 | uv_pipe_init()によるパイプハンドル初期化のAPI定義（IPC対応） |
| 63 | パイプバインド | 主機能 | uv_pipe_bind()/uv_pipe_bind2()によるパイプバインドのAPI定義 |
| 64 | パイプ接続 | 主機能 | uv_pipe_connect()/uv_pipe_connect2()による非同期パイプ接続のAPI定義 |
| 65 | パイプ既存FDオープン | 主機能 | uv_pipe_open()による既存FD関連付けのAPI定義 |
| 66 | パイプ名取得 | 主機能 | uv_pipe_getsockname()/uv_pipe_getpeername()によるパイプ名取得のAPI定義 |
| 67 | パイプ保留インスタンス数設定 | 主機能 | uv_pipe_pending_instances()による保留インスタンス数設定のAPI定義（Windows用） |
| 68 | パイプ保留ハンドル情報取得 | 主機能 | uv_pipe_pending_count()/uv_pipe_pending_type()による保留ハンドル情報取得のAPI定義 |
| 69 | パイプ権限変更 | 主機能 | uv_pipe_chmod()によるパイプ権限変更のAPI定義 |
| 70 | パイプペア作成 | 主機能 | uv_pipe()による接続済みパイプペア作成のAPI定義 |

## 画面種別

APIリファレンス詳細ページ

## URL/ルーティング

`docs/src/pipe.rst` → ビルド後: `/pipe.html`

## 入出力項目

本ページはドキュメント表示ページのため、ユーザー入力項目はない。

| 項目名 | 入出力 | 型 | 説明 |
|--------|--------|-----|------|
| ページコンテンツ | 出力 | HTML | rstファイルからSphinxによって生成されたHTML |

## 表示項目

| セクション | 表示内容 | 説明 |
|-----------|---------|------|
| タイトル | `uv_pipe_t` --- Pipe handle | ページタイトル |
| 概要説明 | Pipe handles provide an abstraction over streaming files... | パイプハンドルの概要 |
| Data types | uv_pipe_t | 型定義 |
| Public members | uv_pipe_t.ipc | IPCフラグ（接続パイプのみ設定） |
| API - uv_pipe_init | パイプ初期化 | ipc引数でIPC有効化 |
| API - uv_pipe_open | 既存FDオープン | v1.2.1でnon-blocking設定 |
| API - uv_pipe_bind/bind2 | パイプバインド | bind2はv1.46.0追加、Linux abstract namespace対応 |
| API - uv_pipe_connect/connect2 | パイプ接続 | connect2はv1.46.0追加 |
| API - uv_pipe_getsockname | パイプ名取得 | v1.3.0で終端NULLなし変更 |
| API - uv_pipe_getpeername | 接続先パイプ名取得 | v1.3.0追加 |
| API - uv_pipe_pending_instances | 保留インスタンス数 | Windows専用 |
| API - uv_pipe_pending_count/type | IPC保留ハンドル情報 | IPC受信用 |
| API - uv_pipe_chmod | 権限変更 | v1.16.0追加、ブロッキング操作 |
| API - uv_pipe | パイプペア作成 | v1.41.0追加 |
| See also | uv_stream_t API functions | ストリームAPIへの参照 |

## イベント仕様

### 1-ページ内リンク遷移

`:c:type:`uv_stream_t`` への参照リンクでストリームページに遷移する。

### 2-接続コールバック（ランタイム動作）

`uv_pipe_connect()` / `uv_pipe_connect2()` による非同期接続が完了すると、`uv_connect_cb` が呼び出される。

### 3-IPC受信（ランタイム動作）

IPC有効パイプで `uv_pipe_pending_count()` が > 0 の場合、`uv_pipe_pending_type()` で型を取得し、`uv_accept()` でハンドルを受信する。

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

本ページは静的ドキュメント表示のため、データベース操作は存在しない。

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| N/A | N/A | N/A | 静的HTMLドキュメントのためDB操作なし |

### テーブル別更新項目詳細

該当なし

## メッセージ仕様

| メッセージ種別 | 条件 | メッセージ内容 |
|--------------|------|--------------|
| エラー | bind2/connect2で不正フラグ | UV_EINVAL |
| エラー | getsocknameでバッファ不足 | UV_ENOBUFS |
| エラー | bind2でパス長超過かつUV_PIPE_NO_TRUNCATE | UV_EINVAL |

## 例外処理

- ページが見つからない場合：Webサーバーの404エラーが表示される

## 備考

- `uv_pipe_t` は `uv_stream_t` のサブクラスであり、ストリーム共通APIがそのまま適用される
- `uv_pipe_bind2()` / `uv_pipe_connect2()` はv1.46.0で追加（Linux abstract namespace対応、UV_PIPE_NO_TRUNCATE対応）
- パス長制限：Unixではsockaddr_un.sun_pathサイズ（通常92-108バイト）に切り詰めされる
- `uv_pipe_chmod()` はv1.16.0追加、ブロッキング操作である
- `uv_pipe()` 関数（パイプペア作成）はv1.41.0追加
- `uv_pipe_pending_instances()` はWindows専用

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | `uv_pipe_t` 構造体定義 |
| 1-2 | pipe.rst | `docs/src/pipe.rst` | 1-183行目: 型定義・パブリックメンバー・全API仕様 |

**読解のコツ**: `uv_pipe_t.ipc` メンバーは、ハンドル受け渡し用パイプかどうかを示す。接続済みパイプ（acceptされた側）のみipc=1に設定すべきで、listen側のパイプには設定しない。

#### Step 2: パイプ初期化とバインド・接続を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | pipe.c | `src/unix/pipe.c` | 48行目: `uv_pipe_init` - ipcフラグ設定を含むパイプ初期化 |
| 2-2 | pipe.c | `src/unix/pipe.c` | 58行目: `uv_pipe_bind` - ファイルパスへのバインド |
| 2-3 | pipe.c | `src/unix/pipe.c` | 231行目: `uv_pipe_connect` - UNIXドメインソケット接続 |
| 2-4 | pipe.c | `src/unix/pipe.c` | 195行目: `uv_pipe_open` - 既存FDのパイプハンドル化 |

#### Step 3: IPC・権限変更・ペア作成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | pipe.c | `src/unix/pipe.c` | 448行目: `uv_pipe_chmod` - ファイルパーミッション変更 |
| 3-2 | pipe.c | `src/unix/pipe.c` | 497行目: `uv_pipe` - パイプペア作成（pipe2/pipe + O_CLOEXEC） |

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

```
uv_pipe_init(loop, handle, ipc) [src/unix/pipe.c:48]
    |
    +-- uv__stream_init() [ストリーム初期化]
    +-- handle->ipc = ipc

uv_pipe_bind(handle, name) [src/unix/pipe.c:58]
    |
    +-- uv_pipe_bind2(handle, name, strlen(name), 0) [内部委譲]
           |
           +-- socket(AF_UNIX) [ソケット作成]
           +-- bind() [バインド]

uv_pipe_connect(req, handle, name, cb) [src/unix/pipe.c:231]
    |
    +-- uv_pipe_connect2(req, handle, name, strlen(name), 0, cb)
           |
           +-- socket(AF_UNIX) [ソケット作成]
           +-- connect() [接続]

uv_pipe_chmod(handle, mode) [src/unix/pipe.c:448]
    |
    +-- chmod() / stat() + chmod() [権限変更]

uv_pipe(fds, read_flags, write_flags) [src/unix/pipe.c:497]
    |
    +-- pipe2() / pipe() + fcntl(O_CLOEXEC) [パイプペア作成]
```

### データフロー図

```
[サーバー側]

uv_pipe_init(ipc=0)  ---> uv_pipe_bind("/tmp/sock")  ---> uv_listen(backlog, cb)
                                                               |
                                                          connection_cb
                                                               |
                                                          uv_accept(server, client)

[クライアント側]

uv_pipe_init(ipc=0)  ---> uv_pipe_connect("/tmp/sock", cb)
                               |
                          connect_cb(req, status)

[IPC用途]

uv_pipe_init(ipc=1)  ---> uv_write2(req, pipe, bufs, send_handle, cb) [ハンドル送信]
                          uv_pipe_pending_count() > 0 → uv_accept(pipe, handle) [ハンドル受信]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| pipe.rst | `docs/src/pipe.rst` | テンプレート | パイプハンドルドキュメントのソース |
| uv.h | `include/uv.h` | ソース | uv_pipe_t構造体定義 |
| pipe.c | `src/unix/pipe.c` | ソース | Unix用pipe init/bind/connect/open/chmod/pipe実装 |
| pipe.c | `src/win/pipe.c` | ソース | Windows用パイプ実装（ネームドパイプ） |
| stream.c | `src/unix/stream.c` | ソース | ストリーム共通read/write/listen/accept実装 |
