# 機能設計書 66-パイプ名取得

## 概要

本ドキュメントは、パイプハンドルのソケット名・ピア名を取得する機能（`uv_pipe_getsockname()`/`uv_pipe_getpeername()`）の設計を記述する。

### 本機能の処理概要

バインド済みまたは接続済みのパイプハンドルから、ローカル側のパイプ名（getsockname）またはリモート側のパイプ名（getpeername）を取得する。

**業務上の目的・背景**：パイプの接続状態やバインド先の情報を実行時に取得するために使用される。ログ出力、デバッグ情報の収集、パイプのchmod操作時の名前解決などに必要である。

**機能の利用シーン**：接続済みパイプのリモート側名前の確認、バインド済みパイプのローカルパス取得、uv_pipe_chmod()内部でのパス名解決など。

**主要な処理内容**：
1. パラメータのバリデーション
2. getsockname()/getpeername()システムコール（Unix）またはNtQueryInformationFile()（Windows）の実行
3. 取得した名前のバッファへのコピー
4. Linuxの抽象ソケット名前空間の特別処理

**関連システム・外部連携**：Unix getsockname()/getpeername()、Windows NtQueryInformationFile(FileNameInformation)。

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 19 | パイプ | 主機能 | uv_pipe_getsockname()/uv_pipe_getpeername()によるパイプ名取得のAPI定義 |

## 機能種別

情報取得（パイプアドレス情報の取得）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| handle | const uv_pipe_t* | Yes | 名前を取得するパイプハンドル | バインド済みまたは接続済み |
| buffer | char* | Yes | 名前を格納するバッファ | NULLでないこと |
| size | size_t* | Yes | バッファサイズ（入出力） | NULLでなく、*size > 0 |

### 入力データソース

パイプハンドルの内部状態（OSソケット/パイプハンドル）。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | int | 成功時は0、バッファ不足時はUV_ENOBUFS、その他エラー時は負のエラーコード |
| buffer | char* | パイプ名が格納される（NUL終端、抽象ソケットを除く） |
| *size | size_t | 実際に書き込まれた名前の長さ |

### 出力先

呼び出し元が提供したバッファに名前が格納される。

## 処理フロー

### 処理シーケンス

```
1. パラメータバリデーション
   └─ buffer, size, *sizeのNULL/0チェック
2. OS関数呼び出し
   └─ Unix: getsockname()/getpeername() → sockaddr_unに格納
   └─ Windows: NtQueryInformationFile() → FileNameInformation
3. 名前の抽出とコピー
   └─ Unix: sun_pathからNUL終端位置を検出、抽象ソケットの特別処理
   └─ Windows: UTF-16からUTF-8への変換、pipe_prefixの付加
4. バッファサイズの確認と結果返却
   └─ バッファ不足の場合は必要サイズを*sizeに設定してUV_ENOBUFS
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{バリデーション}
    B -->|不正| C[return UV_EINVAL]
    B -->|OK| D[OS関数で名前取得]
    D --> E{成功?}
    E -->|No| F[return エラー]
    E -->|Yes| G{バッファ十分?}
    G -->|No| H[*size = 必要サイズ<br/>return UV_ENOBUFS]
    G -->|Yes| I[名前をバッファにコピー<br/>return 0]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 抽象ソケットの扱い | Linux抽象ソケットの場合、名前はNUL終端されず、*sizeにはNULバイトを含む長さが設定される | Linux環境で先頭が'\0'の場合 |
| BR-02 | 通常パスのNUL終端 | 抽象ソケット以外の場合、バッファにはNUL終端文字が付加される | 常に適用 |
| BR-03 | Windowsのパイププレフィックス | Windows版では`\\?\pipe`プレフィックスが付加される | Windows環境 |

### 計算ロジック

特になし。

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| UV_EINVAL | パラメータ不正 | buffer/sizeがNULL、*size==0 | パラメータ修正 |
| UV_ENOBUFS | バッファ不足 | バッファサイズが名前の長さに満たない | *sizeに必要サイズが設定されるので再割り当て |
| UV_EBADF | 不正なハンドル | ハンドルがバインド/接続されていない | ハンドルの状態を確認 |

### リトライ仕様

UV_ENOBUFSの場合、*sizeの値を使ってバッファを再割り当てし再呼び出し可能。

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

該当なし。

## パフォーマンス要件

OSのgetsockname()/getpeername()を含むが、O(1)で完了する。

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

特になし。

## 備考

- uv_pipe_getsockname()はuv__pipe_getsockpeername()にgetsockname関数ポインタを渡す共通実装
- uv_pipe_getpeername()は同様にgetpeername関数ポインタを渡す
- uv_pipe_chmod()内部でもgetsocknameが使用される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | L892-897: uv_pipe_getsockname()/uv_pipe_getpeername()の関数宣言 |
| 1-2 | pipe.c (Unix) | `src/unix/pipe.c` | L406-413: getsockname/getpeernameはuv__pipe_getsockpeername()のラッパー |
| 1-3 | pipe.c (Unix) | `src/unix/pipe.c` | L349-403: uv__pipe_getsockpeername()共通実装 |
| 1-4 | pipe.c (Win) | `src/win/pipe.c` | L2605-2639: Windows版getsockname/getpeername実装 |
| 1-5 | pipe.c (Win) | `src/win/pipe.c` | L2504-2595: uv__pipe_getname()共通実装 |

**主要処理フロー（Unix版共通関数 L349-403）**:
1. **364-365行目**: パラメータバリデーション
2. **367-376行目**: getsockname()/getpeername()呼び出し
3. **379-388行目**: 抽象ソケット判定とアドレス長の計算
4. **390-393行目**: バッファサイズ確認
5. **395-400行目**: 名前のコピーとNUL終端処理

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

```
uv_pipe_getsockname(handle, buffer, size)
    |
    +-- uv__pipe_getsockpeername(handle, getsockname, buffer, size)
            |
            +-- uv__getsockpeername()  [getsockname()ラッパー]
            +-- 名前の抽出・コピー

uv_pipe_getpeername(handle, buffer, size)
    |
    +-- uv__pipe_getsockpeername(handle, getpeername, buffer, size)
```

### データフロー図

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

const uv_pipe_t* handle -----> uv_pipe_getsockname() -------> buffer: パイプ名
char* buffer                    |                              *size: 名前長
size_t* size                    +-- getsockname()
                                +-- sockaddr_un解析
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダー | API宣言（L892-897） |
| pipe.c (Unix) | `src/unix/pipe.c` | ソース | Unix版実装（L349-413） |
| pipe.c (Win) | `src/win/pipe.c` | ソース | Windows版実装（L2504-2639） |
