# 58P03 — file_name_too_long

> PostgreSQL SQLSTATE 58P03 的源码核验与诊断参考。
---

# 58P03

## 速览 {#at-a-glance}

`58P03` 由 PostgreSQL 文件访问 errno 辅助函数在保存的 OS errno 为 `ENAMETOOLONG` 时选择。它不是固定的 `file name too long` 主消息；调用者提供带 `%m` 的消息，辅助函数提供 SQLSTATE。

<!-- BEGIN SQLSTATE FACTS: generated by scripts/generate.py; do not edit -->

| 字段 | 值 |
| --- | --- |
| SQLSTATE | `58P03` |
| 条件名 | `file_name_too_long` |
| 状态 | `有效` |
| 已知存在于 | `18.0` |
| 锁定快照 | `18.6, 19beta3` |
| 宏 | `ERRCODE_FILE_NAME_TOO_LONG` |
| 别名 | `—` |

<!-- source facts: data/errcodes/58P03.json -->
<!-- END SQLSTATE FACTS -->

## 含义 {#meaning}

`errcode_for_file_access()` 将 `ENAMETOOLONG` 映射为 `ERRCODE_FILE_NAME_TOO_LONG`。同一完整 switch 还把 `ENOENT` 映射为 `58P01`、`EEXIST` 映射为 `58P02`、`ENOSPC` 映射为 `53100`、`EIO` 映射为 `58030`，其他 errno 可能落到别的代码。辅助函数明确要求调用者的主消息保留 `%m`，所以 OS 文本和 locale（区域设置）是诊断的一部分。

18.6 固定后端调用者包括 base backup 的 `could not access directory "%s": %m` 和表空间的 `could not set permissions on directory "%s": %m`；两者先以 `ERROR` 发出，再由辅助函数选择代码。这说明实际操作上下文很重要：同一 SQLSTATE 可以来自不同文件操作，其他调用者的文件名过长也可能使用不同主消息模板。

## 消息 {#messages}

- **ERROR**，base backup 代表主消息：`could not access directory "%s": %m`。
- **ERROR**，表空间代表主消息：`could not set permissions on directory "%s": %m`。
- `%m` 展开为保存的 OS 错误文本；若 errno 是 `ENAMETOOLONG`，`errcode_for_file_access()` 提供 SQLSTATE `58P03`。

本次核验没有找到脱离调用者的固定 `58P03` 主消息。不要把 `%m` 换成臆造的英文句子，也不要仅凭条件名推断扩展报文。

## 诊断 {#diagnosis}

保留完整主消息/详细信息/上下文、操作和组件、完整路径、OS errno、文件系统限制、编码及 PostgreSQL 对象名映射。区分文件系统组件长度限制与 PostgreSQL 标识符限制，也要区分辅助函数的 `ENAMETOOLONG` 分支和 `ENOENT`、`EEXIST`、磁盘满、I/O 分支。固定源码确认的是辅助函数与代表调用者，不声称在特定主机自然复现。

## 处理 {#response}

使用组件和文件系统接受的路径/名称，或移动目标并保留持久映射。客户端 `ERROR` 若发生在显式事务中，继续执行前必须 `ROLLBACK` 或回到已有保存点；修正路径后重试受影响操作，不要继续发送无关语句。启动/后台调用可能没有客户端事务；后端已终止时使用新连接。上报时保留原始 OS 详细信息。

## 版本 {#versions}

锁定目录从 18.0 记录 `58P03`；固定辅助函数与调用者来自 PostgreSQL 18.6。本页仅源码复核，没有自然运行声明。

## 相关 {#related}

[`58P01`](../58p01/)、[`58P02`](../58p02/)、[`58030`](../58030/)

## 来源 {#sources}

[`src/backend/utils/error/elog.c#L867-L942`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/error/elog.c#L867)

[`src/backend/backup/basebackup_server.c#L119-L124`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/backup/basebackup_server.c#L119)

[`src/backend/commands/tablespace.c#L606-L618`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/commands/tablespace.c#L606)

结构化[证据记录](../../data/evidence/58p03.json)保存 errno 映射、代表主消息与源码/运行边界。