netdb
netdb 提供网络数据库查询功能，支持主机名与服务名到 socket 地址的解析、socket 地址到主机名与服务名的反向解析，以及相关错误信息获取。
头文件清单
接口清单
| 接口名称 | 功能简述 |
|---|---|
| getaddrinfo | 将主机名和服务名转换为 socket 地址信息 |
| freeaddrinfo | 释放 getaddrinfo 申请的 addrinfo 结构体链表内存 |
| getnameinfo | 将 socket 地址转换为主机名和服务名 |
| gai_strerror | 获取 getaddrinfo 错误码对应的描述字符串 |
Functions
getaddrinfo
int getaddrinfo (const char *__restrict, const char *__restrict, const struct addrinfo *__restrict, struct addrinfo **__restrict)
头文件清单
功能说明
- 将主机名和服务名转换为 socket 地址信息
- 根据 hints 参数中指定的地址族、套接字类型和协议等条件，返回一个或多个 addrinfo 结构体链表
- 返回的 addrinfo 结构体链表需要由调用者通过 freeaddrinfo 释放
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| - | const char *__restrict | 主机名或地址字符串 | NULL 或合法主机名字符串 |
| - | const char *__restrict | 服务名或端口号字符串 | NULL 或合法端口号字符串 |
| - | const struct addrinfo *__restrict | 输入条件提示结构体，指定地址族、套接字类型等过滤条件 | NULL 或指向struct addrinfo结构体的指针 |
出参
| 名称 | 数据类型 | 输出说明 |
|---|---|---|
| - | struct addrinfo **__restrict | 返回的 addrinfo 结构体链表头指针，需调用 freeaddrinfo 释放 |
返回值
- 返回类型：int
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| 0 | 成功 | 主机名和服务名解析成功 |
| EAI_BADFLAGS(-1) | 标志位无效 | hints 的 ai_flags 包含无效值 |
| EAI_NONAME(-2) | 名称无法解析 | 主机名或服务名无法解析 |
| EAI_AGAIN(-3) | 临时失败 | 名称解析临时失败，可重试 |
| EAI_FAIL(-4) | 永久失败 | 名称解析永久失败 |
| EAI_NODATA(-5) | 无地址数据 | 指定的主机名无对应地址 |
| EAI_FAMILY(-6) | 地址族不支持 | hints 的 ai_family 不被支持 |
| EAI_SOCKTYPE(-7) | 套接字类型不支持 | hints 的 ai_socktype 不被支持 |
| EAI_SERVICE(-8) | 服务不支持 | 指定套接字类型下服务名不可用 |
| EAI_MEMORY(-10) | 内存分配失败 | 系统内存不足 |
| EAI_SYSTEM(-11) | 系统错误 | 系统调用返回错误，可查看 errno |
| EAI_OVERFLOW(-12) | 缓冲区溢出 | 参数缓冲区长度不足 |
freeaddrinfo
头文件清单
功能说明
- 释放 getaddrinfo 函数申请的 addrinfo 结构体链表内存空间
- 遍历链表中所有 addrinfo 节点并逐个释放
- 释放后指针不应再被引用
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| - | struct addrinfo * | 指向 getaddrinfo 返回的 addrinfo 链表头指针 | NULL 或 getaddrinfo 返回的有效指针 |
getnameinfo
int getnameinfo (const struct sockaddr *__restrict, socklen_t, char *__restrict, socklen_t, char *__restrict, socklen_t, int)
头文件清单
功能说明
- 将 socket 地址转换为主机名和服务名
- 根据 flags 参数控制转换行为，支持返回数字形式或名称形式的地址和服务
- 独立于协议的地址到名称转换接口
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| - | const struct sockaddr *__restrict | 待转换的 socket 地址结构体指针 | 非 NULL 指针 |
| - | socklen_t | socket 地址结构体的长度 | 大于 0 |
| - | int | 控制转换行为的标志位 | NI_NUMERICHOST(0x01) / NI_NUMERICSERV(0x02) / NI_NOFQDN(0x04) / NI_NAMEREQD(0x08) / NI_DGRAM(0x10) / NI_NUMERICSCOPE(0x100) |
出参
| 名称 | 数据类型 | 输出说明 |
|---|---|---|
| - | char *__restrict | 转换后的主机名字符串 |
| - | char *__restrict | 转换后的服务名字符串 |
返回值
- 返回类型：int
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| 0 | 成功 | socket 地址转换成功 |
| EAI_BADFLAGS(-1) | 标志位无效 | flags 参数包含无效值 |
| EAI_NONAME(-2) | 名称无法解析 | 主机名或服务名无法解析且未设置 NI_NAMEREQD |
| EAI_AGAIN(-3) | 临时失败 | 名称解析临时失败，可重试 |
| EAI_FAIL(-4) | 永久失败 | 名称解析永久失败 |
| EAI_FAMILY(-6) | 地址族不支持 | socket 地址的地址族不被支持 |
| EAI_SOCKTYPE(-7) | 套接字类型不支持 | 指定套接字类型不可用 |
| EAI_OVERFLOW(-12) | 缓冲区溢出 | 输出缓冲区长度不足 |
gai_strerror
头文件清单
功能说明
- 获取 getaddrinfo 返回的错误码对应的描述字符串
- 返回指向静态字符串的指针，无需调用者释放
- 用于诊断 getaddrinfo 调用失败的原因
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| - | int | getaddrinfo 返回的错误码 | EAI_BADFLAGS(-1) / EAI_NONAME(-2) / EAI_AGAIN(-3) / EAI_FAIL(-4) / EAI_NODATA(-5) / EAI_FAMILY(-6) / EAI_SOCKTYPE(-7) / EAI_SERVICE(-8) / EAI_MEMORY(-10) / EAI_SYSTEM(-11) / EAI_OVERFLOW(-12) |
返回值
- 返回类型：const char *
| 返回值 | 文字含义 | 触发场景 |
|---|---|---|
| 非 NULL | 错误码对应的描述字符串 | 任意错误码输入 |
| NULL | 无描述信息 | - |
Structures
struct addrinfo
struct addrinfo {
int ai_flags;
int ai_family;
int ai_socktype;
int ai_protocol;
socklen_t ai_addrlen;
struct sockaddr *ai_addr;
char *ai_canonname;
struct addrinfo *ai_next;
};
成员说明
| 成员名称 | 数据类型 | 描述 |
|---|---|---|
| ai_flags | int | 输入标志位，控制 getaddrinfo 的行为 |
| ai_family | int | 地址族 |
| ai_socktype | int | 套接字类型 |
| ai_protocol | int | 协议类型 |
| ai_addrlen | socklen_t | ai_addr 指向的 socket 地址长度 |
| ai_addr | struct sockaddr * | 指向 socket 地址结构体的指针 |
| ai_canonname | char * | 主机规范名 |
| ai_next | struct addrinfo * | 指向链表中下一个 addrinfo 结构体的指针 |