# 画面設計書 27-共有ライブラリ

## 概要

本ドキュメントは、libuvドキュメントサイトにおける共有ライブラリ（`uv_lib_t`）APIリファレンスページの画面設計書である。動的ライブラリの読み込み・シンボル検索機能のAPI定義を記載する。

### 本画面の処理概要

本ページは、libuvにおけるクロスプラットフォームの動的ライブラリ操作APIリファレンスを提供する。共有ライブラリの読み込み、シンボル検索、閉じる操作、エラー取得の4つのAPIを定義する。

**業務上の目的・背景**：プラグインシステムや動的拡張機能の実装には、実行時に共有ライブラリ（.so/.dylib/.dll）を読み込んでシンボルを解決する必要がある。libuvはdlopen/dlsym（POSIX）とLoadLibrary/GetProcAddress（Windows）を統一的に抽象化するAPIを提供する。

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

**主要な操作・処理内容**：
1. 動的ライブラリの読み込み（`uv_dlopen`）のAPI仕様確認
2. 動的ライブラリの閉じる（`uv_dlclose`）のAPI仕様確認
3. シンボル検索（`uv_dlsym`）のAPI仕様確認
4. エラー取得（`uv_dlerror`）のAPI仕様確認

**画面遷移**：
- 遷移元：APIドキュメント一覧（api.rst）

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 139 | 動的ライブラリ読み込み | 主機能 | uv_dlopen()/uv_dlclose()による動的ライブラリ読み込み・解放のAPI定義 |
| 140 | シンボル検索 | 主機能 | uv_dlsym()による動的ライブラリからのシンボル検索のAPI定義 |
| 141 | エラー取得 | 主機能 | uv_dlerror()による動的ライブラリ操作エラー取得のAPI定義 |

## 画面種別

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

## URL/ルーティング

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

## 入出力項目

| API関数 | パラメータ名 | 型 | 入出力 | 説明 |
|---------|-------------|-----|--------|------|
| uv_dlopen | filename | const char* | 入力 | ライブラリファイル名（UTF-8） |
| uv_dlopen | lib | uv_lib_t* | 出力 | ライブラリハンドル |
| uv_dlclose | lib | uv_lib_t* | 入力 | 閉じるライブラリハンドル |
| uv_dlsym | lib | uv_lib_t* | 入力 | ライブラリハンドル |
| uv_dlsym | name | const char* | 入力 | シンボル名 |
| uv_dlsym | ptr | void** | 出力 | シンボルへのポインタ |
| uv_dlerror | lib | const uv_lib_t* | 入力 | ライブラリハンドル |
| uv_dlerror | (返値) | const char* | 出力 | エラーメッセージ文字列 |

## 表示項目

| セクション | 表示内容 | 説明 |
|-----------|---------|------|
| タイトル | Shared library handling | ページタイトル |
| 概要説明 | libuv provides cross platform utilities... | 共有ライブラリ操作の概要 |
| Data types | uv_lib_t | データ型の定義 |
| Public members | N/A | 固有の公開メンバーなし |
| API | 4関数（dlopen, dlclose, dlsym, dlerror） | 動的ライブラリ操作の全API |

## イベント仕様

本ページの関数はすべて同期的に実行される。非同期コールバックやイベントは存在しない。

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

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

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

## メッセージ仕様

該当なし（本ページには特別なnoteやwarningは存在しない）

## 例外処理

| エラーコード | 発生条件 | 説明 |
|-------------|---------|------|
| -1 | uv_dlopen失敗時 | ライブラリのオープンに失敗（uv_dlerrorでメッセージ取得） |
| -1 | uv_dlsymでシンボル未発見時 | 指定シンボルが見つからない |

## 備考

- filenameパラメータはUTF-8エンコーディングで指定する
- uv_dlsymでシンボルがNULLにマッピングされることは正当な動作である
- エラー情報はuv_dlerror()で最後のuv_dlopen()/uv_dlsym()のエラーメッセージを取得する
- 返値は0が成功、-1が失敗（一般的なlibuvのエラーコード体系とは異なる）

---

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

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

### 推奨読解順序

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

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

**読解のコツ**: uv_lib_tはプラットフォーム依存の構造体であり、内部にdlopen()のハンドルやLoadLibrary()のHMODULEを保持する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | dl.c (Unix) | `src/unix/dl.c` | Unix系のdlopen/dlsym/dlclose/dlerror呼び出し |
| 2-2 | dl.c (Win) | `src/win/dl.c` | Windows系のLoadLibrary/GetProcAddress呼び出し |

**主要処理フロー**:
- `uv_dlopen()`: [Unix] dlopen() / [Win] LoadLibraryExW()
- `uv_dlsym()`: [Unix] dlsym() / [Win] GetProcAddress()
- `uv_dlclose()`: [Unix] dlclose() / [Win] FreeLibrary()
- `uv_dlerror()`: [Unix] dlerror() / [Win] FormatMessage()

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

```
uv_dlopen() [src/unix/dl.c or src/win/dl.c]
    |
    +-- [Unix] dlopen()
    +-- [Win] LoadLibraryExW()

uv_dlsym() [src/unix/dl.c or src/win/dl.c]
    |
    +-- [Unix] dlsym()
    +-- [Win] GetProcAddress()

uv_dlclose() [src/unix/dl.c or src/win/dl.c]
    |
    +-- [Unix] dlclose()
    +-- [Win] FreeLibrary()

uv_dlerror() [src/unix/dl.c or src/win/dl.c]
    +-- 内部に保存されたエラーメッセージを返却
```

### データフロー図

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

ファイル名 ----------> uv_dlopen() ---------> uv_lib_t (ハンドル)
                                                  |
シンボル名 ----------> uv_dlsym() ----------> void* (ポインタ)
                                                  |
                       uv_dlclose() --------> リソース解放

エラー発生時 --------> uv_dlerror() --------> エラーメッセージ文字列
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| dll.rst | `docs/src/dll.rst` | テンプレート | 共有ライブラリページのSphinxソース |
| uv.h | `include/uv.h` | ソース | uv_lib_tの公開API定義 |
| dl.c (Unix) | `src/unix/dl.c` | ソース | Unix系動的ライブラリ操作実装 |
| dl.c (Win) | `src/win/dl.c` | ソース | Windows系動的ライブラリ操作実装 |
| api.rst | `docs/src/api.rst` | テンプレート | API一覧ページ（遷移元） |
