# 画面設計書 24-ファイルシステム操作

## 概要

本ドキュメントは、libuvドキュメントサイトにおけるファイルシステム操作（`uv_fs_t`）APIリファレンスページの画面設計書である。非同期ファイルI/O操作に関する包括的なAPI定義を記載する。

### 本画面の処理概要

本ページは、libuvにおけるクロスプラットフォームの同期・非同期ファイルシステム操作のAPIリファレンスを提供する。ファイルのオープン、読み書き、コピー、削除、リネーム、ディレクトリ操作、パーミッション制御、シンボリックリンク操作等、広範なファイル操作をカバーする最大規模のAPIページである。

**業務上の目的・背景**：ファイルシステム操作はほぼ全てのアプリケーションで必要となる基本機能である。libuvはスレッドプール上でファイルI/O操作を非同期に実行し、イベントループをブロックしない設計を提供する。v1.45.0以降Linuxではio_uringによる高スループット化も可能である。本ページはこれら全てのファイル操作APIの完全なリファレンスである。

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

**主要な操作・処理内容**：
1. ファイルオープン・クローズ（`uv_fs_open` / `uv_fs_close`）のAPI仕様確認
2. ファイル読み書き（`uv_fs_read` / `uv_fs_write`）のAPI仕様確認
3. ファイルコピー・削除・リネーム等のAPI仕様確認
4. ディレクトリ操作（mkdir, rmdir, scandir, opendir, readdir等）のAPI仕様確認
5. ファイル情報取得（stat, fstat, lstat, statfs）のAPI仕様確認
6. パーミッション・所有者・タイムスタンプ変更のAPI仕様確認
7. シンボリックリンク・ハードリンク操作のAPI仕様確認
8. FSリクエスト情報取得関数群のAPI仕様確認
9. ファイルオープン定数（UV_FS_O_*）の確認
10. ヘルパー関数（uv_get_osfhandle等）の確認

**画面遷移**：
- 遷移元：APIドキュメント一覧（api.rst）
- 遷移先：リクエスト基底（request.rst）へのseealsoリンク、スレッドプール（threadpool.rst）への参照
- 関連：ファイルシステムガイド（guide/filesystem.rst）

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 96 | ファイルオープン・クローズ | 主機能 | uv_fs_open()/uv_fs_close()による非同期ファイルオープン・クローズのAPI定義 |
| 97 | ファイル読み書き | 主機能 | uv_fs_read()/uv_fs_write()による非同期ファイル読み書きのAPI定義 |
| 98 | ファイルコピー | 主機能 | uv_fs_copyfile()による非同期ファイルコピーのAPI定義 |
| 99 | ファイル削除 | 主機能 | uv_fs_unlink()による非同期ファイル削除のAPI定義 |
| 100 | ファイルリネーム | 主機能 | uv_fs_rename()による非同期ファイルリネームのAPI定義 |
| 101 | ファイル情報取得 | 主機能 | uv_fs_stat()/fstat()/lstat()によるファイルステータス情報取得のAPI定義 |
| 102 | ファイルシステム情報取得 | 主機能 | uv_fs_statfs()によるファイルシステム情報取得のAPI定義 |
| 103 | ディレクトリ操作 | 主機能 | uv_fs_mkdir()/rmdir()/mkdtemp()/mkstemp()によるディレクトリ操作のAPI定義 |
| 104 | ディレクトリ走査 | 主機能 | uv_fs_scandir()/opendir()/readdir()/closedir()によるディレクトリ走査のAPI定義 |
| 105 | ファイル権限変更 | 主機能 | uv_fs_chmod()/fchmod()によるパーミッション変更のAPI定義 |
| 106 | ファイル所有者変更 | 主機能 | uv_fs_chown()/fchown()/lchown()による所有者変更のAPI定義 |
| 107 | ファイルタイムスタンプ変更 | 主機能 | uv_fs_utime()/futime()/lutime()によるタイムスタンプ変更のAPI定義 |
| 108 | シンボリックリンク操作 | 主機能 | uv_fs_symlink()/readlink()/realpath()/link()によるリンク操作のAPI定義 |
| 109 | ファイル同期 | 主機能 | uv_fs_fsync()/fdatasync()によるディスク同期のAPI定義 |
| 110 | ファイルサイズ変更 | 主機能 | uv_fs_ftruncate()によるファイルサイズ変更のAPI定義 |
| 111 | ファイル転送 | 主機能 | uv_fs_sendfile()によるファイル間データ転送のAPI定義 |
| 112 | ファイルアクセス確認 | 主機能 | uv_fs_access()によるアクセス権確認のAPI定義 |
| 113 | FSリクエストクリーンアップ | 主機能 | uv_fs_req_cleanup()によるFSリクエストリソース解放のAPI定義 |
| 114 | FSリクエスト情報取得 | 主機能 | uv_fs_get_type()/result()/system_error()/ptr()/path()/statbuf()のAPI定義 |
| 163 | OSファイルハンドル変換 | 補助機能 | uv_get_osfhandle()/uv_open_osfhandle()によるネイティブハンドル変換のAPI定義 |

## 画面種別

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

## URL/ルーティング

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

## 入出力項目

| API関数 | パラメータ名 | 型 | 入出力 | 説明 |
|---------|-------------|-----|--------|------|
| uv_fs_open | loop | uv_loop_t* | 入力 | イベントループ |
| uv_fs_open | req | uv_fs_t* | 入出力 | FSリクエスト |
| uv_fs_open | path | const char* | 入力 | ファイルパス |
| uv_fs_open | flags | int | 入力 | オープンフラグ |
| uv_fs_open | mode | int | 入力 | ファイルモード |
| uv_fs_open | cb | uv_fs_cb | 入力 | 完了コールバック（NULLで同期実行） |
| uv_fs_read | bufs | const uv_buf_t[] | 入出力 | 読み取りバッファ |
| uv_fs_read | offset | int64_t | 入力 | 読み取り開始位置（-1で現在位置） |
| uv_fs_write | bufs | const uv_buf_t[] | 入力 | 書き込みバッファ |
| uv_fs_write | offset | int64_t | 入力 | 書き込み開始位置（-1で現在位置） |
| uv_fs_copyfile | flags | int | 入力 | EXCL/FICLONE/FICLONE_FORCEフラグ |
| uv_fs_stat | (返値) | uv_stat_t | 出力 | req->statbufにファイル情報格納 |
| uv_fs_scandir_next | ent | uv_dirent_t* | 出力 | ディレクトリエントリ |

## 表示項目

| セクション | 表示内容 | 説明 |
|-----------|---------|------|
| タイトル | File system operations | ページタイトル |
| 概要説明 | libuv provides a wide variety... | ファイル操作の概要と同期・非同期の説明 |
| note | io_uring対応 | v1.45.0以降のLinux io_uring対応に関する注記 |
| Data types | uv_fs_t, uv_timespec_t, uv_stat_t, uv_statfs_t等 | 全データ型定義 |
| Public members | loop, fs_type, path, result, statbuf, ptr | 公開メンバーフィールド |
| API | 約40関数 | ファイル操作の全API |
| Helper functions | uv_get_osfhandle, uv_open_osfhandle | ヘルパー関数 |
| File open constants | UV_FS_O_* 定数群 | ファイルオープン定数（約20個） |

## イベント仕様

### 1-非同期完了コールバック

全てのuv_fs_*関数はコールバック（`uv_fs_cb`）を受け取る。コールバックがNULLの場合は同期実行、非NULLの場合はスレッドプール上で非同期実行される。完了時にreq->resultに結果が格納される。

### 2-ディレクトリ走査イテレーション

`uv_fs_scandir`のコールバック呼び出し後、`uv_fs_scandir_next`を繰り返し呼んでディレクトリエントリを取得する。UV_EOFが返るまで繰り返す。

### 3-seealsoリンク遷移

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

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

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

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

## メッセージ仕様

| メッセージ種別 | 条件 | 内容 |
|--------------|------|------|
| note | Windows環境 | UTF-8エンコーディング使用に関する注意 |
| note | io_uring | v1.49.0でデフォルト無効化、UV_LOOP_USE_IO_URING_SQPOLLで有効化 |
| warning | UV_FS_O_FILEMAP使用時 | Windows非MSVC環境でのメモリマップ読み書き失敗時のクラッシュリスク |
| note | mkdir | Windowsでmodeパラメータ未実装 |
| note | chown系関数 | Windowsでは未実装 |
| warning | realpath | macOS/BSD/Windowsでのプラットフォーム固有の注意事項 |
| versionadded | 各API | 各APIが追加されたlibuvバージョン |

## 例外処理

| エラーコード | 発生条件 | 説明 |
|-------------|---------|------|
| UV_EEXIST | copyfileでEXCLフラグ使用時 | 宛先ファイルが既に存在する場合 |
| UV_ENOTSUP | FICLONE_FORCEでCoW非対応時 | プラットフォームがCopy-on-Writeをサポートしない場合 |
| UV_EOF | scandir_nextで終端到達時 | ディレクトリエントリの読み取り完了 |
| UV_ENOBUFS | getpath等でバッファ不足時 | バッファサイズが不足 |
| UV_EBADF | AIXでfsyncにて非通常ファイル指定時 | 非通常ファイルのファイルディスクリプタ |
| UV_ENOSYS | z/OSでlutime呼び出し時 | 未実装のプラットフォーム |
| UV_ELOOP | macOS/BSDでrealpath使用時 | 32以上のシンボリックリンク解決 |

## 備考

- 全ファイル操作はスレッドプール上で実行される（threadpool参照）
- コールバックにNULLを渡すと同期的に実行される
- v1.45.0以降Linuxでio_uringが利用可能だったが、v1.49.0でデフォルト無効化された
- uv_fs_req_cleanup()はリクエスト完了後に必ず呼び出す必要がある
- WindowsではUTF-8エンコーディングが使用される
- UV_FS_O_FILEMAPはWindowsのみサポート
- uv_fs_readdir()はスレッドセーフではない
- ファイルオープン定数（UV_FS_O_*）はプラットフォーム間の移植性を確保するために提供される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | uv_fs_t, uv_stat_t, uv_statfs_t, uv_dirent_t, uv_dir_t, uv_fs_type等の定義 |

**読解のコツ**: uv_fs_type列挙型でサポートされる全ファイル操作タイプを把握する。uv_stat_tはstruct statのポータブル版。

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

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | fs.c (Unix) | `src/unix/fs.c` | Unix系でのファイルシステム操作実装 |
| 3-2 | fs.c (Win) | `src/win/fs.c` | Windows系でのファイルシステム操作実装 |

**主要処理フロー**:
- 各`uv_fs_*`関数がリクエストを初期化し、スレッドプールにキュー投入
- スレッドプール上でPOSIX/Win32 APIを呼び出し
- 完了時にイベントループスレッドでコールバックを実行

#### Step 4: スレッドプール連携を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | threadpool.c | `src/threadpool.c` | スレッドプールでのワーク実行機構 |

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

```
uv_fs_open() [src/unix/fs.c or src/win/fs.c]
    |
    +-- [cb != NULL] uv__work_submit() [src/threadpool.c]
    |       |
    |       +-- uv__fs_work() [スレッドプール上で実行]
    |       |       +-- open() / CreateFileW()
    |       |
    |       +-- uv__fs_done() [イベントループスレッド]
    |               +-- uv_fs_cb() [ユーザーコールバック]
    |
    +-- [cb == NULL] 同期実行
            +-- open() / CreateFileW()

uv_fs_req_cleanup() [src/uv-common.c]
    +-- メモリ解放処理
```

### データフロー図

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

ファイルパス          uv_fs_open()
オープンフラグ             |
                    +------+------+
                    |             |
              [非同期]        [同期]
                    |             |
              スレッドプール   直接実行
              uv__fs_work()       |
                    |             |
              open()/CreateFileW()
                    |             |
              uv__fs_done()       |
                    |             |
              uv_fs_cb()     req->result
                    |
              req->result -------> ファイルディスクリプタ
                                   (< 0 でエラー)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| fs.rst | `docs/src/fs.rst` | テンプレート | ファイルシステム操作ページのSphinxソース |
| uv.h | `include/uv.h` | ソース | uv_fs_t等の公開API定義 |
| fs.c (Unix) | `src/unix/fs.c` | ソース | Unix系ファイルシステム操作実装 |
| fs.c (Win) | `src/win/fs.c` | ソース | Windows系ファイルシステム操作実装 |
| uv-common.c | `src/uv-common.c` | ソース | プラットフォーム共通処理 |
| threadpool.c | `src/threadpool.c` | ソース | スレッドプール実行基盤 |
| api.rst | `docs/src/api.rst` | テンプレート | API一覧ページ（遷移元） |
| request.rst | `docs/src/request.rst` | テンプレート | リクエスト基底ページ（参照先） |
| threadpool.rst | `docs/src/threadpool.rst` | テンプレート | スレッドプールページ（参照先） |
