# 機能設計書 120-FSポーリングパス取得

## 概要

本ドキュメントは、libuvのファイルシステムポーリング対象パス取得機能 `uv_fs_poll_getpath()` の設計仕様を記述する。現在ポーリング中のファイルパスを取得するAPI設計について定義する。

### 本機能の処理概要

`uv_fs_poll_getpath()` は、アクティブなFSポーリングハンドルが監視しているファイルのパスを取得する機能である。ユーザーが提供するバッファにパス文字列をコピーし、必要なバッファサイズを返す。

**業務上の目的・背景**：複数のFSポーリングハンドルを管理するアプリケーションにおいて、各ハンドルがどのパスをポーリングしているかを実行時に確認する必要がある。デバッグ、状態確認、ログ出力、管理UI表示などの目的で使用される。

**機能の利用シーン**：FSポーリングハンドルの状態確認、デバッグログ出力、ポーリング管理テーブルの構築、複数ファイルポーリングの状態表示など。

**主要な処理内容**：
1. バッファ/サイズパラメータのバリデーション
2. ハンドルのアクティブ状態チェック
3. ポーリングコンテキストからパス長の計算
4. バッファサイズのチェック
5. バッファへのパスコピー

**関連システム・外部連携**：特になし。

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 23 | ファイルシステムポーリング | 主機能 | uv_fs_poll_getpath()によるポーリング対象パス取得のAPI定義 |

## 機能種別

データ取得処理（ポーリング状態情報の取得）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| handle | uv_fs_poll_t* | Yes | FSポーリングハンドル | NULLでないこと |
| buffer | char* | Yes | パスを格納するバッファ | NULLでないこと |
| size | size_t* | Yes | バッファサイズ（入出力） | NULLでなく、*size > 0 |

### 入力データソース

初期化済みかつアクティブなFSポーリングハンドル。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | int | 成功時は0、エラー時は負のエラーコード |
| buffer | char* | ポーリング対象のパス文字列（NULターミネート） |
| *size | size_t | 実際のパス長（NULターミネータ含まず） |

### 出力先

ユーザー提供のバッファに出力。

## 処理フロー

### 処理シーケンス

```
1. パラメータバリデーション
   └─ buffer/size/sizeがNULLまたは*size==0ならUV_EINVAL
2. アクティブチェック
   └─ 非アクティブなら*size=0でUV_EINVAL
3. ポーリングコンテキスト取得
   └─ ctx = handle->poll_ctx（assertでNULLチェック）
4. 必要サイズ計算
   └─ required_len = strlen(ctx->path)
5. バッファサイズチェック
   └─ required_len >= *sizeなら*size = required_len+1でUV_ENOBUFS
6. パスコピー
   └─ memcpy(buffer, ctx->path, required_len)
7. 結果設定
   └─ *size = required_len, buffer[required_len] = '\0'
8. 成功返却
   └─ return 0
```

### フローチャート

```mermaid
flowchart TD
    A[uv_fs_poll_getpath] --> B{buffer/size/size有効?}
    B -->|No| C[return UV_EINVAL]
    B -->|Yes| D{ハンドルアクティブ?}
    D -->|No| E[size=0, return UV_EINVAL]
    D -->|Yes| F[ctx = handle->poll_ctx]
    F --> G[required_len = strlen ctx->path]
    G --> H{required_len >= size?}
    H -->|Yes| I[size = required_len+1, return UV_ENOBUFS]
    H -->|No| J[memcpy buffer, ctx->path]
    J --> K[size = required_len, buffer NUL終端]
    K --> L[return 0]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-120-1 | アクティブ必須 | 非アクティブなハンドルではUV_EINVALを返す | 常時 |
| BR-120-2 | バッファ不足通知 | バッファが小さい場合、必要サイズを*sizeに設定してUV_ENOBUFSを返す | バッファ不足時 |
| BR-120-3 | NULターミネート | 出力パスは必ずNULターミネートされる | 成功時 |
| BR-120-4 | コンテキスト参照 | パスはhandle->poll_ctx->pathから取得される（handle直接ではない） | 常時 |

### 計算ロジック

特になし。

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

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| UV_EINVAL | パラメータ不正 | buffer/sizeがNULLまたは*size==0、ハンドルが非アクティブ | パラメータを確認する |
| UV_ENOBUFS | バッファ不足 | バッファサイズがパス長より小さい | *sizeに返された必要サイズでバッファを再確保 |

### リトライ仕様

UV_ENOBUFS時は返された*sizeのバッファを確保して再呼び出しが可能。

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

該当なし。

## パフォーマンス要件

- strlen + memcpyのみの軽量処理

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

- 特になし。

## 備考

- uv_fs_poll_getpathはsrc/fs-poll.cに実装されている（uv_fs_event_getpathのuv-common.cとは異なる）
- uv_fs_event_getpath()と同様のインターフェース設計だが、パスの取得元が異なる（handle->path vs ctx->path）
- パスはpoll_ctx構造体の末尾に格納された可変長文字列から取得される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | **L1715-1717**: uv_fs_poll_getpath()のAPI宣言 |
| 1-2 | fs-poll.c | `src/fs-poll.c` | **L37-49**: struct poll_ctx。pathフィールドは構造体末尾の可変長文字列 |

**読解のコツ**: uv_fs_event_getpathはhandle->pathから取得するが、uv_fs_poll_getpathはhandle->poll_ctx->pathから取得する。この違いはFSイベントとFSポーリングの内部設計の違いに起因する。FSポーリングではpoll_ctxにパスを含む全ての状態が集約されている。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | fs-poll.c | `src/fs-poll.c` | **L138-164**: uv_fs_poll_getpath()の実装 |

**主要処理フロー**:
1. **L142-143**: buffer/size/sizeのバリデーション
2. **L145-148**: アクティブチェック。非アクティブなら*size=0でUV_EINVAL
3. **L150-151**: ctx取得とassert
4. **L153**: required_len = strlen(ctx->path)
5. **L154-157**: バッファサイズチェック。不足時は*size=required_len+1でUV_ENOBUFS
6. **L159-161**: memcpy、*size設定、NULターミネート
7. **L163**: return 0

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

```
uv_fs_poll_getpath()           [src/fs-poll.c L138]
    |
    +-- uv_is_active()         [アクティブ判定]
    +-- strlen()               [パス長計算]
    +-- memcpy()               [パスコピー]
```

### データフロー図

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

uv_fs_poll_t* handle    ──> ctx = poll_ctx     ──> buffer (パス文字列)
  .poll_ctx             ──> strlen(ctx->path)  ──> *size (パス長)
char* buffer            ──> memcpyコピー       ──> return 0 or エラー
size_t* size
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダー | uv_fs_poll_getpath()のAPI宣言 |
| fs-poll.c | `src/fs-poll.c` | ソース | getpath()の実装、poll_ctx構造体定義 |
