# 画面設計書 16-プロセス

## 概要

本ドキュメントは、libuvドキュメントサイトにおける `uv_process_t`（プロセスハンドル）APIリファレンスページの画面設計書である。Sphinxにより生成されるHTMLページとして、プロセスハンドルの型定義・オプション構造体・標準入出力設定・API関数仕様を表示する。

### 本画面の処理概要

プロセスハンドルは、子プロセスの生成と管理を行い、ストリームを使ったプロセス間通信チャネルの確立を可能にする。本ページでは、プロセスの生成（uv_spawn）、シグナル送信、PID取得に関するAPIと、関連するオプション構造体・フラグ・標準入出力設定を詳細に解説する。

**業務上の目的・背景**：外部コマンドの実行、パイプライン処理、マルチプロセスアーキテクチャの実装において、子プロセスの生成と管理は基本的な機能である。libuvのプロセスハンドルは、クロスプラットフォームで一貫した子プロセス管理APIを提供し、標準入出力のリダイレクト・環境変数設定・UID/GID設定・プロセスのデタッチなど、高度な機能をサポートする。Node.jsの `child_process` モジュールの基盤として広く使用されている。本ページは、子プロセスを安全に生成・管理するために必要なオプション設定と、プラットフォーム固有の動作差異を理解するための公式リファレンスである。

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

**主要な操作・処理内容**：
1. `uv_process_t`、`uv_process_options_t`、`uv_exit_cb`、`uv_process_flags`、`uv_stdio_container_t`、`uv_stdio_flags` の型定義と列挙型を閲覧する
2. `uv_process_options_t` の各メンバー（file, args, env, cwd, flags, stdio, uid, gid）の仕様を確認する
3. `uv_stdio_flags` によるstdio設定方法（UV_IGNORE, UV_CREATE_PIPE, UV_INHERIT_FD, UV_INHERIT_STREAM等）を確認する
4. `uv_disable_stdio_inheritance()` / `uv_spawn()` / `uv_process_kill()` / `uv_kill()` / `uv_process_get_pid()` の各API仕様を確認する
5. プロセスフラグ（SETUID, SETGID, DETACHED, WINDOWS_HIDE等）の仕様を確認する

**画面遷移**：
- 遷移元：APIドキュメント一覧（api.rst）
- 遷移先：ハンドル基底ページ（handle.rst）、シグナルページ（signal.rst）への参照リンク
- 関連ページ：パイプページ（pipe.rst）、ストリームページ（stream.rst）

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 90 | プロセス生成 | 主機能 | uv_spawn()による子プロセス生成のAPI定義（stdio・環境変数・UID/GID設定対応） |
| 91 | プロセスキル | 主機能 | uv_process_kill()/uv_kill()によるプロセスへのシグナル送信のAPI定義 |
| 92 | プロセスPID取得 | 主機能 | uv_process_get_pid()によるプロセスPID取得のAPI定義 |
| 162 | 標準入出力継承無効化 | 補助機能 | uv_disable_stdio_inheritance()による子プロセスへのFD継承無効化のAPI定義 |

## 画面種別

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

## URL/ルーティング

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

## 入出力項目

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

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

## 表示項目

| セクション | 表示内容 | 説明 |
|-----------|---------|------|
| タイトル | `uv_process_t` --- Process handle | ページタイトル |
| 概要説明 | Process handles will spawn a new process... | プロセスハンドルの概要 |
| Data types | uv_process_t, uv_process_options_t, uv_exit_cb | 型定義 |
| uv_process_flags | SETUID/SETGID/DETACHED/WINDOWS_HIDE等 | プロセスフラグ列挙 |
| uv_stdio_container_t | stream/fdの共用体 | stdio設定構造体 |
| uv_stdio_flags | UV_IGNORE/CREATE_PIPE/INHERIT_FD/INHERIT_STREAM等 | stdio設定フラグ |
| Public members | uv_process_t.pid、options各メンバー | パブリックメンバー |
| API - uv_disable_stdio_inheritance | stdio継承無効化 | プログラム早期に呼び出し推奨 |
| API - uv_spawn | プロセス生成 | オプション構造体による設定 |
| API - uv_process_kill | シグナル送信（ハンドル経由） | ハンドル指定版 |
| API - uv_kill | シグナル送信（PID経由） | PID指定版 |
| API - uv_process_get_pid | PID取得 | v1.19.0追加 |
| See also | uv_handle_t API functions | 基底ハンドルAPIへの参照 |

## イベント仕様

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

`:c:type:`uv_handle_t``、`:c:ref:`signal``、`:c:enum:`uv_process_flags`` 等への参照リンクで各セクション・ページに遷移する。

### 2-exit_cb実行（ランタイム動作）

子プロセスが終了すると、`uv_process_options_t.exit_cb` に設定したコールバックが呼び出され、終了ステータスと終了シグナルが通知される。

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

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

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

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

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

該当なし

## メッセージ仕様

| メッセージ種別 | 条件 | メッセージ内容 |
|--------------|------|--------------|
| エラー | uv_spawnで実行ファイルが存在しない等 | 負のエラーコード返却 |
| エラー | WindowsでSETUID/SETGID使用時 | UV_ENOTSUP |

## 例外処理

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

## 備考

- `uv_process_get_pid()` はv1.19.0で追加
- `UV_PROCESS_WINDOWS_HIDE_CONSOLE`/`UV_PROCESS_WINDOWS_HIDE_GUI` はv1.24.0で追加
- `UV_PROCESS_WINDOWS_FILE_PATH_EXACT_NAME` はv1.48.0で追加
- WindowsでUID/GID設定は非対応（UV_ENOTSUP）
- WindowsではFD 2より大きいファイルディスクリプタはMSVCRTランタイム使用時のみ利用可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | `uv_process_t`、`uv_process_options_t`、`uv_process_flags`、`uv_stdio_container_t`、`uv_stdio_flags` の定義箇所 |
| 1-2 | process.rst | `docs/src/process.rst` | 1-292行目: 全データ型・フラグ・API仕様 |

**読解のコツ**: `uv_process_options_t` は多数のメンバーを持つ複合構造体である。stdioの設定は `uv_stdio_container_t` 配列で行い、各要素に `uv_stdio_flags` でモード指定し、`data` 共用体でstream/fdを設定する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | process.c | `src/unix/process.c` | `uv_spawn` 関数 - オプション検証、fork/exec、stdioセットアップ |
| 2-2 | process.c | `src/unix/process.c` | 84行目: SIGCHLD監視のための `uv_signal_init` 呼び出し |
| 2-3 | process.c | `src/unix/process.c` | 1019行目: `uv_signal_start` でSIGCHLD監視開始 |

**主要処理フロー**:
1. オプション構造体の検証（file, args等）
2. SIGCHLDシグナルハンドラの初期化と開始
3. fork()による子プロセス生成
4. 子プロセス側でstdioリダイレクト、execvp()実行
5. 親プロセス側でPID記録、ハンドル開始

#### Step 3: プロセスキルとPID取得を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | uv-data-getter-setters.c | `src/uv-data-getter-setters.c` | `uv_process_get_pid` - handle->pidを返す |

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

```
uv_spawn(loop, handle, options) [src/unix/process.c]
    |
    +-- uv_signal_init() / uv_signal_start() [SIGCHLD監視]
    +-- fork() [子プロセス生成]
    |      |
    |      +-- [子プロセス] stdio設定 → execvp(options->file)
    |
    +-- [親プロセス] PID記録、ハンドル開始

uv_process_kill(handle, signum) [src/unix/process.c]
    |
    +-- kill(handle->pid, signum) [シグナル送信]

uv_kill(pid, signum) [src/unix/process.c]
    |
    +-- kill(pid, signum) [シグナル送信]

[子プロセス終了時]
SIGCHLD → uv__chld() → exit_cb(handle, exit_status, term_signal)
```

### データフロー図

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

uv_process_options_t    --->  uv_spawn()                 ---> uv_process_t
(file, args, env, cwd,       fork() + execvp()               (pid設定済み)
 flags, stdio, uid, gid)

SIGCHLD受信             --->  uv__chld()                 ---> exit_cb呼び出し
                              waitpid()                       (exit_status, term_signal)

uv_process_kill(signum) --->  kill(pid, signum)          ---> シグナル送信
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| process.rst | `docs/src/process.rst` | テンプレート | プロセスハンドルドキュメントのソース |
| uv.h | `include/uv.h` | ソース | uv_process_t・uv_process_options_t・フラグ類の定義 |
| process.c | `src/unix/process.c` | ソース | Unix用spawn/kill/PID取得実装 |
| process.c | `src/win/process.c` | ソース | Windows用spawn/kill実装 |
| uv-data-getter-setters.c | `src/uv-data-getter-setters.c` | ソース | uv_process_get_pid実装 |
| signal.c | `src/unix/signal.c` | ソース | SIGCHLD処理に使用されるシグナルインフラ |
