# 帳票設計書 17-ファイルシステム統計情報

## 概要

本ドキュメントは、libuvライブラリが提供するファイルシステム統計情報取得機能（uv_fs_statfs）の帳票設計書である。

### 本帳票の処理概要

uv_fs_statfs() APIは、指定パスが存在するファイルシステムの統計情報（ブロックサイズ、総ブロック数、空きブロック数、ファイル数等）をuv_statfs_t構造体に出力する関数である。

**業務上の目的・背景**：ディスク容量の監視やファイル書き込み前の空き容量確認は、ストレージ管理において基本的な要件である。本APIはPOSIX statfs/statvfsに相当する機能をクロスプラットフォームで提供し、ファイルシステムレベルの統計情報を取得できる。Node.jsのfs.statfsはこのAPIを通じて実装される。

**帳票の利用シーン**：ディスク空き容量の確認、ファイル書き込み前の容量チェック、ディスク使用率監視ダッシュボード、ストレージアラート生成。

**主要な出力内容**：
1. ファイルシステムタイプ（f_type）
2. ブロックサイズ（f_bsize）
3. 総ブロック数（f_blocks）
4. 空きブロック数（f_bfree）
5. 利用可能ブロック数（f_bavail）
6. 総ファイル数（f_files）
7. 空きファイル数（f_ffree）
8. フラグメントサイズ（f_frsize）

**帳票の出力タイミング**：コールバック（cb）がNULLの場合は同期実行、非NULLの場合はスレッドプール上で非同期実行される。

**帳票の利用者**：Node.jsランタイム内部、ストレージ管理ツール開発者、アプリケーション開発者

## 帳票種別

構造体レポート（uv_statfs_t構造体出力型）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| N/A | C API呼び出し | N/A | uv_fs_statfs() 関数呼び出し |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | メモリ上の構造体（uv_statfs_t） |
| 用紙サイズ | N/A |
| 向き | N/A |
| ファイル名 | N/A（uv_fs_t.ptrに格納） |
| 出力方法 | uv_fs_tリクエスト構造体のptrフィールド |
| 文字コード | N/A |

## 帳票レイアウト

### レイアウト概要

uv_statfs_t（uv_statfs_s）構造体は10個のフィールドで構成される。

```
┌─────────────────────────────────────┐
│  uv_statfs_t                        │
├─────────────────────────────────────┤
│  f_type   : ファイルシステムタイプ    │
│  f_bsize  : ブロックサイズ           │
│  f_blocks : 総ブロック数             │
│  f_bfree  : 空きブロック数           │
│  f_bavail : 利用可能ブロック数       │
│  f_files  : 総ファイル数             │
│  f_ffree  : 空きファイル数           │
│  f_frsize : フラグメントサイズ       │
│  f_spare[3]: 予約領域               │
└─────────────────────────────────────┘
```

### ヘッダー部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| N/A | N/A | ヘッダー部は存在しない | N/A | N/A |

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 | 列幅 |
|----|-------|------|-------------|---------|-----|
| 1 | f_type | ファイルシステムタイプID | statfs/statvfs | uint64_t | 8バイト |
| 2 | f_bsize | 推奨I/Oブロックサイズ | statfs/statvfs | uint64_t | 8バイト |
| 3 | f_blocks | ファイルシステム内の総ブロック数 | statfs/statvfs | uint64_t | 8バイト |
| 4 | f_bfree | 空きブロック数 | statfs/statvfs | uint64_t | 8バイト |
| 5 | f_bavail | 非特権ユーザーが利用可能なブロック数 | statfs/statvfs | uint64_t | 8バイト |
| 6 | f_files | 総inode数 | statfs/statvfs | uint64_t | 8バイト |
| 7 | f_ffree | 空きinode数 | statfs/statvfs | uint64_t | 8バイト |
| 8 | f_frsize | フラグメントサイズ | statfs/statvfs | uint64_t | 8バイト |
| 9 | f_spare[3] | 予約領域（将来の拡張用） | N/A | uint64_t x3 | 24バイト |

### フッター部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| N/A | N/A | フッター部は存在しない | N/A | N/A |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| path | 対象パス | Yes |
| loop | イベントループ | Yes |
| cb | コールバック関数（NULLで同期実行） | No |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| N/A | N/A | 単一ファイルシステムの情報 |

### 改ページ条件

改ページは発生しない。

## データベース参照仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| N/A | ファイルシステムを直接参照 | N/A |

### テーブル別参照項目詳細

#### プラットフォーム別システムコール

| プラットフォーム | システムコール | 備考 |
|----------------|--------------|------|
| Linux/macOS/FreeBSD | statfs() | struct statfsを使用 |
| SunOS/MVS/NetBSD/Haiku/QNX | statvfs() | struct statvfsを使用 |
| Windows | src/win/fs.c独自実装 | GetDiskFreeSpaceExW等 |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| 総ディスク容量 | f_blocks * f_frsize | なし | アプリケーション側で計算 |
| 空きディスク容量 | f_bfree * f_frsize | なし | アプリケーション側で計算 |
| 利用可能容量 | f_bavail * f_frsize | なし | 非特権ユーザー向け |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[uv_fs_statfs 呼び出し] --> B{cbがNULL?}
    B -->|Yes 同期| C[uv__fs_statfs 直接呼び出し]
    B -->|No 非同期| D[スレッドプールにタスク投入]
    D --> E[ワーカースレッドでuv__fs_work実行]
    E --> C
    C --> F{プラットフォーム判定}
    F -->|statfs系| G[statfs 呼び出し]
    F -->|statvfs系| H[statvfs 呼び出し]
    G --> I[uv_statfs_t構造体にコピー]
    H --> I
    I --> J[uv__malloc でメモリ確保]
    J --> K[req->ptrに設定]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| UV_ENOENT | パスが存在しない | なし | req->resultに負のエラーコード |
| UV_ENOMEM | メモリ確保失敗 | なし | uv_statfs_tのmalloc失敗時にerrnoをENOMEMに設定 |
| 取得失敗 | statfs/statvfsの呼び出し失敗 | なし | -1を返却 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 1件（単一ファイルシステムの情報） |
| 目標出力時間 | ミリ秒オーダー |
| 同時出力数上限 | スレッドプールサイズに依存 |

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

ファイルシステムの統計情報はセキュリティ上の機密情報ではないが、ディスク使用率の変化を監視することで、データ書き込みパターンの推測が可能な場合がある。

## 備考

- uv_statfs_tはuv__malloc()で動的確保される。uv_fs_req_cleanup()でメモリが解放される。
- SunOS、MVS、NetBSD、Haiku、QNXではstatvfsを使用し、f_typeは0に設定される（未サポート）。
- OpenBSDではf_typeは0に設定される。
- f_spare[3]は将来の拡張用の予約領域である。

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | 1255-1265行目: uv_statfs_s構造体の定義。10フィールド（f_spare含む） |
| 1-2 | uv.h | `include/uv.h` | 257行目: uv_statfs_tのtypedef宣言 |

**読解のコツ**: uv_statfs_tの全フィールドはuint64_t型に統一されており、statfs/statvfsの型差異を吸収している。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | uv.h | `include/uv.h` | 1680行目: uv_fs_statfs()の宣言 |
| 2-2 | fs.c (unix) | `src/unix/fs.c` | 2294行目: uv_fs_statfs()のUnix実装。INIT(STATFS), PATH, POSTマクロ |

**主要処理フロー**:
1. **2294行目**: uv_fs_statfs関数定義開始
2. **2298行目**: INIT(STATFS)で初期化
3. **2299行目**: PATHでパスをコピー
4. **2300行目**: POSTで同期/非同期分岐

#### Step 3: 内部実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | fs.c (unix) | `src/unix/fs.c` | 675行目: uv__fs_statfs内部関数。statfs/statvfsの呼び出しとuv_statfs_tへの変換 |

**主要処理フロー**:
- **675行目**: uv__fs_statfs関数開始
- **684/688行目**: プラットフォームに応じてstatvfs/statfsを呼び出し
- **692行目**: uv__malloc()でuv_statfs_t構造体を動的確保
- **698-724行目**: プラットフォーム別のフィールドマッピング

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

```
uv_fs_statfs(loop, req, path, cb)
    │
    ├─ INIT(STATFS) → req初期化
    ├─ PATH → パスコピー
    └─ POST → uv__fs_work()
           │
           └─ uv__fs_statfs(req)
                  ├─ statfs(req->path, &buf) [Linux/macOS]
                  │   or statvfs(req->path, &buf) [SunOS等]
                  │
                  ├─ uv__malloc(sizeof(uv_statfs_t))
                  └─ フィールドコピー → req->ptr = stat_fs
```

### データフロー図

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

path         ───▶  statfs/statvfs呼び出し    ───▶  uv_statfs_t (動的確保)
uv_loop_t*          └─ struct statfs/statvfs        └─ req->ptr に格納
uv_fs_cb                └─ uv_statfs_tにコピー
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダー | uv_statfs_t構造体定義（1255行目）、API宣言（1680行目） |
| fs.c (unix) | `src/unix/fs.c` | ソース | Unix系実装（API: 2294行目、内部: 675行目） |
| fs.c (win) | `src/win/fs.c` | ソース | Windows実装 |
