# 機能設計書 99-ファイル削除

## 概要

本ドキュメントは、libuvにおけるファイル削除機能（uv_fs_unlink）の設計仕様を記述する。指定パスのファイルを非同期で削除する機能である。

### 本機能の処理概要

**業務上の目的・背景**：ファイルの削除はファイル管理の基本操作である。一時ファイルの後始末、古いログファイルの削除、ファイルの入れ替え処理などで使用される。libuvはイベントループと統合された非同期ファイル削除APIを提供し、ブロッキングを回避した効率的なファイル操作を可能にする。

**機能の利用シーン**：一時ファイルの削除、ファイルのローテーション処理、キャッシュファイルのクリーンアップ、ファイルコピー失敗時のクリーンアップ（uv__fs_copyfile内部）などで利用される。

**主要な処理内容**：
1. ファイルパスを設定する
2. 非同期モードではスレッドプールで実行する
3. POSIX unlink()システムコールを呼び出す
4. Linux io_uring対応環境ではio_uringで高速処理する

**関連システム・外部連携**：POSIX unlink()システムコール、Linux io_uring。

**権限による制御**：ファイルが存在するディレクトリへの書き込み権限が必要。ファイル自体の権限は不要（ディレクトリのスティッキービット設定時を除く）。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 24 | ファイルシステム操作 | 主機能 | uv_fs_unlink()による非同期ファイル削除のAPI定義 |

## 機能種別

ファイルI/O操作

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| loop | uv_loop_t* | Yes | イベントループ | NULLでないこと |
| req | uv_fs_t* | Yes | ファイルシステムリクエスト | NULLでないこと |
| path | const char* | Yes | 削除するファイルのパス | NULLでないこと |
| cb | uv_fs_cb | No | 完了コールバック（NULLの場合は同期実行） | - |

### 入力データソース

呼び出し元コードから直接パラメータとして渡される。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値（同期） | int | 成功時は0、失敗時は負のエラーコード |
| 戻り値（非同期） | int | 常に0（リクエスト投入成功） |
| req->result | ssize_t | コールバック内で参照。0または負のエラーコード |

### 出力先

呼び出し元への戻り値。ファイルシステムから指定ファイルが削除される。

## 処理フロー

### 処理シーケンス

```
1. INITマクロでリクエスト構造体を初期化する（UV_FS_UNLINK）
2. PATHマクロでパスを設定する（非同期時はコピー）
3. [非同期] io_uring対応の場合はuv__iou_fs_unlink()で高速パスを試行
4. POSTマクロでスレッドプールに投入/同期実行
5. uv__fs_work()がunlink(req->path)を呼び出す
6. 結果をreq->resultに格納する
7. [非同期] コールバックを呼び出す
```

### フローチャート

```mermaid
flowchart TD
    A[uv_fs_unlink] --> B[INIT UNLINK]
    B --> C[PATH設定]
    C --> D{非同期?}
    D -->|Yes| E{io_uring?}
    E -->|Yes| F[io_uringパス]
    E -->|No| G[スレッドプール投入]
    D -->|No| H[unlink syscall直接実行]
    G --> H
    H --> I{成功?}
    I -->|Yes| J[return 0]
    I -->|No| K[return UV_ERR]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-99-1 | ディレクトリ不可 | unlink()はディレクトリの削除には使用できない。ディレクトリにはuv_fs_rmdir()を使用する | 常時 |
| BR-99-2 | リンクカウント | ファイルのリンクカウントが0になった場合のみ実際にデータが削除される | ハードリンクが存在する場合 |
| BR-99-3 | io_uring高速パス | Linux環境でio_uring対応の場合、スレッドプールをバイパスして処理する | Linux, 非同期モード |

### 計算ロジック

特になし。

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| UV_EINVAL | 不正パラメータ | reqがNULL | 有効なリクエストを渡す |
| UV_ENOENT | 不存在 | 指定パスのファイルが存在しない | パスを確認する |
| UV_EACCES | アクセス拒否 | ディレクトリへの書き込み権限がない | 権限を確認する |
| UV_EPERM | 操作不許可 | スティッキービットが設定されたディレクトリで所有者以外が削除 | 権限を確認する |
| UV_EISDIR | ディレクトリ | パスがディレクトリを指している | uv_fs_rmdir()を使用する |
| UV_ECANCELED | キャンセル | uv_cancel()によるキャンセル | 再試行する |

### リトライ仕様

EINTRによるリトライはuv__fs_work()のdo-whileで自動的に行われる。

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

該当なし。

## パフォーマンス要件

- 同期モード：システムコール1回分の遅延
- 非同期モード：スレッドプールのワーカースレッド数に依存
- io_uring利用時：カーネルレベルの非同期削除

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

- ファイル削除はディレクトリの書き込み権限で制御される
- スティッキービットが設定されたディレクトリ（例：/tmp）では追加の権限チェックが適用される

## 備考

- uv_fs_unlink()はシンボリックリンク自体を削除する（リンク先は削除しない）
- ディレクトリの削除にはuv_fs_rmdir()を使用する
- 内部的にはuv__fs_copyfile()のエラー時クリーンアップでも使用される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | API宣言（1487-1490行目） |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | fs.c | `src/unix/fs.c` | uv_fs_unlink()（2183-2189行目）。INIT/PATH/io_uring/POST |

**主要処理フロー**:
- **2184行目**: `INIT(UNLINK)` - UV_FS_UNLINKとして初期化
- **2185行目**: `PATH` - パスの設定
- **2186-2188行目**: io_uring高速パスの試行

#### Step 3: ディスパッチャーを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | fs.c | `src/unix/fs.c` | uv__fs_work()（1732行目）。`X(UNLINK, unlink(req->path))` |

**主要処理フロー**:
- **1732行目**: `unlink(req->path)` - POSIX unlink()の直接呼び出し

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

```
uv_fs_unlink(loop, req, path, cb)
    |
    +-- INIT(UNLINK)
    +-- PATH
    +-- [非同期] uv__iou_fs_unlink() or POST
    |       +-- uv__fs_work()
    |               +-- unlink(req->path)
    +-- [同期] uv__fs_work() → return req->result
```

### データフロー図

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

const char* path ───> unlink() syscall  ───> 0 or error
                      io_uring (Linux)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダー | API宣言 |
| fs.c | `src/unix/fs.c` | ソース | Unix系のunlink実装 |
| fs.c | `src/win/fs.c` | ソース | Windows版の削除実装 |
