# 画面設計書 18-TCP

## 概要

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

### 本画面の処理概要

TCPハンドルは、TCPストリームおよびサーバーの両方を表現するために使用される。`uv_stream_t` のサブクラスであり、ストリーム共通APIに加えてTCP固有の初期化・バインド・接続・ソケットオプション設定・アドレス取得等のAPIを提供する。

**業務上の目的・背景**：TCPはインターネットプロトコルの基盤であり、Webサーバー・APIサーバー・データベース接続など、ほぼ全てのネットワークアプリケーションで使用される。libuvのTCPハンドルは、ソケットの作成・バインド・接続・リスン・データ送受信・ソケットオプション設定をクロスプラットフォームで統一されたAPIとして提供する。IPv4/IPv6の両方をサポートし、Nagle制御（TCP_NODELAY）、キープアライブ設定、同時接続受入制御、SO_REUSEPORTなど高度なソケットオプションも扱える。本ページは、TCP通信アプリケーションを構築する開発者が、ソケットライフサイクル全体を通じて必要なAPIを正確に把握するための公式リファレンスである。

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

**主要な操作・処理内容**：
1. `uv_tcp_t` 型と `uv_tcp_flags` 列挙型の定義を閲覧する
2. `uv_tcp_init()` / `uv_tcp_init_ex()` による初期化APIの仕様を確認する
3. `uv_tcp_open()` / `uv_tcp_bind()` / `uv_tcp_connect()` によるソケット設定・接続APIの仕様を確認する
4. `uv_tcp_nodelay()` / `uv_tcp_keepalive()` / `uv_tcp_keepalive_ex()` / `uv_tcp_simultaneous_accepts()` によるソケットオプション設定APIの仕様を確認する
5. `uv_tcp_getsockname()` / `uv_tcp_getpeername()` によるアドレス取得APIの仕様を確認する
6. `uv_tcp_close_reset()` / `uv_socketpair()` の仕様を確認する

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

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 39 | TCP初期化 | 主機能 | uv_tcp_init()/uv_tcp_init_ex()によるTCPハンドル初期化のAPI定義 |
| 40 | TCPバインド | 主機能 | uv_tcp_bind()によるTCPソケットバインドのAPI定義（IPv6only・REUSEPORT対応） |
| 41 | TCP接続 | 主機能 | uv_tcp_connect()による非同期TCP接続のAPI定義 |
| 42 | TCP既存ソケットオープン | 主機能 | uv_tcp_open()による既存OSソケット関連付けのAPI定義 |
| 43 | Nagle制御 | 主機能 | uv_tcp_nodelay()によるTCP_NODELAYオプション設定のAPI定義 |
| 44 | キープアライブ設定 | 主機能 | uv_tcp_keepalive()/uv_tcp_keepalive_ex()によるTCPキープアライブのAPI定義 |
| 45 | 同時接続受入制御 | 主機能 | uv_tcp_simultaneous_accepts()による同時接続受入制御のAPI定義 |
| 46 | TCPアドレス取得 | 主機能 | uv_tcp_getsockname()/uv_tcp_getpeername()によるアドレス取得のAPI定義 |
| 47 | TCPリセットクローズ | 主機能 | uv_tcp_close_reset()によるRSTパケット送信クローズのAPI定義 |
| 71 | ソケットペア作成 | 補助機能 | uv_socketpair()による接続済みソケットペア作成のAPI定義 |

## 画面種別

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

## URL/ルーティング

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

## 入出力項目

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

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

## 表示項目

| セクション | 表示内容 | 説明 |
|-----------|---------|------|
| タイトル | `uv_tcp_t` --- TCP handle | ページタイトル |
| 概要説明 | TCP handles are used to represent both TCP streams and servers | TCPハンドルの概要 |
| Data types | uv_tcp_t, uv_tcp_flags | 型定義・フラグ |
| uv_tcp_flags | UV_TCP_IPV6ONLY=1, UV_TCP_REUSEPORT=2 | バインドフラグ |
| API - uv_tcp_init/init_ex | 初期化 | ドメイン指定版はv1.7.0追加 |
| API - uv_tcp_open | 既存ソケットオープン | v1.2.1でnon-blocking設定 |
| API - uv_tcp_nodelay | Nagle制御 | TCP_NODELAY設定 |
| API - uv_tcp_keepalive | キープアライブ | delay秒後、10プローブ |
| API - uv_tcp_keepalive_ex | キープアライブ拡張 | idle/intvl/cnt設定、v1.52.0追加 |
| API - uv_tcp_simultaneous_accepts | 同時接続受入 | デフォルト有効 |
| API - uv_tcp_bind | バインド | IPv6only/REUSEPORT対応 |
| API - uv_tcp_getsockname/getpeername | アドレス取得 | sockaddr_storage推奨 |
| API - uv_tcp_connect | TCP接続 | IPv4/IPv6対応 |
| API - uv_tcp_close_reset | RSTクローズ | v1.32.0追加 |
| API - uv_socketpair | ソケットペア | v1.41.0追加 |
| See also | uv_stream_t API functions | ストリームAPIへの参照 |

## イベント仕様

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

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

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

`uv_tcp_connect()` による非同期接続が完了（成功または失敗）すると、`uv_connect_cb` が呼び出される。Windows上で未指定アドレス（0.0.0.0や::）はlocalhostにマッピングされる（v1.19.0以降）。

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

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

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

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

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

該当なし

## メッセージ仕様

| メッセージ種別 | 条件 | メッセージ内容 |
|--------------|------|--------------|
| エラー | バインドでポート使用中かつREUSEPORT未指定 | UV_EADDRINUSE（listen/connect時） |
| エラー | keepaliveのdelay<1 | UV_EINVAL（v1.49.0以降） |
| エラー | REUSEPORTが非対応プラットフォーム | UV_ENOTSUP |

## 例外処理

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

## 備考

- `uv_tcp_t` は `uv_stream_t` のサブクラスであり、ストリーム共通APIがそのまま適用される
- `uv_tcp_init_ex()` はv1.7.0で追加（ドメイン指定でソケット事前作成）
- `uv_tcp_keepalive()` でdelay<1の場合UV_EINVAL返却はv1.49.0追加
- `uv_tcp_keepalive_ex()` はv1.52.0で追加（TCP_KEEPINTVL/TCP_KEEPCNT設定対応）
- UV_TCP_REUSEPORTはv1.49.0で追加（Linux 3.9+, DragonFlyBSD 3.6+, FreeBSD 12.0+, Solaris 11.4, AIX 7.2.5+）
- `uv_tcp_close_reset()` はv1.32.0で追加（SO_LINGER=0設定後uv_close）
- `uv_socketpair()` はv1.41.0で追加

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | `uv_tcp_t` 構造体定義、`uv_tcp_flags` 列挙型 |
| 1-2 | tcp.rst | `docs/src/tcp.rst` | 1-219行目: 型定義・フラグ・全API仕様 |

**読解のコツ**: `uv_tcp_t` は `uv_stream_t` のサブクラスであるため、`UV_HANDLE_FIELDS` + `UV_STREAM_FIELDS` + TCP固有フィールドで構成される。ストリーム共通API（read/write/listen/accept等）はstream.rstで定義される。

#### Step 2: TCP固有APIを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | tcp.c | `src/unix/tcp.c` | 146行目: `uv_tcp_init` - ハンドル初期化 |
| 2-2 | tcp.c | `src/unix/tcp.c` | 352行目: `uv_tcp_open` - 既存ソケットの関連付け |
| 2-3 | tcp.c | `src/unix/tcp.c` | 573行目: `uv_tcp_nodelay` - TCP_NODELAY設定 |
| 2-4 | tcp.c | `src/unix/tcp.c` | 591行目: `uv_tcp_keepalive` - キープアライブ設定 |
| 2-5 | tcp.c | `src/unix/tcp.c` | 396行目: `uv_tcp_close_reset` - RST送信クローズ |
| 2-6 | tcp.c | `src/unix/tcp.c` | 632行目: `uv_socketpair` - ソケットペア作成 |

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

```
uv_tcp_init(loop, handle) [src/unix/tcp.c:146]
    |
    +-- uv__stream_init() [ストリーム初期化]

uv_tcp_bind(handle, addr, flags) [src/unix/tcp.c]
    |
    +-- uv__tcp_bind() [内部バインド処理]
    +-- bind() [システムコール]

uv_tcp_connect(req, handle, addr, cb) [src/unix/tcp.c]
    |
    +-- connect() [非同期接続開始]
    +-- [完了時] connect_cb(req, status)

uv_tcp_nodelay(handle, on) [src/unix/tcp.c:573]
    |
    +-- setsockopt(TCP_NODELAY) [ソケットオプション設定]

uv_tcp_keepalive(handle, on, delay) [src/unix/tcp.c:591]
    |
    +-- setsockopt(SO_KEEPALIVE) [キープアライブ有効化]
    +-- setsockopt(TCP_KEEPIDLE) [アイドル時間設定]

uv_tcp_close_reset(handle, close_cb) [src/unix/tcp.c:396]
    |
    +-- setsockopt(SO_LINGER, {0,0}) [linger=0設定]
    +-- uv_close() [ハンドルクローズ]
```

### データフロー図

```
[サーバー側]

uv_tcp_init()  ---> uv_tcp_bind(addr) ---> uv_listen(backlog, cb)
                                                |
                                           connection_cb
                                                |
                                           uv_accept(server, client)
                                                |
                                           uv_read_start(client, ...)

[クライアント側]

uv_tcp_init()  ---> uv_tcp_connect(addr, cb)
                         |
                    connect_cb(req, status)
                         |
                    uv_write(req, handle, bufs, cb)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| tcp.rst | `docs/src/tcp.rst` | テンプレート | TCPハンドルドキュメントのソース |
| uv.h | `include/uv.h` | ソース | uv_tcp_t・uv_tcp_flags定義 |
| tcp.c | `src/unix/tcp.c` | ソース | Unix用TCP init/open/bind/connect/nodelay/keepalive/close_reset/socketpair実装 |
| tcp.c | `src/win/tcp.c` | ソース | Windows用TCP実装 |
| stream.c | `src/unix/stream.c` | ソース | ストリーム共通read/write/listen/accept実装 |
