# 機能設計書 117-FSイベントパス取得

## 概要

本ドキュメントは、libuvのファイルシステムイベント監視対象パス取得機能 `uv_fs_event_getpath()` の設計仕様を記述する。現在監視中のファイル/ディレクトリのパスを取得するAPI設計について定義する。

### 本機能の処理概要

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

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

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

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

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

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 22 | ファイルシステムイベント | 主機能 | uv_fs_event_getpath()による監視対象パス取得のAPI定義 |

## 機能種別

データ取得処理（監視状態情報の取得）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| handle | uv_fs_event_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. 必要サイズ計算
   └─ required_len = strlen(handle->path)
4. バッファサイズチェック
   └─ required_len >= *sizeなら*size = required_len+1でUV_ENOBUFS
5. パスコピー
   └─ memcpy(buffer, handle->path, required_len)
6. 結果設定
   └─ *size = required_len, buffer[required_len] = '\0'
7. 成功返却
   └─ return 0
```

### フローチャート

```mermaid
flowchart TD
    A[uv_fs_event_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[required_len = strlen handle->path]
    F --> G{required_len >= size?}
    G -->|Yes| H[size = required_len+1, return UV_ENOBUFS]
    G -->|No| I[memcpy buffer, handle->path]
    I --> J[size = required_len, buffer NUL終端]
    J --> K[return 0]
```

## ビジネスルール

### 業務ルール

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

### 計算ロジック

特になし。

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

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

該当なし。

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

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

該当なし。

## パフォーマンス要件

- strlen + memcpyのみの軽量処理

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

- 特になし。

## 備考

- uv_fs_event_getpath()はsrc/uv-common.cに実装されている（プラットフォーム共通）
- uv_fs_poll_getpath()と同様のインターフェース設計

---

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

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

### 推奨読解順序

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

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | uv-common.c | `src/uv-common.c` | **L668-690**: uv_fs_event_getpath()の実装 |

**主要処理フロー**:
1. **L671-672**: buffer/size/sizeのNULLチェック
2. **L674-677**: アクティブチェック、非アクティブなら*size=0でUV_EINVAL
3. **L679**: required_len = strlen(handle->path)
4. **L680-683**: バッファサイズチェック、不足時はUV_ENOBUFS
5. **L685-687**: memcpy、*size設定、NULターミネート
6. **L689**: return 0

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

```
uv_fs_event_getpath()          [src/uv-common.c L668]
    |
    +-- uv__is_active()        [アクティブ判定]
    +-- strlen()               [パス長計算]
    +-- memcpy()               [パスコピー]
```

### データフロー図

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

uv_fs_event_t* handle  ──> パス長計算       ──> buffer (パス文字列)
char* buffer           ──> バッファサイズ判定 ──> *size (パス長)
size_t* size           ──> memcpyコピー     ──> return 0 or エラー
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダー | uv_fs_event_getpath()のAPI宣言 |
| uv-common.c | `src/uv-common.c` | ソース | getpath()のプラットフォーム共通実装 |
