# 画面設計書 22-ファイルシステムイベント

## 概要

本ドキュメントは、libuvドキュメントサイトにおけるファイルシステムイベント（`uv_fs_event_t`）APIリファレンスページの画面設計書である。ファイルやディレクトリの変更を監視するためのAPI定義を網羅的に記載する。

### 本画面の処理概要

本ページは、libuvにおけるファイルシステムイベント監視機能のAPIリファレンスを提供する。ファイルのリネームや変更を検知するハンドルであり、各プラットフォームで最適なバックエンド（inotify、kqueue、FSEvents等）を使用する。

**業務上の目的・背景**：ファイルやディレクトリの変更をリアルタイムに検知する機能は、ファイル監視ツール、ホットリロード、ビルドシステム等で広く必要とされる。libuvはプラットフォームごとに異なるファイル監視メカニズムを抽象化し、統一APIを提供する。本ページはその利用方法を開発者に示す重要なリファレンスである。

**画面へのアクセス方法**：トップページからAPIドキュメント一覧（api.rst）を経由し、ファイルシステムイベントリンクをクリックして本ページに遷移する。

**主要な操作・処理内容**：
1. FSイベントハンドルの初期化（`uv_fs_event_init`）のAPI仕様確認
2. ファイル変更監視の開始（`uv_fs_event_start`）と停止（`uv_fs_event_stop`）のAPI仕様確認
3. 監視対象パスの取得（`uv_fs_event_getpath`）のAPI仕様確認
4. イベント種別（UV_RENAME、UV_CHANGE）の確認
5. 監視フラグ（UV_FS_EVENT_RECURSIVE等）の確認

**画面遷移**：
- 遷移元：APIドキュメント一覧（api.rst）
- 遷移先：ハンドル基底（handle.rst）へのseealsoリンク

**権限による表示制御**：なし（公開ドキュメント）

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 115 | FSイベント初期化 | 主機能 | uv_fs_event_init()によるFSイベントハンドル初期化のAPI定義 |
| 116 | FSイベント監視開始・停止 | 主機能 | uv_fs_event_start()/stop()によるファイル変更監視制御のAPI定義 |
| 117 | FSイベントパス取得 | 主機能 | uv_fs_event_getpath()による監視対象パス取得のAPI定義 |

## 画面種別

APIリファレンス（詳細表示）

## URL/ルーティング

`/docs/src/fs_event.rst` (Sphinx生成後: `/fs_event.html`)

## 入出力項目

| API関数 | パラメータ名 | 型 | 入出力 | 説明 |
|---------|-------------|-----|--------|------|
| uv_fs_event_init | loop | uv_loop_t* | 入力 | イベントループ |
| uv_fs_event_init | handle | uv_fs_event_t* | 出力 | 初期化されるFSイベントハンドル |
| uv_fs_event_start | handle | uv_fs_event_t* | 入力 | FSイベントハンドル |
| uv_fs_event_start | cb | uv_fs_event_cb | 入力 | 変更検知コールバック |
| uv_fs_event_start | path | const char* | 入力 | 監視対象パス |
| uv_fs_event_start | flags | unsigned int | 入力 | 監視フラグ（UV_FS_EVENT_RECURSIVE等） |
| uv_fs_event_stop | handle | uv_fs_event_t* | 入力 | 停止するハンドル |
| uv_fs_event_getpath | handle | uv_fs_event_t* | 入力 | FSイベントハンドル |
| uv_fs_event_getpath | buffer | char* | 出力 | パス格納バッファ |
| uv_fs_event_getpath | size | size_t* | 入出力 | バッファサイズ/結果長 |

## 表示項目

| セクション | 表示内容 | 説明 |
|-----------|---------|------|
| タイトル | `uv_fs_event_t` --- FS Event handle | ページタイトル |
| 概要説明 | FS Event handles allow... | FSイベントハンドルの概要 |
| note | AIX/z/OSの制限事項 | プラットフォーム固有の制約 |
| Data types | uv_fs_event_t, uv_fs_event_cb, uv_fs_event, uv_fs_event_flags | データ型の定義 |
| Public members | N/A | 固有の公開メンバーなし |
| API | 4関数（init, start, stop, getpath） | ファイル監視の全API |

## イベント仕様

### 1-ファイル変更検知コールバック

`uv_fs_event_start`で登録したコールバック（`uv_fs_event_cb`）が、監視対象のファイル/ディレクトリに変更が発生した際に呼び出される。コールバックにはファイル名、イベント種別（UV_RENAME/UV_CHANGE）、ステータスが渡される。

### 2-seealsoリンク遷移

ページ末尾の「See also」セクションから `uv_handle_t` の基底APIリファレンスページへ遷移する。

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

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

該当なし（本プロジェクトはCライブラリであり、データベースは使用しない）

## メッセージ仕様

| メッセージ種別 | 条件 | 内容 |
|--------------|------|------|
| note | AIX環境 | bos.ahafsパッケージの要件とスレッドセーフティに関する注意 |
| note | z/OS環境 | ディレクトリ監視時のファイル作成/削除非通知に関する注意 |
| note | FreeBSD環境 | カーネルバグによりpathがNULLになる場合がある |
| note | UV_FS_EVENT_RECURSIVEフラグ | 現在OSXとWindowsのみサポート |
| note | macOS | start呼び出し直前のイベントが報告される場合がある |
| versionchanged | uv_fs_event_getpath | v1.3.0/v1.9.0でのバッファ動作変更 |

## 例外処理

| エラーコード | 発生条件 | 説明 |
|-------------|---------|------|
| UV_ENOBUFS | バッファサイズ不足時 | uv_fs_event_getpath()でバッファが小さい場合 |
| 負のstatus | ファイルアクセス不可時 | コールバック内でstatusが負値の場合 |

## 備考

- UV_FS_EVENT_WATCH_ENTRYとUV_FS_EVENT_STATフラグは現時点でどのバックエンドでも未実装
- UV_FS_EVENT_RECURSIVEはOSXとWindowsのみサポート
- AIXではahafsインフラストラクチャの制限がある
- FreeBSDではカーネルバグによりpathがNULLになることがある

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | uv_fs_event_t, uv_fs_event_cb, uv_fs_event, uv_fs_event_flagsの定義 |

**読解のコツ**: uv_fs_eventとuv_fs_event_flagsの列挙型の値（UV_RENAME=1, UV_CHANGE=2等）を確認する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | fs_event.rst | `docs/src/fs_event.rst` | ドキュメントのソースと構造 |

#### Step 3: プラットフォーム固有実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | linux.c | `src/unix/linux.c` | Linux（inotify）でのFSイベント実装 |
| 3-2 | kqueue.c | `src/unix/kqueue.c` | macOS/BSD（kqueue）でのFSイベント実装 |
| 3-3 | aix.c | `src/unix/aix.c` | AIX（ahafs）でのFSイベント実装 |
| 3-4 | sunos.c | `src/unix/sunos.c` | Solaris（port events）でのFSイベント実装 |
| 3-5 | fs-event.c | `src/win/fs-event.c` | WindowsでのFSイベント実装 |
| 3-6 | no-fsevents.c | `src/unix/no-fsevents.c` | FSイベント非対応プラットフォームのスタブ |

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

```
uv_fs_event_init() [プラットフォーム固有]
    |
    +-- uv__handle_init() [ハンドル共通初期化]

uv_fs_event_start() [プラットフォーム固有]
    |
    +-- [Linux] inotify_add_watch()
    +-- [macOS/BSD] kqueue + kevent()
    +-- [Windows] ReadDirectoryChangesW()
    +-- [AIX] ahafs監視登録

uv_fs_event_stop() [プラットフォーム固有]
    |
    +-- [Linux] inotify_rm_watch()
    +-- [macOS/BSD] kevent() で監視解除
    +-- [Windows] CancelIo()

uv_fs_event_getpath() [プラットフォーム固有]
    +-- ハンドル内部に保存されたパスを返却
```

### データフロー図

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

監視対象パス ---------> uv_fs_event_start()
                              |
                              v
                    カーネルファイル監視
                    (inotify/kqueue等)
                              |
                              v
ファイル変更イベント --> uv_fs_event_cb() -------> アプリケーション通知
                        (filename, events,        (UV_RENAME/UV_CHANGE)
                         status)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| fs_event.rst | `docs/src/fs_event.rst` | テンプレート | FSイベントページのSphinxソース |
| uv.h | `include/uv.h` | ソース | uv_fs_event_t等の公開API定義 |
| linux.c | `src/unix/linux.c` | ソース | Linux(inotify)でのFSイベント実装 |
| kqueue.c | `src/unix/kqueue.c` | ソース | macOS/BSD(kqueue)でのFSイベント実装 |
| aix.c | `src/unix/aix.c` | ソース | AIXでのFSイベント実装 |
| os390.c | `src/unix/os390.c` | ソース | z/OSでのFSイベント実装 |
| sunos.c | `src/unix/sunos.c` | ソース | SolarisでのFSイベント実装 |
| no-fsevents.c | `src/unix/no-fsevents.c` | ソース | 非対応プラットフォームのスタブ |
| fs-event.c | `src/win/fs-event.c` | ソース | WindowsでのFSイベント実装 |
| api.rst | `docs/src/api.rst` | テンプレート | API一覧ページ（遷移元） |
| handle.rst | `docs/src/handle.rst` | テンプレート | ハンドル基底ページ（参照先） |
