# 画面設計書 29-その他ユーティリティ

## 概要

本ドキュメントは、libuvドキュメントサイトにおけるその他ユーティリティ（Miscellaneous utilities）APIリファレンスページの画面設計書である。バッファ操作、メモリ管理、時間取得、プロセス情報、環境変数、ネットワークアドレス変換など多岐にわたるユーティリティ関数のAPI定義を記載する。

### 本画面の処理概要

本ページは、libuvにおける他のカテゴリに分類されない各種ユーティリティ関数群のAPIリファレンスを提供する。システム情報の取得、プロセス管理、ネットワークアドレス変換、メモリ管理、時間取得、乱数生成、文字コード変換など、libuvの補助的な機能を広範に網羅する最大規模のAPIページの一つである。

**業務上の目的・背景**：クロスプラットフォームのアプリケーション開発では、OS固有の情報取得やシステム制御が必要であるが、プラットフォームごとにAPIが異なる。libuvは統一的なインターフェースでこれらの機能を提供し、移植性の高いコードの記述を可能にする。

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

**主要な操作・処理内容**：
1. バッファ初期化（`uv_buf_init`）のAPI仕様確認
2. カスタムアロケータ設定（`uv_replace_allocator`）のAPI仕様確認
3. ライブラリシャットダウン（`uv_library_shutdown`）のAPI仕様確認
4. IPアドレス変換（`uv_ip4_addr` / `uv_ip6_addr` / `uv_ip4_name` / `uv_ip6_name`等）のAPI仕様確認
5. ネットワークインターフェース情報取得のAPI仕様確認
6. CPU情報取得のAPI仕様確認
7. メモリ情報取得のAPI仕様確認
8. OS情報取得のAPI仕様確認
9. プロセス情報・制御のAPI仕様確認
10. 環境変数操作のAPI仕様確認
11. ユーザー/グループ情報取得のAPI仕様確認
12. 高精度時刻取得のAPI仕様確認
13. 乱数生成（`uv_random`）のAPI仕様確認
14. スリープ（`uv_sleep`）のAPI仕様確認
15. UTF-16/WTF-8文字コード変換のAPI仕様確認
16. デバッグ用ハンドル表示のAPI仕様確認

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

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 24 | ハンドルタイプ推定 | 主機能 | uv_guess_handle()によるFDからのハンドルタイプ推定のAPI定義 |
| 25 | デバッグ用ハンドル表示 | 主機能 | uv_print_all_handles()/print_active_handles()によるデバッグ出力のAPI定義 |
| 142 | IPアドレス変換 | 主機能 | uv_ip4_addr()/uv_ip6_addr()による文字列→sockaddr変換のAPI定義 |
| 143 | IPアドレス文字列化 | 主機能 | uv_ip4_name()/ip6_name()/ip_name()によるsockaddr→文字列変換のAPI定義 |
| 144 | inet変換 | 主機能 | uv_inet_ntop()/inet_pton()によるIPアドレスバイナリ・文字列間変換のAPI定義 |
| 145 | インターフェースアドレス取得 | 主機能 | uv_interface_addresses()/free_interface_addresses()のAPI定義 |
| 146 | インターフェース名変換 | 主機能 | uv_if_indextoname()/if_indextoiid()のAPI定義 |
| 147 | CPU情報取得 | 主機能 | uv_cpu_info()/free_cpu_info()によるCPU情報取得のAPI定義 |
| 148 | CPUマスクサイズ取得 | 主機能 | uv_cpumask_size()によるCPUマスクサイズ取得のAPI定義 |
| 149 | 利用可能並列度取得 | 主機能 | uv_available_parallelism()による並列処理数取得のAPI定義 |
| 150 | メモリ情報取得 | 主機能 | uv_get_free_memory()/total/constrained/available_memory()のAPI定義 |
| 151 | システム名取得 | 主機能 | uv_os_uname()によるOS情報取得のAPI定義 |
| 152 | ホスト名取得 | 主機能 | uv_os_gethostname()によるホスト名取得のAPI定義 |
| 153 | システム稼働時間取得 | 主機能 | uv_uptime()によるシステム稼働時間取得のAPI定義 |
| 154 | ロードアベレージ取得 | 主機能 | uv_loadavg()によるロードアベレージ取得のAPI定義 |
| 155 | リソース使用状況取得 | 主機能 | uv_getrusage()/getrusage_thread()によるリソース使用状況取得のAPI定義 |
| 156 | 常駐メモリサイズ取得 | 主機能 | uv_resident_set_memory()によるRSS取得のAPI定義 |
| 157 | PID取得 | 主機能 | uv_os_getpid()/getppid()によるプロセスID取得のAPI定義 |
| 158 | プロセス優先度制御 | 主機能 | uv_os_getpriority()/setpriority()によるプロセス優先度制御のAPI定義 |
| 159 | プロセスタイトル制御 | 主機能 | uv_setup_args()/get_process_title()/set_process_title()のAPI定義 |
| 160 | 実行ファイルパス取得 | 主機能 | uv_exepath()による実行ファイルパス取得のAPI定義 |
| 161 | 作業ディレクトリ制御 | 主機能 | uv_cwd()/chdir()によるカレントディレクトリ制御のAPI定義 |
| 162 | 標準入出力継承無効化 | 主機能 | uv_disable_stdio_inheritance()による子プロセスFD継承無効化のAPI定義 |
| 163 | OSファイルハンドル変換 | 主機能 | uv_get_osfhandle()/open_osfhandle()によるネイティブハンドル変換のAPI定義 |
| 164 | 環境変数一覧取得 | 主機能 | uv_os_environ()/free_environ()による全環境変数取得・解放のAPI定義 |
| 165 | 環境変数個別操作 | 主機能 | uv_os_getenv()/setenv()/unsetenv()による環境変数個別操作のAPI定義 |
| 166 | ホームディレクトリ取得 | 主機能 | uv_os_homedir()によるホームディレクトリ取得のAPI定義 |
| 167 | テンポラリディレクトリ取得 | 主機能 | uv_os_tmpdir()による一時ディレクトリ取得のAPI定義 |
| 168 | パスワード情報取得 | 主機能 | uv_os_get_passwd()/get_passwd2()/free_passwd()のAPI定義 |
| 169 | グループ情報取得 | 主機能 | uv_os_get_group()/free_group()によるグループ情報取得のAPI定義 |
| 170 | 高精度時刻取得 | 主機能 | uv_hrtime()によるナノ秒精度タイムスタンプ取得のAPI定義 |
| 171 | クロック時刻取得 | 主機能 | uv_clock_gettime()によるMONOTONIC/REALTIMEクロック取得のAPI定義 |
| 172 | 現在時刻取得 | 主機能 | uv_gettimeofday()によるマイクロ秒精度現在時刻取得のAPI定義 |
| 173 | スリープ | 主機能 | uv_sleep()による指定ミリ秒スリープのAPI定義 |
| 174 | 乱数生成 | 主機能 | uv_random()による暗号学的に安全な乱数生成のAPI定義 |
| 179 | システムエラー変換 | 補助機能 | uv_translate_sys_error()によるシステムエラーコード変換のAPI定義 |
| 181 | カスタムアロケータ設定 | 主機能 | uv_replace_allocator()によるメモリアロケータ置換のAPI定義 |
| 182 | ライブラリシャットダウン | 主機能 | uv_library_shutdown()による内部リソース解放のAPI定義 |
| 183 | バッファ初期化 | 主機能 | uv_buf_init()によるuv_buf_t構造体初期化のAPI定義 |
| 184 | UTF-16/WTF-8変換 | 主機能 | uv_utf16_to_wtf8()/wtf8_to_utf16()等の文字コード変換のAPI定義 |

## 画面種別

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

## URL/ルーティング

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

## 入出力項目

本ページには多数のAPI関数が含まれるため、代表的なものを記載する。

| API関数 | パラメータ名 | 型 | 入出力 | 説明 |
|---------|-------------|-----|--------|------|
| uv_buf_init | base | char* | 入力 | バッファの先頭ポインタ |
| uv_buf_init | len | unsigned int | 入力 | バッファサイズ |
| uv_ip4_addr | ip | const char* | 入力 | IPv4アドレス文字列 |
| uv_ip4_addr | port | int | 入力 | ポート番号 |
| uv_ip4_addr | addr | struct sockaddr_in* | 出力 | 変換結果 |
| uv_random | buf | void* | 出力 | 乱数格納バッファ |
| uv_random | buflen | size_t | 入力 | 乱数バイト数 |
| uv_os_getenv | name | const char* | 入力 | 環境変数名 |
| uv_os_getenv | buffer | char* | 出力 | 値格納バッファ |
| uv_os_getenv | size | size_t* | 入出力 | バッファサイズ/結果長 |

## 表示項目

| セクション | 表示内容 | 説明 |
|-----------|---------|------|
| タイトル | Miscellaneous utilities | ページタイトル |
| Data types | uv_buf_t, uv_file, uv_os_sock_t, uv_os_fd_t等 | 全データ型定義（約15種） |
| API | 約70関数 | ユーティリティ関数群 |
| String manipulation functions | UTF-16/WTF-8変換関数群 | 文字コード変換 |

## イベント仕様

### 1-乱数生成コールバック

`uv_random`で非同期実行時（cb!=NULL）、完了後にuv_random_cbが呼び出される。statusが非0の場合エラーを示す。同期実行時（loop=NULL, req=NULL）はコールバックなし。

### 2-デバッグ出力

`uv_print_all_handles` / `uv_print_active_handles` は指定ストリームにハンドル情報をテキスト出力する。出力フォーマットは `[flags] handle-type handle-address` 形式。

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

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

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

## メッセージ仕様

| メッセージ種別 | 条件 | 内容 |
|--------------|------|------|
| note | uv_buf_t | Windowsではlenフィールドがunsigned longである |
| warning | uv_replace_allocator | アロケータの複数回変更に対する保護なし、スレッドセーフである必要あり |
| warning | uv_library_shutdown | 一度だけ呼び出し、アクティブなループやリクエストがない状態で呼ぶこと |
| warning | uv_print_all_handles | デバッグ用でありAPI/ABI安定性保証なし |
| note | uv_loadavg | Windowsでは[0,0,0]を返す |
| note | uv_get_constrained_memory | 現在LinuxとzOSのみ非ゼロ値を返す |
| note | uv_os_homedir | スレッドセーフではない |
| note | uv_os_environ系 | スレッドセーフではない |
| warning | uv_os_homedir/tmpdir | スレッドセーフではない |

## 例外処理

| エラーコード | 発生条件 | 説明 |
|-------------|---------|------|
| UV_EINVAL | uv_replace_allocatorにNULLポインタ指定時 | 関数ポインタがNULL |
| UV_ENOBUFS | バッファサイズ不足時 | 各種get系関数でバッファ不足 |
| UV_ENOENT | 環境変数が存在しない時 | uv_os_getenvで未定義の変数 |

## 備考

- このページはlibuvの中で最も多くの関数を含むページの一つである
- uv_buf_tのbaseとlenのメンバー順序はプラットフォーム依存のため、uv_buf_init()で初期化すべき
- uv_hrtime()はナノ秒精度だが、全プラットフォームがナノ秒解像度をサポートするわけではない
- uv_random()はCSPRNG（暗号学的に安全な擬似乱数生成器）を使用する
- uv_sleep()はv1.34.0で追加
- 文字コード変換関数群はv1.47.0で追加
- uv_getrusage_thread()はv1.50.0で追加

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | uv_buf_t, uv_rusage_t, uv_cpu_info_t, uv_interface_address_t等の定義 |

**読解のコツ**: 多数のデータ型が定義されているため、使用するAPIに関連する型から読み進めるとよい。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | uv-common.c | `src/uv-common.c` | uv_buf_init, uv_replace_allocator等の共通実装 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | core.c (Unix) | `src/unix/core.c` | Unix系のOS情報取得、プロセス情報等 |
| 3-2 | core.c (Win) | `src/win/core.c` | Windows系のOS情報取得、プロセス情報等 |

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

```
uv_buf_init() [src/uv-common.c]
    +-- uv_buf_t構造体の初期化

uv_ip4_addr() [src/uv-common.c]
    +-- inet_pton() [標準ライブラリ]

uv_cpu_info() [src/unix/core.c or src/win/core.c]
    +-- [Linux] /proc/stat, /proc/cpuinfo読み取り
    +-- [macOS] sysctl()
    +-- [Win] GetSystemInfo() + NtQuerySystemInformation()

uv_random() [src/uv-common.c]
    +-- [同期] uv__random()
    |       +-- [Linux] getrandom(2)
    |       +-- [macOS] getentropy(2)
    |       +-- [Win] RtlGenRandom()
    +-- [非同期] uv_queue_work()
            +-- uv__random() [スレッドプール上]
```

### データフロー図

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

(なし)               uv_cpu_info()             --> uv_cpu_info_t[]
                                                    (CPU情報配列)

バッファ             uv_random()               --> 暗号学的乱数

環境変数名           uv_os_getenv()            --> 環境変数値

(なし)               uv_hrtime()               --> uint64_t
                                                    (ナノ秒タイムスタンプ)

IPv4文字列           uv_ip4_addr()             --> struct sockaddr_in
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| misc.rst | `docs/src/misc.rst` | テンプレート | ユーティリティページのSphinxソース |
| uv.h | `include/uv.h` | ソース | ユーティリティ関数の公開API定義 |
| uv-common.c | `src/uv-common.c` | ソース | プラットフォーム共通ユーティリティ実装 |
| core.c (Unix) | `src/unix/core.c` | ソース | Unix系OS情報取得等の実装 |
| core.c (Win) | `src/win/core.c` | ソース | Windows系OS情報取得等の実装 |
| random-devurandom.c | `src/unix/random-devurandom.c` | ソース | /dev/urandomベースの乱数実装 |
| random-getrandom.c | `src/unix/random-getrandom.c` | ソース | getrandom(2)ベースの乱数実装 |
| random-getentropy.c | `src/unix/random-getentropy.c` | ソース | getentropy(2)ベースの乱数実装 |
| api.rst | `docs/src/api.rst` | テンプレート | API一覧ページ（遷移元） |
