# 画面設計書 20-TTY

## 概要

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

### 本画面の処理概要

TTYハンドルは、コンソール（ターミナル）に対するストリームを表現する。`uv_stream_t` のサブクラスであり、ストリーム共通APIに加えてTTY固有のモード設定・ウィンドウサイズ取得・仮想端末制御等のAPIを提供する。

**業務上の目的・背景**：CLIアプリケーション、REPLツール、テキストエディタなどのターミナルアプリケーションでは、標準入出力の制御が不可欠である。TTYハンドルは、ターミナルの入力モード（通常/RAW/IO）の切り替え、ウィンドウサイズの取得、仮想端末シーケンス処理の制御を提供する。RAWモードではキー入力を1文字ずつ処理でき、IOモードはIPCでのバイナリ安全な転送に使用される。Windows上では仮想端末（ConEmuやWindows 10コンソール）のANSIエスケープシーケンス処理の制御も可能である。本ページは、ターミナル制御機能を実装する開発者がTTYハンドルの各モードとプラットフォーム固有の動作を正確に理解するための公式リファレンスである。

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

**主要な操作・処理内容**：
1. `uv_tty_t` 型、`uv_tty_mode_t` 列挙型、`uv_tty_vtermstate_t` 列挙型の定義を閲覧する
2. `uv_tty_init()` によるTTY初期化（FD指定）のAPIを確認する
3. `uv_tty_set_mode()` によるTTYモード設定（NORMAL/RAW/IO/RAW_VT）のAPIを確認する
4. `uv_tty_reset_mode()` によるモードリセット（プログラム終了時用）のAPIを確認する
5. `uv_tty_get_winsize()` によるウィンドウサイズ取得APIを確認する
6. `uv_tty_set_vterm_state()` / `uv_tty_get_vterm_state()` による仮想端末制御APIを確認する

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

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 72 | TTY初期化 | 主機能 | uv_tty_init()によるTTYハンドル初期化のAPI定義 |
| 73 | TTYモード設定 | 主機能 | uv_tty_set_mode()によるTTYモード（NORMAL/RAW/IO）設定のAPI定義 |
| 74 | TTYモードリセット | 主機能 | uv_tty_reset_mode()による全TTYモードリセットのAPI定義 |
| 75 | TTYウィンドウサイズ取得 | 主機能 | uv_tty_get_winsize()によるTTYウィンドウサイズ取得のAPI定義 |
| 76 | 仮想端末状態制御 | 主機能 | uv_tty_set_vterm_state()/uv_tty_get_vterm_state()による仮想端末状態制御のAPI定義 |

## 画面種別

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

## URL/ルーティング

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

## 入出力項目

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

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

## 表示項目

| セクション | 表示内容 | 説明 |
|-----------|---------|------|
| タイトル | `uv_tty_t` --- TTY handle | ページタイトル |
| 概要説明 | TTY handles represent a stream for the console | TTYハンドルの概要 |
| Data types | uv_tty_t, uv_tty_mode_t, uv_tty_vtermstate_t | 型定義・列挙型 |
| uv_tty_mode_t | UV_TTY_MODE_NORMAL/RAW/IO/RAW_VT | TTYモード定義（v1.2.0追加） |
| uv_tty_vtermstate_t | UV_TTY_SUPPORTED/UV_TTY_UNSUPPORTED | 仮想端末状態 |
| Public members | N/A | 固有のパブリックメンバーなし |
| API - uv_tty_init | TTY初期化 | fd指定（0=stdin, 1=stdout, 2=stderr） |
| API - uv_tty_set_mode | モード設定 | v1.2.0でuv_tty_mode_t使用に変更 |
| API - uv_tty_reset_mode | モードリセット | プログラム終了時用、async-signal-safe |
| API - uv_tty_get_winsize | ウィンドウサイズ取得 | width/height取得 |
| API - uv_tty_set_vterm_state | 仮想端末状態設定 | v1.33.0追加、Windows専用 |
| API - uv_tty_get_vterm_state | 仮想端末状態取得 | v1.33.0追加、Unix非対応(UV_ENOTSUP) |
| See also | uv_stream_t API functions | ストリームAPIへの参照 |

## イベント仕様

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

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

### 2-TTY入力読み取り（ランタイム動作）

`uv_read_start()` でTTYからの入力読み取りを開始できる。RAWモードでは1文字ずつの入力が可能で、NORMALモードではライン単位の入力となる。

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

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

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

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

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

該当なし

## メッセージ仕様

| メッセージ種別 | 条件 | メッセージ内容 |
|--------------|------|--------------|
| エラー | ファイル型FDでuv_tty_init | UV_EINVAL（Unix、v1.5.0以降） |
| エラー | uv_tty_set_mode中のuv_tty_reset_mode | UV_EBUSY |
| エラー | Unixでuv_tty_get_vterm_state呼び出し | UV_ENOTSUP |

## 例外処理

- ページが見つからない場合：Webサーバーの404エラーが表示される
- TTY再オープン失敗時：libuvはブロッキング書き込みにフォールバック

## 備考

- `uv_tty_t` は `uv_stream_t` のサブクラスであり、ストリーム共通APIがそのまま適用される
- `uv_tty_mode_t` はv1.2.0で追加
- `uv_tty_init()` の `readable` パラメータはv1.23.1で非推奨（カーネルから自動検出）
- v1.9.0以降、TTYパスは `ttyname_r(3)` で決定される（以前は `/dev/tty`）
- v1.5.0以降、ファイル型FDでの初期化はUV_EINVALを返す
- `uv_tty_init()` はioctl TIOCGPTN/TIOCPTYGNAME非対応システム（OpenBSD, Solaris）でスレッドセーフではない
- `uv_tty_reset_mode()` はasync-signal-safeであり、シグナルハンドラから安全に呼び出せる
- `uv_tty_set_vterm_state()` / `uv_tty_get_vterm_state()` はv1.33.0で追加（Windows専用）
- `uv_tty_set_vterm_state()` はUnixでは無視される
- UV_TTY_MODE_RAW_VTはWindowsでENABLE_VIRTUAL_TERMINAL_INPUTも設定される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | `uv_tty_t` 構造体定義、`uv_tty_mode_t`・`uv_tty_vtermstate_t` 列挙型 |
| 1-2 | tty.rst | `docs/src/tty.rst` | 1-146行目: 型定義・列挙型・全API仕様 |

**読解のコツ**: `uv_tty_mode_t` には4つのモードがある。UV_TTY_MODE_NORMAL（通常）、UV_TTY_MODE_RAW（生入力）、UV_TTY_MODE_IO（バイナリ安全IPC、Unix限定）、UV_TTY_MODE_RAW_VT（生入力+VT処理、Windows限定）。

#### Step 2: TTY初期化を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | tty.c | `src/unix/tty.c` | 136行目: `uv_tty_init` - FD検証、ttyname_rでTTYパス取得、non-blocking設定 |

**主要処理フロー**:
1. **136行目**: `uv_tty_init` - FDがTTYかどうかの検証
2. `ttyname_r(3)` でTTYの実際のパスを取得
3. TTYのFDを再オープンしてnon-blockingモードに設定（他プロセスへの影響を回避）
4. 再オープン失敗時はブロッキング書き込みにフォールバック

#### Step 3: モード設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | tty.c | `src/unix/tty.c` | 281行目: `uv_tty_set_mode` - termiosを使ったモード切り替え |
| 3-2 | tty.c | `src/unix/tty.c` | 376行目: `uv_tty_get_winsize` - ioctl(TIOCGWINSZ)によるサイズ取得 |
| 3-3 | tty.c | `src/unix/tty.c` | 486行目: `uv_tty_reset_mode` - async-signal-safeなモードリセット |

#### Step 4: 仮想端末制御を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | tty.c | `src/unix/tty.c` | 505行目: `uv_tty_set_vterm_state` - Unix上では空実装 |
| 4-2 | tty.c | `src/unix/tty.c` | 508行目: `uv_tty_get_vterm_state` - Unix上ではUV_ENOTSUP |

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

```
uv_tty_init(loop, handle, fd, unused) [src/unix/tty.c:136]
    |
    +-- isatty(fd) / ttyname_r(fd) [TTY検証・パス取得]
    +-- open(tty_path, O_RDWR) [TTY再オープン]
    +-- uv__nonblock() [non-blocking設定]
    +-- uv__stream_init() [ストリーム初期化]

uv_tty_set_mode(handle, mode) [src/unix/tty.c:281]
    |
    +-- tcgetattr() [現在の設定取得]
    +-- cfmakeraw() [RAWモード設定]
    +-- tcsetattr() [設定適用]

uv_tty_reset_mode() [src/unix/tty.c:486]
    |
    +-- tcsetattr() [保存済み設定に復元]
    (async-signal-safe)

uv_tty_get_winsize(handle, width, height) [src/unix/tty.c:376]
    |
    +-- ioctl(fd, TIOCGWINSZ, &ws) [ウィンドウサイズ取得]

uv_tty_set_vterm_state(state) [src/unix/tty.c:505]
    +-- (Unixでは無操作)

uv_tty_get_vterm_state(state) [src/unix/tty.c:508]
    +-- return UV_ENOTSUP (Unixでは非対応)
```

### データフロー図

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

uv_tty_init(fd=0)       ---> isatty() + ttyname_r()     ---> 初期化済みTTYハンドル
                              TTY再オープン + non-blocking

uv_tty_set_mode(RAW)    ---> tcgetattr() + cfmakeraw()  ---> RAWモードTTY
                              tcsetattr()

uv_tty_get_winsize()    ---> ioctl(TIOCGWINSZ)          ---> width, height

uv_read_start(tty, ...) ---> read(fd)                   ---> read_cb(nread, buf)
                              (RAW: 1文字ずつ)
                              (NORMAL: ライン単位)

プログラム終了時         ---> uv_tty_reset_mode()        ---> 端末設定復元
                              tcsetattr(保存設定)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| tty.rst | `docs/src/tty.rst` | テンプレート | TTYハンドルドキュメントのソース |
| uv.h | `include/uv.h` | ソース | uv_tty_t・uv_tty_mode_t・uv_tty_vtermstate_t定義 |
| tty.c | `src/unix/tty.c` | ソース | Unix用TTY init/set_mode/reset_mode/get_winsize/vterm実装 |
| tty.c | `src/win/tty.c` | ソース | Windows用TTY実装（コンソールAPI使用） |
| stream.c | `src/unix/stream.c` | ソース | ストリーム共通read/write実装 |
