# 機能設計書 75-TTYウィンドウサイズ取得

## 概要

uv_tty_get_winsize()によりTTYのウィンドウサイズ（幅・高さ）を取得する機能の設計書である。

### 本機能の処理概要

uv_tty_get_winsize()は、TTYハンドルに関連付けられた端末のウィンドウサイズ（カラム数と行数）を取得する関数である。Unix環境ではioctl(TIOCGWINSZ)システムコールを、Windows環境ではGetConsoleScreenBufferInfo() APIを使用する。

**業務上の目的・背景**：端末アプリケーションでは、出力のフォーマットやレイアウトを端末のサイズに合わせて調整する必要がある。プログレスバーの幅、テーブルのカラム数、テキストの折り返し位置など、端末の幅と高さの情報は多くの場面で必要となる。

**機能の利用シーン**：
- CLIアプリケーションの出力フォーマット調整
- プログレスバーの幅計算
- テーブル表示のカラム幅調整
- テキストエディタの描画領域決定

**主要な処理内容**：
1. ioctl(TIOCGWINSZ)でstruct winsizeを取得する
2. ws_colをwidth、ws_rowをheightに設定する
3. エラー発生時はUV__ERR(errno)を返す

**関連システム・外部連携**：ioctl()システムコール（Unix）、GetConsoleScreenBufferInfo()（Windows）。

**権限による制御**：TTYデバイスへのアクセス権が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 20 | TTY | 主機能 | uv_tty_get_winsize()によるTTYウィンドウサイズ取得のAPI定義 |

## 機能種別

情報取得処理 - 端末ウィンドウサイズの取得

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| tty | uv_tty_t* | Yes | ウィンドウサイズを取得するTTYハンドル | 初期化済みであること |
| width | int* | Yes | 幅（カラム数）の格納先 | NULLでないこと |
| height | int* | Yes | 高さ（行数）の格納先 | NULLでないこと |

### 入力データソース

関数呼び出し時の引数として渡される。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | int | 成功時0、失敗時は負のエラーコード |
| *width | int | 端末の幅（カラム数） |
| *height | int | 端末の高さ（行数） |

### 出力先

呼び出し元のwidth, heightポインタに格納される。

## 処理フロー

### 処理シーケンス

```
1. ioctl(uv__stream_fd(tty), TIOCGWINSZ, &ws)を実行
   └─ EINTRの場合はリトライ（doループ）
2. エラー判定
   ├─ 失敗: return UV__ERR(errno)
   └─ 成功: *width = ws.ws_col, *height = ws.ws_row
3. return 0
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[ioctl TIOCGWINSZ]
    B --> C{EINTR?}
    C -->|Yes| B
    C -->|No| D{成功?}
    D -->|No| E[return UV__ERR errno]
    D -->|Yes| F[width = ws_col]
    F --> G[height = ws_row]
    G --> H[return 0]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-75-01 | EINTRリトライ | ioctlがEINTRで中断された場合は自動リトライ | 常時 |
| BR-75-02 | カラム・行単位 | サイズはカラム数（横）と行数（縦）で返される | 常時 |

### 計算ロジック

特段の計算ロジックはない。ws_colとws_rowをそのまま返す。

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| UV_ENOTTY | システムエラー | FDがTTYデバイスでない | 有効なTTYハンドルを使用する |
| UV_EBADF | システムエラー | 無効なFD | ハンドルの状態を確認する |

### リトライ仕様

EINTRはdoループで自動リトライされる。

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

該当なし。

## パフォーマンス要件

ioctl()は軽量な操作である。

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

特段のセキュリティ考慮はない。

## 備考

- Windows版ではGetConsoleScreenBufferInfo()を使用する（src/win/tty.c L440以降）
- ウィンドウサイズはリサイズイベント（SIGWINCH）により動的に変化する可能性がある

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | **L842**: uv_tty_get_winsize()の宣言 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | tty.c | `src/unix/tty.c` | **L376-391**: uv_tty_get_winsize()の全実装 |

**主要処理フロー**:
1. **377行目**: struct winsize ws 宣言
2. **380-382行目**: ioctl(TIOCGWINSZ)のEINTRリトライループ
3. **384-385行目**: エラー時UV__ERR(errno)返却
4. **387-388行目**: ws_col/ws_rowをwidth/heightに設定

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

```
uv_tty_get_winsize(tty, width, height)  [src/unix/tty.c L376]
    +-- uv__stream_fd(tty)              [FD取得]
    +-- ioctl(fd, TIOCGWINSZ, &ws)      [システムコール]
```

### データフロー図

```
[入力]              [処理]                     [出力]
tty (ハンドル) ---> ioctl(TIOCGWINSZ) -------> *width (ws_col)
                                        -----> *height (ws_row)
                                        -----> 戻り値 (0 or エラー)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダ | uv_tty_get_winsize()宣言（L842） |
| tty.c | `src/unix/tty.c` | ソース | Unix版実装（L376-391） |
| tty.c | `src/win/tty.c` | ソース | Windows版実装（L440以降） |
