计算机网络 / 知识点
Socket API 常用调用速查
数据收发
int sendmmsg(int sockfd, struct mmsghdr *msgvec, unsigned int vlen, int flags);Linux 扩展接口,可一次提交多个消息以减少系统调用次数;主要用于高吞吐 UDP 或报文批处理场景,不属于基础 POSIX API。
sendmmsg 批量发送消息
需要在 Linux 上一次提交多个独立报文、减少高吞吐 UDP 场景中的系统调用次数时查这个接口。它把多组 msghdr 放进 mmsghdr 数组,一次调用后可直接读取每个已发送消息的长度。
签名
int sendmmsg(int sockfd, struct mmsghdr *msgvec, unsigned int vlen, int flags);在 glibc 环境通常应在包含 <sys/socket.h> 前定义 _GNU_SOURCE,以暴露该 Linux 扩展接口。
| 参数 | 类型 | 含义 | 约束 |
|---|---|---|---|
sockfd |
int |
已创建的套接字描述符 | UDP 常用;也可用于支持 sendmsg 语义的套接字 |
msgvec |
struct mmsghdr * |
待发送消息数组 | 每项的 msg_hdr 描述地址、缓冲区和控制消息;msg_len 由内核写回 |
vlen |
unsigned int |
数组中的消息数 | 必须与可访问的数组元素数量一致 |
flags |
int |
发送标志 | 语义与 sendmsg 的 flags 一致,可为 0 |
返回与错误
成功时返回本次实际发送的消息个数,范围为 1..vlen;返回值小于 vlen 表示只提交了前一部分消息。每个已发送元素的 msg_len 会记录该消息发送的字节数。
如果一个消息都没有发送成功,返回 -1 并设置 errno。若已经发送部分消息后才遇到错误,调用可能直接返回已发送数量,因此此时不要把 errno 当作该批次剩余消息的可靠错误结果;应从返回下标继续重试或按业务策略处理。
完整示例
下面使用两个 UDP 套接字在回环地址上验证一次发送两条消息。
#define _GNU_SOURCE
#include <arpa/inet.h>
#include <stdio.h>
#include <string.h>
#include <sys/socket.h>
#include <unistd.h>
int main(void) {
int rx = socket(AF_INET, SOCK_DGRAM, 0);
int tx = socket(AF_INET, SOCK_DGRAM, 0);
if (rx < 0 || tx < 0) return 1;
struct sockaddr_in addr = {
.sin_family = AF_INET,
.sin_addr.s_addr = htonl(INADDR_LOOPBACK),
.sin_port = 0
};
if (bind(rx, (struct sockaddr *)&addr, sizeof(addr)) < 0) return 1;
socklen_t addrlen = sizeof(addr);
if (getsockname(rx, (struct sockaddr *)&addr, &addrlen) < 0) return 1;
char a[] = "alpha";
char b[] = "beta";
struct iovec iov[2] = {
{ .iov_base = a, .iov_len = strlen(a) },
{ .iov_base = b, .iov_len = strlen(b) }
};
struct mmsghdr msgs[2] = {0};
for (int i = 0; i < 2; i++) {
msgs[i].msg_hdr.msg_name = &addr;
msgs[i].msg_hdr.msg_namelen = sizeof(addr);
msgs[i].msg_hdr.msg_iov = &iov[i];
msgs[i].msg_hdr.msg_iovlen = 1;
}
int n = sendmmsg(tx, msgs, 2, 0);
if (n < 0) return 1;
char buf[16];
for (int i = 0; i < n; i++) {
ssize_t r = recv(rx, buf, sizeof(buf) - 1, 0);
if (r < 0) return 1;
buf[r] = '\0';
printf("%d:%s:%u\n", i, buf, msgs[i].msg_len);
}
close(tx);
close(rx);
return 0;
}预期输出:
0:alpha:5
1:beta:4边界与兼容性
sendmmsg 是 Linux 扩展,不属于基础 POSIX Socket API;跨平台代码应准备循环调用 sendmsg 的替代路径。它减少的是系统调用次数,不会把多条 UDP 消息合并成一个数据报;每个 mmsghdr 仍表示一条独立消息。
int recvmmsg(int sockfd, struct mmsghdr *msgvec, unsigned int vlen, unsigned int flags, struct timespec *timeout);Linux 扩展接口,可一次接收多个消息以降低系统调用开销;适用于高吞吐 UDP 接收,使用前应确认运行环境和头文件支持。
recvmmsg 批量接收消息
需要在 Linux 上一次取回多条独立报文、降低高吞吐 UDP 接收路径的系统调用开销时查这个接口。它把多个接收缓冲区一次交给内核,并在返回后给出本批实际收到的消息数和每条消息长度。
签名
int recvmmsg(int sockfd, struct mmsghdr *msgvec, unsigned int vlen,
unsigned int flags, struct timespec *timeout);在 glibc 环境通常应在包含 <sys/socket.h> 前定义 _GNU_SOURCE。
| 参数 | 类型 | 含义 | 约束 |
|---|---|---|---|
sockfd |
int |
接收套接字描述符 | UDP 批量接收最常见 |
msgvec |
struct mmsghdr * |
接收消息数组 | 每项需预先设置 msg_hdr 中的缓冲区;msg_len 由内核写回 |
vlen |
unsigned int |
最多接收的消息数 | 必须与数组容量匹配 |
flags |
unsigned int |
接收标志 | 可使用 recvmsg 支持的标志;MSG_WAITFORONE 是该接口常见用法 |
timeout |
struct timespec * |
等待超时 | 可为 NULL;非空时应提供有效的秒和纳秒值 |
返回与错误
成功时返回本批收到的消息个数,范围为 1..vlen;对应元素的 msg_len 是该消息实际接收的字节数。若套接字为非阻塞模式且当前无数据,通常返回 -1 并由 errno 表示 EAGAIN 或 EWOULDBLOCK。
调用失败且没有成功接收任何消息时返回 -1。处理 UDP 时还应检查每个 msg_hdr.msg_flags,例如缓冲区过小时可能出现 MSG_TRUNC,此时不能把缓冲区中的内容当作完整数据报。
完整示例
下面先向回环 UDP 套接字发送两条数据,再用一次 recvmmsg 接收它们。
#define _GNU_SOURCE
#include <arpa/inet.h>
#include <stdio.h>
#include <string.h>
#include <sys/socket.h>
#include <unistd.h>
int main(void) {
int rx = socket(AF_INET, SOCK_DGRAM, 0);
int tx = socket(AF_INET, SOCK_DGRAM, 0);
if (rx < 0 || tx < 0) return 1;
struct sockaddr_in addr = {
.sin_family = AF_INET,
.sin_addr.s_addr = htonl(INADDR_LOOPBACK),
.sin_port = 0
};
if (bind(rx, (struct sockaddr *)&addr, sizeof(addr)) < 0) return 1;
socklen_t addrlen = sizeof(addr);
if (getsockname(rx, (struct sockaddr *)&addr, &addrlen) < 0) return 1;
if (sendto(tx, "one", 3, 0, (struct sockaddr *)&addr, sizeof(addr)) != 3) return 1;
if (sendto(tx, "two", 3, 0, (struct sockaddr *)&addr, sizeof(addr)) != 3) return 1;
char buf[2][16] = {{0}};
struct iovec iov[2];
struct mmsghdr msgs[2] = {0};
for (int i = 0; i < 2; i++) {
iov[i].iov_base = buf[i];
iov[i].iov_len = sizeof(buf[i]) - 1;
msgs[i].msg_hdr.msg_iov = &iov[i];
msgs[i].msg_hdr.msg_iovlen = 1;
}
struct timespec timeout = { .tv_sec = 1, .tv_nsec = 0 };
int n = recvmmsg(rx, msgs, 2, 0, &timeout);
if (n < 0) return 1;
for (int i = 0; i < n; i++) {
buf[i][msgs[i].msg_len] = '\0';
printf("%d:%s:%u\n", i, buf[i], msgs[i].msg_len);
}
close(tx);
close(rx);
return 0;
}预期输出:
0:one:3
1:two:3边界与兼容性
recvmmsg 是 Linux 扩展,不属于基础 POSIX API;需要跨平台时可退化为循环调用 recvmsg。批量接收仍保留消息边界,每个 mmsghdr 对应一条消息。
不要把 timeout 当作严格的用户态定时器保证;如果业务要求精确截止时间,通常应结合非阻塞套接字与 poll、epoll 等等待机制控制整体超时。
I/O 多路复用
int select(int nfds, fd_set *restrict readfds, fd_set *restrict writefds, fd_set *restrict exceptfds, struct timeval *restrict timeout);通过 fd_set 同时等待多个文件描述符事件;接口历史悠久但受 FD_SETSIZE 等实现限制,适合兼容性要求较高的小规模场景。
等待多个描述符就绪
当一个线程需要同时等待多个 Socket 是否可读、可写或出现带外事件时使用 select。调用返回后,通过 FD_ISSET 判断哪些描述符已经就绪;它适合连接数不大、需要 POSIX 兼容性的场景。
签名
int select(int nfds,
fd_set *restrict readfds,
fd_set *restrict writefds,
fd_set *restrict exceptfds,
struct timeval *restrict timeout);nfds:参与监视的最大文件描述符值加 1;不是描述符数量。readfds:输入时给出关注可读事件的集合,返回时只保留已就绪描述符;不需要时传NULL。writefds:输入时给出关注可写事件的集合,返回时只保留已就绪描述符;不需要时传NULL。exceptfds:用于等待实现定义的异常条件,例如某些 Socket 的带外数据;它不是通用“错误集合”。timeout:NULL表示一直等待;零值timeval表示立即返回;正值表示最长等待时间。调用后不要依赖其原值,循环等待时应重新初始化。
fd_set 通过 FD_ZERO、FD_SET、FD_CLR 和 FD_ISSET 操作。描述符值必须落在实现支持的 fd_set 范围内,通常受 FD_SETSIZE 限制。
返回与错误
返回值大于 0 时,表示三个结果集合中被置位项的总数;返回 0 表示超时;返回 -1 表示失败并设置 errno。常见失败包括等待被信号中断、集合中存在无效描述符,或参数不合法。
完整示例
下面使用 socketpair 创建一对本地已连接 Socket,先向一端写入数据,再用 select 等待另一端可读。
#include <errno.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/select.h>
#include <sys/socket.h>
#include <sys/time.h>
#include <unistd.h>
int main(void) {
int sv[2];
if (socketpair(AF_UNIX, SOCK_STREAM, 0, sv) == -1) {
perror("socketpair");
return 1;
}
const char *msg = "ping";
if (send(sv[0], msg, strlen(msg), 0) == -1) {
perror("send");
close(sv[0]);
close(sv[1]);
return 1;
}
fd_set readfds;
FD_ZERO(&readfds);
FD_SET(sv[1], &readfds);
struct timeval timeout = {
.tv_sec = 1,
.tv_usec = 0
};
int ready = select(sv[1] + 1, &readfds, NULL, NULL, &timeout);
if (ready == -1) {
perror("select");
close(sv[0]);
close(sv[1]);
return 1;
}
if (ready == 0) {
puts("timeout");
close(sv[0]);
close(sv[1]);
return 0;
}
if (FD_ISSET(sv[1], &readfds)) {
char buf[16] = {0};
ssize_t n = recv(sv[1], buf, sizeof(buf) - 1, 0);
if (n == -1) {
perror("recv");
close(sv[0]);
close(sv[1]);
return 1;
}
printf("readable: %s\n", buf);
}
close(sv[0]);
close(sv[1]);
return 0;
}预期输出:
readable: ping边界与兼容性
select 每次都需要扫描并重建集合,且描述符值受到 fd_set 容量约束,因此不适合大量高编号连接。若连接集合持续扩大,应优先评估 poll 或平台专用的可扩展事件接口。本文签名按 POSIX 语义说明;Windows Winsock 的 select 在类型和集合行为上存在差异,不能直接套用本条参数规则。
int poll(struct pollfd fds[], nfds_t nfds, int timeout);以 pollfd 数组等待可读、可写、异常等事件;没有 select 的位图大小限制,适合中小规模连接集合和跨 Unix 兼容场景。
轮询描述符事件
当需要等待一组 Socket 的可读、可写、挂断或错误状态,又不希望受 fd_set 位图大小限制时使用 poll。调用返回后读取每个元素的 revents,即可判断实际发生的事件。
签名
int poll(struct pollfd fds[], nfds_t nfds, int timeout);核心结构体:
struct pollfd {
int fd;
short events;
short revents;
};fds:pollfd数组;fd是文件描述符,events是请求监视的事件,revents由内核写回实际事件。nfds:数组元素个数,不是最大描述符加 1。timeout:毫秒。负值表示一直等待,0表示立即检查,正值表示最长等待毫秒数。- 常用
events:POLLIN表示可读,POLLOUT表示可写,POLLPRI表示高优先级数据。 - 常见返回标志:
POLLERR、POLLHUP、POLLNVAL即使没有写入events也可能出现在revents中。
数组元素的 fd 为负数时,该元素会被忽略,并在返回时保持 revents 为 0;这可用于临时停用某个槽位而不重排数组。
返回与错误
返回值大于 0 时,表示 revents 非零的数组元素数量;返回 0 表示超时;返回 -1 表示失败并设置 errno。等待过程中收到未被自动重启的信号时可能返回 EINTR,事件循环通常需要根据业务策略重试。
完整示例
下面使用 socketpair 创建本地已连接 Socket,并通过 poll 等待另一端变为可读。
#include <poll.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/socket.h>
#include <unistd.h>
int main(void) {
int sv[2];
if (socketpair(AF_UNIX, SOCK_STREAM, 0, sv) == -1) {
perror("socketpair");
return 1;
}
const char *msg = "ping";
if (send(sv[0], msg, strlen(msg), 0) == -1) {
perror("send");
close(sv[0]);
close(sv[1]);
return 1;
}
struct pollfd fds[1] = {
{
.fd = sv[1],
.events = POLLIN,
.revents = 0
}
};
int ready = poll(fds, 1, 1000);
if (ready == -1) {
perror("poll");
close(sv[0]);
close(sv[1]);
return 1;
}
if (ready == 0) {
puts("timeout");
close(sv[0]);
close(sv[1]);
return 0;
}
if (fds[0].revents & POLLIN) {
char buf[16] = {0};
ssize_t n = recv(sv[1], buf, sizeof(buf) - 1, 0);
if (n == -1) {
perror("recv");
close(sv[0]);
close(sv[1]);
return 1;
}
printf("readable: %s\n", buf);
}
if (fds[0].revents & (POLLERR | POLLNVAL)) {
fprintf(stderr, "poll reported an error event\n");
}
close(sv[0]);
close(sv[1]);
return 0;
}预期输出:
readable: ping边界与兼容性
poll 没有 select 那种基于 FD_SETSIZE 的位图限制,但每次调用仍要线性检查传入数组,因此连接数量很大时通常会转向 epoll、kqueue 等平台专用机制。本文按 POSIX poll 语义说明;具体支持的事件标志可能因 Unix 实现而异,跨平台代码应只依赖目标系统明确提供的标志。
int epoll_create1(int flags);创建 Linux epoll 实例并返回其文件描述符;通常使用 flags 为 0 或 EPOLL_CLOEXEC,后续通过 epoll_ctl 注册目标 Socket。
创建 epoll 实例
需要建立 epoll 关注集合时调用 epoll_create1。成功后得到一个 epoll 文件描述符,随后把它传给 epoll_ctl 和 epoll_wait;使用完必须调用 close 释放。
签名
#include <sys/epoll.h>
int epoll_create1(int flags);flags 当前常用取值是 0 或 EPOLL_CLOEXEC。后者会为返回的文件描述符设置 close-on-exec,避免执行其他程序时意外继承该描述符。
返回与错误
成功时返回新的非负文件描述符;失败时返回 -1 并设置 errno。常见失败包括参数包含不支持的标志、进程文件描述符达到限制,或系统资源不足。
完整示例
#include <errno.h>
#include <stdio.h>
#include <string.h>
#include <sys/epoll.h>
#include <unistd.h>
int main(void) {
int epfd = epoll_create1(EPOLL_CLOEXEC);
if (epfd == -1) {
fprintf(stderr, "epoll_create1 failed: %s\n", strerror(errno));
return 1;
}
printf("epoll fd=%d\n", epfd);
close(epfd);
return 0;
}预期输出:文件描述符数值由运行时分配,实际值可能不同。
epoll fd=<ID>边界与兼容性
epoll_create1 是 Linux API,不适用于 BSD、macOS 或 Windows。返回值只是 epoll 实例本身的文件描述符,并不会自动关注任何 Socket;至少还需要通过 epoll_ctl 添加关注项后,epoll_wait 才可能返回相应事件。
int epoll_ctl(int epfd, int op, int fd, struct epoll_event *event);向 epoll 实例新增、修改或删除文件描述符及其关注事件;核心操作为 EPOLL_CTL_ADD、EPOLL_CTL_MOD 和 EPOLL_CTL_DEL。
管理 epoll 关注项
需要把 Socket 等文件描述符加入 epoll、修改其关注事件或从关注集合删除时调用 epoll_ctl。它只修改关注集合,不负责等待事件;等待通常由 epoll_wait 完成。
签名
#include <sys/epoll.h>
int epoll_ctl(int epfd, int op, int fd, struct epoll_event *event);epfd:由epoll_create1等接口创建的 epoll 实例文件描述符。op:操作类型,常用为EPOLL_CTL_ADD、EPOLL_CTL_MOD或EPOLL_CTL_DEL。fd:需要管理的目标文件描述符。event:新增或修改时指向struct epoll_event;删除时现代 Linux 内核忽略该参数,通常传NULL。
struct epoll_event.events 保存 EPOLLIN、EPOLLOUT、EPOLLET 等事件标志;data 联合体用于把应用自己的文件描述符、整数或指针与事件关联。
返回与错误
成功返回 0;失败返回 -1 并设置 errno。例如,重复对同一目标执行 EPOLL_CTL_ADD 通常会得到 EEXIST,修改或删除未注册的目标通常会得到 ENOENT。无效的 epoll 描述符、目标描述符或操作也会失败。
完整示例
下面用管道的读端代替 Socket,完整演示新增、修改和删除关注项;这三个操作对 Socket 文件描述符的调用方式相同。
#include <errno.h>
#include <stdio.h>
#include <string.h>
#include <sys/epoll.h>
#include <unistd.h>
int main(void) {
int pipefd[2];
if (pipe(pipefd) == -1) {
fprintf(stderr, "pipe failed: %s\n", strerror(errno));
return 1;
}
int epfd = epoll_create1(EPOLL_CLOEXEC);
if (epfd == -1) {
fprintf(stderr, "epoll_create1 failed: %s\n", strerror(errno));
close(pipefd[0]);
close(pipefd[1]);
return 1;
}
struct epoll_event ev = {0};
ev.events = EPOLLIN;
ev.data.fd = pipefd[0];
if (epoll_ctl(epfd, EPOLL_CTL_ADD, pipefd[0], &ev) == -1) {
fprintf(stderr, "ADD failed: %s\n", strerror(errno));
return 1;
}
ev.events = EPOLLIN | EPOLLET;
if (epoll_ctl(epfd, EPOLL_CTL_MOD, pipefd[0], &ev) == -1) {
fprintf(stderr, "MOD failed: %s\n", strerror(errno));
return 1;
}
if (epoll_ctl(epfd, EPOLL_CTL_DEL, pipefd[0], NULL) == -1) {
fprintf(stderr, "DEL failed: %s\n", strerror(errno));
return 1;
}
puts("add, modify and delete succeeded");
close(epfd);
close(pipefd[0]);
close(pipefd[1]);
return 0;
}预期输出:三个控制操作全部成功时输出一行。
add, modify and delete succeeded使用边界
epoll_ctl 是 Linux 专用 API。使用 EPOLLET 边沿触发时,目标描述符通常应配合非阻塞 I/O,并在收到事件后持续读写直到返回 EAGAIN 或 EWOULDBLOCK;否则可能因为没有新的状态变化而迟迟收不到下一次通知。
删除关注项后,该文件描述符不再属于当前 epoll 实例的关注集合。关闭目标文件描述符与显式执行 EPOLL_CTL_DEL 的生命周期语义不同,复杂服务中应明确管理注册、修改、删除和关闭的先后关系。
int epoll_wait(int epfd, struct epoll_event *events, int maxevents, int timeout);等待已注册描述符产生事件并把结果写入事件数组;返回值是本次就绪事件数量,超时返回 0,被信号打断通常返回 -1。
等待 epoll 事件
当事件循环需要阻塞等待一组已注册文件描述符就绪时使用 epoll_wait。它把本轮就绪事件写入调用方提供的数组,并用返回值告诉你实际写入了多少项;超时返回 0,被信号打断等失败情况返回 -1。
签名
int epoll_wait(int epfd, struct epoll_event *events, int maxevents, int timeout);参数含义:
| 参数 | 类型 | 必填 | 含义与约束 |
|---|---|---|---|
epfd |
int |
是 | epoll_create1 或 epoll_create 返回的 epoll 实例描述符。 |
events |
struct epoll_event * |
是 | 输出数组,至少能容纳 maxevents 个元素。 |
maxevents |
int |
是 | 本次最多返回的事件数,必须大于 0。 |
timeout |
int |
是 | 毫秒;-1 表示无限等待,0 表示立即返回,正数表示最长等待时间。 |
events 中每一项的 events 字段给出 EPOLLIN、EPOLLOUT、EPOLLERR 等就绪标志,data 字段保持注册时通过 epoll_ctl 保存的用户数据。
返回与错误
返回值大于 0 时表示本轮就绪事件数量,范围不超过 maxevents;返回 0 表示在给定超时时间内没有事件;返回 -1 表示失败,并设置 errno。
常见失败包括:EBADF 表示 epfd 不是有效描述符,EINVAL 表示 epfd 不是 epoll 实例或 maxevents <= 0,EFAULT 表示 events 指向不可访问内存,EINTR 表示等待在产生事件或超时前被信号处理程序打断。
完整示例
下面用 socketpair 构造一个本地双向套接字对,向一端写入一个字节,再等待另一端出现可读事件。
#include <sys/epoll.h>
#include <sys/socket.h>
#include <unistd.h>
#include <stdio.h>
#include <stdlib.h>
int main(void) {
int sv[2];
if (socketpair(AF_UNIX, SOCK_STREAM, 0, sv) == -1) {
perror("socketpair");
return 1;
}
int epfd = epoll_create1(0);
if (epfd == -1) {
perror("epoll_create1");
return 1;
}
struct epoll_event ev = {0};
ev.events = EPOLLIN;
ev.data.fd = sv[1];
if (epoll_ctl(epfd, EPOLL_CTL_ADD, sv[1], &ev) == -1) {
perror("epoll_ctl");
return 1;
}
if (write(sv[0], "Z", 1) != 1) {
perror("write");
return 1;
}
struct epoll_event ready[1];
int n = epoll_wait(epfd, ready, 1, 1000);
if (n == -1) {
perror("epoll_wait");
return 1;
}
if (n == 0) {
puts("timeout");
return 0;
}
char ch = 0;
if (recv(ready[0].data.fd, &ch, 1, 0) != 1) {
perror("recv");
return 1;
}
printf("ready=%d data=%c\n", n, ch);
close(epfd);
close(sv[0]);
close(sv[1]);
return 0;
}编译并运行:
cc -Wall -Wextra -O2 epoll_wait_demo.c -o epoll_wait_demo
./epoll_wait_demo预期输出:
ready=1 data=Z边界与兼容性
epoll_wait 是 Linux API,不属于 POSIX;程序需要包含 <sys/epoll.h>。timeout 的单位是毫秒,不能表达亚毫秒等待;事件循环若允许信号打断,应显式处理 EINTR,并根据业务决定重试、退出或转入信号处理逻辑。对于边沿触发 EPOLLET,返回一次就绪通知后通常还要把非阻塞描述符读写到 EAGAIN,否则可能遗漏后续处理机会。
int epoll_pwait(int epfd, struct epoll_event *events, int maxevents, int timeout, const sigset_t *sigmask);epoll_wait 的 Linux 扩展版本,可在等待期间原子地临时替换信号屏蔽字;适合需要协调事件循环与信号处理的服务程序。
等待 epoll 事件并原子处理信号
当事件循环既要等待文件描述符,又要避免“刚检查完信号、尚未进入等待就收到信号”的竞态时使用 epoll_pwait。它在进入等待时原子地临时替换线程的信号屏蔽字,并在返回后恢复原屏蔽字。
签名
int epoll_pwait(int epfd, struct epoll_event *events, int maxevents, int timeout, const sigset_t *sigmask);前四个参数与 epoll_wait 相同:
| 参数 | 类型 | 必填 | 含义与约束 |
|---|---|---|---|
epfd |
int |
是 | epoll 实例描述符。 |
events |
struct epoll_event * |
是 | 输出数组,至少容纳 maxevents 项。 |
maxevents |
int |
是 | 最多返回的事件数,必须大于 0。 |
timeout |
int |
是 | 毫秒;-1 无限等待,0 立即返回。 |
sigmask |
const sigset_t * |
是 | 等待期间临时使用的信号屏蔽字;传 NULL 时不替换屏蔽字,行为等同于 epoll_wait。 |
关键点不是“多处理一个信号参数”,而是屏蔽字切换与进入等待之间没有可见竞态窗口。返回后,调用线程原来的信号屏蔽字会恢复。

返回与错误
返回值语义与 epoll_wait 一致:大于 0 是就绪事件数,0 是超时,-1 是失败并设置 errno。等待期间某个未屏蔽信号被处理,且当时尚无可返回事件时,通常会以 -1 和 EINTR 返回。
EBADF、EINVAL、EFAULT 等参数错误与 epoll_wait 的含义相同。sigmask 必须指向调用线程可读的 sigset_t;传入 NULL 时不会临时改变屏蔽字。
完整示例
示例先在主线程中阻塞 SIGUSR1,再启动线程发送该信号;等待时从原屏蔽字中只移除 SIGUSR1,因此其他既有屏蔽设置保持不变,目标信号会在 epoll_pwait 真正进入等待后被交付并使调用以 EINTR 返回。
#define _GNU_SOURCE
#include <sys/epoll.h>
#include <pthread.h>
#include <signal.h>
#include <errno.h>
#include <stdio.h>
#include <string.h>
#include <time.h>
#include <unistd.h>
static volatile sig_atomic_t got_signal = 0;
static void on_sigusr1(int signo) {
(void)signo;
got_signal = 1;
}
static void *sender(void *arg) {
pthread_t target = *(pthread_t *)arg;
struct timespec delay = {0, 100000000};
nanosleep(&delay, NULL);
pthread_kill(target, SIGUSR1);
return NULL;
}
int main(void) {
struct sigaction sa = {0};
sa.sa_handler = on_sigusr1;
sigemptyset(&sa.sa_mask);
sigaction(SIGUSR1, &sa, NULL);
sigset_t blocked;
sigemptyset(&blocked);
sigaddset(&blocked, SIGUSR1);
sigset_t oldmask;
int rc = pthread_sigmask(SIG_BLOCK, &blocked, &oldmask);
if (rc != 0) {
fprintf(stderr, "pthread_sigmask: %s\n", strerror(rc));
return 1;
}
int epfd = epoll_create1(0);
if (epfd == -1) {
perror("epoll_create1");
return 1;
}
pthread_t main_thread = pthread_self();
pthread_t worker;
rc = pthread_create(&worker, NULL, sender, &main_thread);
if (rc != 0) {
fprintf(stderr, "pthread_create: %s\n", strerror(rc));
return 1;
}
sigset_t wait_mask = oldmask;
sigdelset(&wait_mask, SIGUSR1);
struct epoll_event events[1];
errno = 0;
int n = epoll_pwait(epfd, events, 1, 1000, &wait_mask);
int saved_errno = errno;
pthread_join(worker, NULL);
close(epfd);
if (n == -1 && saved_errno == EINTR) {
printf("signal=%d errno=EINTR\n", got_signal ? 1 : 0);
return 0;
}
if (n == 0) {
puts("timeout");
} else {
printf("unexpected return=%d errno=%d\n", n, saved_errno);
}
return 1;
}编译并运行:
cc -Wall -Wextra -O2 -pthread epoll_pwait_demo.c -o epoll_pwait_demo
./epoll_pwait_demo预期输出:
signal=1 errno=EINTR边界与兼容性
epoll_pwait 是 Linux 专用 API,不属于 POSIX。它解决的是信号屏蔽与进入等待之间的原子性问题;如果只是普通事件等待且不需要临时调整信号屏蔽字,epoll_wait 更直接。多线程程序要注意信号屏蔽字是线程级状态,应在目标线程中设置和理解其屏蔽关系,而不是假定整个进程共享同一份当前 mask。
int pselect(int nfds, fd_set *restrict readfds, fd_set *restrict writefds, fd_set *restrict exceptfds, const struct timespec *restrict timeout, const sigset_t *restrict sigmask);select 的扩展版本,允许在等待期间原子修改信号屏蔽字,并使用更高精度的 timespec 超时;适合信号与 I/O 协调场景。
pselect
当需要同时等待多个文件描述符,又要避免“检查状态后、进入阻塞前”被信号打断形成竞态时查这个 API。pselect 会监视读、写和异常集合,并可在等待期间原子替换线程的信号屏蔽字。
签名
int pselect(int nfds, fd_set *restrict readfds, fd_set *restrict writefds, fd_set *restrict exceptfds, const struct timespec *restrict timeout, const sigset_t *restrict sigmask);nfds 必须等于所有被监视描述符中的最大值加 1;没有描述符时可为 0。readfds、writefds、exceptfds 都可为 NULL,非空集合在返回时只保留已就绪的描述符。timeout 为相对超时,NULL 表示无限等待;sigmask 为等待期间临时采用的信号屏蔽字,NULL 表示不修改当前屏蔽字。
| 参数 | 类型 | 必填性 | 含义与约束 |
|---|---|---|---|
nfds |
int |
是 | 扫描范围为 0 到 nfds - 1 |
readfds |
fd_set * |
否 | 可读事件集合,返回后被改写为已就绪集合 |
writefds |
fd_set * |
否 | 可写事件集合,返回后被改写为已就绪集合 |
exceptfds |
fd_set * |
否 | 异常条件集合,返回后被改写为已就绪集合 |
timeout |
const struct timespec * |
否 | 秒与纳秒精度的相对超时;NULL 表示无限等待 |
sigmask |
const sigset_t * |
否 | 等待期间原子替换当前线程的信号屏蔽字 |

返回与错误
返回正数表示至少一个描述符就绪,数值是三个集合中就绪描述符的总数;返回 0 表示超时;返回 -1 表示失败,并设置 errno。常见失败包括 EBADF(集合中存在无效描述符)、EINTR(被未屏蔽且已捕获的信号中断)和 EINVAL(参数或超时值无效,具体条件以实现为准)。
完整示例
下面用管道模拟一个稍后变为可读的文件描述符,并给 pselect 1 秒超时。示例传入空信号集,表示等待期间临时不屏蔽任何信号。
#define _POSIX_C_SOURCE 200809L
#include <signal.h>
#include <stdio.h>
#include <sys/select.h>
#include <sys/wait.h>
#include <time.h>
#include <unistd.h>
int main(void) {
int p[2];
if (pipe(p) == -1) { perror("pipe"); return 1; }
pid_t pid = fork();
if (pid == -1) { perror("fork"); return 1; }
if (pid == 0) {
close(p[0]);
struct timespec delay = { .tv_sec = 0, .tv_nsec = 100000000L };
nanosleep(&delay, NULL);
if (write(p[1], "ping", 4) != 4) _exit(2);
_exit(0);
}
close(p[1]);
fd_set rfds;
FD_ZERO(&rfds);
FD_SET(p[0], &rfds);
struct timespec timeout = { .tv_sec = 1, .tv_nsec = 0 };
sigset_t waitmask;
sigemptyset(&waitmask);
int n = pselect(p[0] + 1, &rfds, NULL, NULL, &timeout, &waitmask);
if (n == -1) { perror("pselect"); return 1; }
if (n == 0) { puts("timeout"); return 0; }
char buf[5] = {0};
if (read(p[0], buf, 4) == -1) { perror("read"); return 1; }
printf("ready=%d data=%s\n", n, buf);
close(p[0]);
waitpid(pid, NULL, 0);
return 0;
}预期输出:
ready=1 data=ping边界与兼容性
pselect 属于 POSIX 接口,示例使用 _POSIX_C_SOURCE 200809L 暴露声明。它的关键价值不是“比 select 更快”,而是把信号屏蔽字切换与进入等待合并为一个原子操作;若只需要普通 I/O 等待而不涉及信号竞态,选择何种多路复用机制应按平台、描述符数量和性能要求决定。
地址与名称解析
int getaddrinfo(const char *restrict node, const char *restrict service, const struct addrinfo *restrict hints, struct addrinfo **restrict res);把主机名、服务名或数值地址解析为可直接用于 Socket 的地址链表;同时支持 IPv4、IPv6 与 TCP/UDP 服务选择。
getaddrinfo
当需要把主机名、数值 IP 或服务名转换成可直接传给 socket、connect、bind 的地址结构时查这个 API。它返回 addrinfo 链表,可一次覆盖 IPv4/IPv6、TCP/UDP 等候选组合。
签名
int getaddrinfo(const char *restrict node, const char *restrict service, const struct addrinfo *restrict hints, struct addrinfo **restrict res);node 是主机名或数值地址,service 是服务名或端口字符串;两者不能同时为 NULL。hints 可为 NULL,也可用于限定地址族、Socket 类型、协议与解析标志。成功时 res 指向动态分配的结果链表,使用完必须调用 freeaddrinfo。
| 参数 | 类型 | 必填性 | 含义与约束 |
|---|---|---|---|
node |
const char * |
条件必填 | 主机名或数值 IP;与 service 至少提供一个 |
service |
const char * |
条件必填 | 服务名或十进制端口字符串 |
hints |
const struct addrinfo * |
否 | 常先清零,再设置 ai_family、ai_socktype、ai_protocol、ai_flags |
res |
struct addrinfo ** |
是 | 成功后接收结果链表头指针 |
常用约束包括:AF_UNSPEC 接受 IPv4/IPv6,AF_INET 或 AF_INET6 可强制地址族;SOCK_STREAM 常用于 TCP,SOCK_DGRAM 常用于 UDP;AI_NUMERICHOST 与 AI_NUMERICSERV 可要求输入必须是数值形式,从而避免名称解析。

返回与错误
成功返回 0;失败返回非 0 的 EAI_* 错误码,不应把返回值当成 errno。错误文本可传给 gai_strerror。常见错误包括名称暂时不可解析、主机或服务不存在、地址族/Socket 类型不受支持;若返回 EAI_SYSTEM,底层系统错误可再查看 errno。
结果链表中的每个节点都可能对应不同地址或协议组合。调用方通常按顺序尝试候选节点,直到 socket 与后续 connect/bind 成功,而不是假定第一个结果永远可用。
完整示例
下面解析数值 IPv4 地址和数值端口,因此不依赖 DNS 或系统服务名数据库;再用 getnameinfo 以数值形式读回结果。
#define _POSIX_C_SOURCE 200809L
#include <netdb.h>
#include <stdio.h>
#include <string.h>
#include <sys/socket.h>
int main(void) {
struct addrinfo hints;
memset(&hints, 0, sizeof(hints));
hints.ai_family = AF_UNSPEC;
hints.ai_socktype = SOCK_STREAM;
hints.ai_protocol = IPPROTO_TCP;
hints.ai_flags = AI_NUMERICHOST | AI_NUMERICSERV;
struct addrinfo *res = NULL;
int rc = getaddrinfo("127.0.0.1", "8080", &hints, &res);
if (rc != 0) {
fprintf(stderr, "getaddrinfo: %s\n", gai_strerror(rc));
return 1;
}
char host[64];
char service[16];
rc = getnameinfo(res->ai_addr, res->ai_addrlen,
host, sizeof(host), service, sizeof(service),
NI_NUMERICHOST | NI_NUMERICSERV);
if (rc != 0) {
fprintf(stderr, "getnameinfo: %s\n", gai_strerror(rc));
freeaddrinfo(res);
return 1;
}
printf("host=%s service=%s family=%s\n",
host, service, res->ai_family == AF_INET ? "IPv4" : "IPv6");
freeaddrinfo(res);
return 0;
}预期输出:
host=127.0.0.1 service=8080 family=IPv4边界与兼容性
getaddrinfo 属于 POSIX 接口,但名称解析结果受本机 DNS、/etc/hosts、服务数据库、网络配置和解析器策略影响,因此真实主机名的候选数量与顺序不能写死。需要可复现实验时使用数值地址并配合 AI_NUMERICHOST/AI_NUMERICSERV;生产代码则应遍历完整链表并在结束时无条件 freeaddrinfo。
void freeaddrinfo(struct addrinfo *res);释放 getaddrinfo 返回的整个 addrinfo 链表;解析结果使用完成后必须释放,避免在客户端重连或循环解析场景中持续占用内存。
释放地址解析结果
在 getaddrinfo 成功返回地址链表并完成遍历、连接或绑定后调用 freeaddrinfo,一次释放整条结果链。释放后不得继续访问原链表及其中的地址、规范名称等成员。
签名
void freeaddrinfo(struct addrinfo *res);res 必须指向 getaddrinfo 成功返回的结果链表首节点。调用者不需要逐节点释放,也不应自行对链表节点或其内部指针调用 free。
返回与错误
freeaddrinfo 没有返回值,也不提供失败状态。它只负责释放由 getaddrinfo 分配的结果链表;getaddrinfo 本身失败且没有取得有效结果时,不要构造伪造的 addrinfo 指针交给它。
调用完成后,原来的 res 以及从链表节点取得的 ai_addr、ai_canonname 等指针均应视为失效。需要长期保存其中的数据时,应在释放前复制到调用者自己的存储区。
完整示例
下面使用数值 IPv4 地址避免依赖 DNS。程序取得结果后读取第一个节点,再释放整条链表。
#include <netdb.h>
#include <stdio.h>
#include <string.h>
int main(void) {
struct addrinfo hints;
struct addrinfo *res = NULL;
memset(&hints, 0, sizeof(hints));
hints.ai_family = AF_UNSPEC;
hints.ai_socktype = SOCK_STREAM;
hints.ai_flags = AI_NUMERICHOST;
int rc = getaddrinfo("127.0.0.1", NULL, &hints, &res);
if (rc != 0) {
fprintf(stderr, "getaddrinfo: %s\n", gai_strerror(rc));
return 1;
}
if (res != NULL) {
printf("resolved family: %d\n", res->ai_family);
}
/* 一次释放 getaddrinfo 返回的整条链表。 */
freeaddrinfo(res);
res = NULL;
puts("addrinfo released");
return 0;
}预期输出:ai_family 的数值由平台定义,因此实际数字可能不同;最后一行应固定出现。
resolved family: <ID>
addrinfo released边界与常见误用
不要只释放首节点后继续保存后续节点,也不要在 freeaddrinfo 后继续遍历原链表。循环执行地址解析时,应保证每次成功取得的结果最终都走到释放路径,包括连接失败、提前返回和重试分支;否则长期运行的客户端或服务端可能持续积累解析结果占用的内存。
int inet_pton(int af, const char *restrict src, void *restrict dst);把点分十进制 IPv4 或冒号表示的 IPv6 文本转换为二进制网络地址;新代码通常优先使用它而不是历史 inet_addr 接口。
解析数值 IP 地址
需要把用户输入、配置文件或协议字段中的 IPv4/IPv6 文本转换成 Socket API 使用的二进制地址时调用 inet_pton。它只解析数值地址,不执行 DNS 或主机名查询。
签名
int inet_pton(int af, const char *restrict src, void *restrict dst);af:地址族。IPv4 使用AF_INET,IPv6 使用AF_INET6。src:以空字符结尾的数值 IP 地址字符串。dst:接收二进制地址的缓冲区;AF_INET时通常指向struct in_addr,AF_INET6时通常指向struct in6_addr。
调用者必须根据 af 提供足够大的目标对象,函数不会为 dst 分配内存。
返回与错误
返回 1 表示转换成功,dst 已写入网络地址;返回 0 表示 src 不是所选地址族的合法数值地址。返回 -1 表示地址族不受支持,此时可检查 errno,POSIX 环境通常报告 EAFNOSUPPORT。
0 与 -1 的含义不同:输入格式错误应作为数据校验失败处理,而不是直接按系统调用错误处理。
完整示例
下面将文档示例网段中的 IPv4 地址 192.0.2.1 转换为 4 字节网络地址,并输出每个字节验证结果。
#include <arpa/inet.h>
#include <errno.h>
#include <stdio.h>
#include <string.h>
int main(void) {
const char *src = "192.0.2.1";
struct in_addr addr;
int rc = inet_pton(AF_INET, src, &addr);
if (rc == 0) {
fprintf(stderr, "invalid IPv4 address: %s\n", src);
return 1;
}
if (rc == -1) {
fprintf(stderr, "inet_pton: %s\n", strerror(errno));
return 1;
}
/* 网络地址在内存中按网络字节序保存。 */
const unsigned char *bytes = (const unsigned char *)&addr;
printf("%02x %02x %02x %02x\n",
bytes[0], bytes[1], bytes[2], bytes[3]);
return 0;
}预期输出:输入 192.0.2.1 对应的四个网络地址字节为以下十六进制值。
c0 00 02 01边界与兼容性
inet_pton 不接受主机名;需要把域名解析成一个或多个地址时应使用 getaddrinfo。解析 IPv6 时应把 af 改为 AF_INET6,同时把目标对象改为 struct in6_addr,不能继续使用仅能容纳 IPv4 地址的 struct in_addr。
不要仅凭返回值非负就判定成功,因为非法文本返回的是 0。正确判断应明确区分 1、0 和 -1 三种结果。
const char *inet_ntop(int af, const void *restrict src, char *restrict dst, socklen_t size);把网络字节序地址转换为可打印的 IPv4 或 IPv6 字符串;调用者需提供足够大的目标缓冲区并检查返回值是否为 NULL。
格式化二进制 IP 地址
需要把 struct in_addr 或 struct in6_addr 中的二进制地址写入日志、配置或诊断信息时使用 inet_ntop。它只负责地址格式化,不执行 DNS 或主机名解析;成功后可直接读取调用者提供的字符串缓冲区。
签名与参数
const char *inet_ntop(int af, const void *restrict src,
char *restrict dst, socklen_t size);| 参数 | 类型 | 含义 | 约束 |
|---|---|---|---|
af |
int |
地址族 | 常用 AF_INET 或 AF_INET6 |
src |
const void * |
二进制地址 | IPv4 指向 struct in_addr,IPv6 指向 struct in6_addr |
dst |
char * |
接收文本地址的缓冲区 | 由调用者分配 |
size |
socklen_t |
dst 的容量 |
IPv4 通常传 INET_ADDRSTRLEN,IPv6 通常传 INET6_ADDRSTRLEN |
src 必须保存与 af 匹配的网络格式地址。不要把整个 struct sockaddr_in 或 struct sockaddr_in6 直接传给 src,应传其中的地址字段。
返回与错误
成功时返回 dst;失败时返回 NULL。不支持的地址族可导致 EAFNOSUPPORT,目标缓冲区不足可导致 ENOSPC,因此不能忽略返回值。
缓冲区应优先使用系统提供的 INET_ADDRSTRLEN 与 INET6_ADDRSTRLEN,不要自行猜测 IPv6 文本的最大长度。
完整示例
#include <arpa/inet.h>
#include <stdio.h>
int main(void) {
const char *input = "2001:db8::42";
struct in6_addr addr;
char output[INET6_ADDRSTRLEN];
if (inet_pton(AF_INET6, input, &addr) != 1) {
fputs("inet_pton failed\n", stderr);
return 1;
}
if (inet_ntop(AF_INET6, &addr, output, sizeof output) == NULL) {
perror("inet_ntop");
return 1;
}
printf("%s\n", output);
return 0;
}预期输出:
2001:db8::42边界与兼容性
IPv6 地址允许多种等价文本写法,inet_ntop 会生成合法的展示形式,但调用方不应依赖某一种字符串压缩形式做二进制等价判断。需要比较地址时,应比较解析后的地址值,而不是直接比较文本。
在 POSIX 系统中通常从 <arpa/inet.h> 获取声明。该函数处理 IP 地址本身,不包含端口;若要展示 IP:port,端口应单独通过 ntohs 转回主机字节序后再格式化。
int getnameinfo(const struct sockaddr *restrict addr, socklen_t addrlen, char *restrict host, socklen_t hostlen, char *restrict serv, socklen_t servlen, int flags);把 Socket 地址转换为主机名和服务名或其数值形式;日志记录、审计展示和调试连接来源时常用,避免直接手写 IPv4 专用解析逻辑。
反向解析地址与服务
拿到 accept、recvfrom 等接口返回的 sockaddr 后,可用 getnameinfo 将地址转换为主机名、数值 IP、服务名或端口字符串。日志和审计场景通常配合数值标志使用,避免 DNS 或服务数据库查询带来的延迟和不确定性。
签名
int getnameinfo(const struct sockaddr *restrict addr,
socklen_t addrlen,
char *restrict host,
socklen_t hostlen,
char *restrict serv,
socklen_t servlen,
int flags);| 参数 | 类型 | 必填 | 含义与约束 |
|---|---|---|---|
addr |
const struct sockaddr * |
是 | 指向待解析的 Socket 地址 |
addrlen |
socklen_t |
是 | addr 对应地址结构的实际长度 |
host |
char * |
条件必填 | 接收主机名或数值地址;不需要时可配合长度 0 跳过 |
hostlen |
socklen_t |
是 | host 缓冲区容量,空间不足可能返回 EAI_OVERFLOW |
serv |
char * |
条件必填 | 接收服务名或数值端口;不需要时可配合长度 0 跳过 |
servlen |
socklen_t |
是 | serv 缓冲区容量 |
flags |
int |
是 | 控制名称解析方式,可按位组合 NI_NUMERICHOST、NI_NUMERICSERV 等标志 |
返回值与错误
成功返回 0,结果写入调用方提供的缓冲区。失败返回非零的 EAI_* 错误码,应使用 gai_strerror 获取对应说明,而不是把所有失败都当作普通 errno。
常见失败包括地址族或参数不受支持、名称解析失败,以及输出缓冲区不足。设置 NI_NAMEREQD 时,如果无法得到主机名,会返回错误,而不是退回数值地址。
完整示例
示例使用 NI_NUMERICHOST | NI_NUMERICSERV,因此不会依赖 DNS 或服务名数据库,输出可直接验证。
#include <arpa/inet.h>
#include <netdb.h>
#include <stdio.h>
#include <sys/socket.h>
int main(void) {
struct sockaddr_in addr = {0};
char host[INET6_ADDRSTRLEN];
char serv[16];
addr.sin_family = AF_INET;
addr.sin_port = htons(8080);
if (inet_pton(AF_INET, "127.0.0.1", &addr.sin_addr) != 1) {
fprintf(stderr, "inet_pton failed\n");
return 1;
}
/* 数值模式适合日志路径,可避免名称解析造成阻塞或结果变化。 */
int rc = getnameinfo((const struct sockaddr *)&addr,
sizeof(addr),
host, sizeof(host),
serv, sizeof(serv),
NI_NUMERICHOST | NI_NUMERICSERV);
if (rc != 0) {
fprintf(stderr, "getnameinfo: %s\n", gai_strerror(rc));
return 1;
}
printf("host=%s serv=%s\n", host, serv);
return 0;
}预期输出:
host=127.0.0.1 serv=8080边界与兼容性
addrlen 必须与实际地址结构匹配;处理同时支持 IPv4 和 IPv6 的连接代码时,应保留 Socket API 返回的实际长度,而不是固定写成 sizeof(struct sockaddr_in)。
不指定 NI_NUMERICHOST 时,主机名解析可能访问名称服务并产生等待;不指定 NI_NUMERICSERV 时,端口可能显示为服务名。需要稳定、低延迟的日志输出时优先使用两个数值标志。
字节序与地址值
uint16_t htons(uint16_t hostshort);把主机字节序的 16 位整数转换为网络字节序,最常用于 TCP/UDP 端口字段;与 ntohs 配对使用,不能混用于 32 位值。
网络字节序转换
把主机上的 16 位端口号写入 Socket 地址结构或网络协议字段前使用 htons。它把主机字节序转换为网络字节序,使同一个端口值在不同 CPU 字节序的机器之间具有一致的线上表示。
签名与参数
uint16_t htons(uint16_t hostshort);| 参数 | 类型 | 含义 | 默认值或约束 |
|---|---|---|---|
hostshort |
uint16_t |
主机字节序的 16 位无符号整数 | 无默认值;取值范围为 0~65535 |
最常见的调用是给 sockaddr_in.sin_port 赋值,例如把主机整数端口转换后保存到地址结构中。
返回与错误
返回转换后的 16 位网络字节序值。htons 没有失败返回值,也不通过 errno 报错;在大端主机上转换可能等价于原值,在小端主机上通常需要交换两个字节,但调用者不应自行根据 CPU 类型决定是否转换。
逆向读取网络字段时使用 ntohs。对于 32 位整数应使用 htonl 与 ntohl,不能用 htons 截断或代替 32 位转换。
完整示例
#include <arpa/inet.h>
#include <stdint.h>
#include <stdio.h>
#include <string.h>
int main(void) {
uint16_t host_port = 8080;
uint16_t network_port = htons(host_port);
unsigned char bytes[sizeof network_port];
/* 直接检查内存中的两个字节,可验证网络序为高字节在前。 */
memcpy(bytes, &network_port, sizeof bytes);
printf("host=%u\n", (unsigned)host_port);
printf("network bytes=%02x %02x\n", bytes[0], bytes[1]);
printf("round-trip=%u\n", (unsigned)ntohs(network_port));
return 0;
}预期输出:
host=8080
network bytes=1f 90
round-trip=8080边界与常见误用
网络字节序规定高字节在前,因此十六进制 0x1f90 的线上字节顺序是 1f 90。不要通过打印 htons 返回值的十进制数来判断转换是否正确,因为该整数被本机如何解释取决于主机字节序;检查实际字节或用 ntohs 回转验证更可靠。
在 POSIX 系统中通常包含 <arpa/inet.h>。给 sockaddr_in.sin_port 赋值时传入的是数值端口,例如 htons(8080);已经处于网络字节序的字段不要重复调用 htons。
uint32_t htonl(uint32_t hostlong);把主机字节序的 32 位整数转换为网络字节序,适用于 IPv4 地址等 32 位协议字段;接收方向对应 ntohl。
32 位网络字节序转换
向网络报文写入 32 位整数时使用 htonl,把主机字节序转换成网络字节序(大端序)。它适合长度、标志值或以整数表示的 IPv4 字段;接收同类字段后可用 ntohl 转回主机字节序。
签名
uint32_t htonl(uint32_t hostlong);POSIX 环境通常通过 <arpa/inet.h> 声明该函数。
参数与返回值
hostlong:必填,uint32_t,当前主机字节序表示的 32 位无符号整数。- 返回值:转换后的
uint32_t。其内存字节排列符合网络字节序,可直接写入需要 32 位网络序字段的协议结构。 - 失败路径:该转换没有可报告的运行时失败,不通过返回值或
errno表示错误。
htonl 只改变字节排列,不解析字符串地址,也不检查数值是否符合某个具体协议字段的业务范围。
完整示例
下面直接检查转换结果在内存中的四个字节,并使用 ntohl 验证往返转换。这样不会因主机本身是大端还是小端而误读整数打印结果。
#include <arpa/inet.h>
#include <inttypes.h>
#include <stdint.h>
#include <stdio.h>
int main(void) {
uint32_t host = UINT32_C(0x12345678);
uint32_t net = htonl(host);
const unsigned char *bytes = (const unsigned char *)&net;
printf("network bytes: %02x %02x %02x %02x\n",
(unsigned)bytes[0], (unsigned)bytes[1],
(unsigned)bytes[2], (unsigned)bytes[3]);
printf("round trip: 0x%08" PRIx32 "\n", ntohl(net));
return 0;
}预期输出:
network bytes: 12 34 56 78
round trip: 0x12345678边界与兼容性
不要通过直接打印 htonl 返回值的十六进制整数来判断“网络序是否正确”;在小端主机上,整数显示值可能看起来被反转,而真正需要检查的是内存中的字节顺序。处理文本形式 IPv4 地址时,应使用地址解析函数生成二进制地址,而不是自行拆分字符串后依赖 htonl 拼装。Windows Winsock 也提供同名转换函数,但头文件和套接字环境与这里的 POSIX 示例不同。
uint16_t ntohs(uint16_t netshort);把网络字节序的 16 位整数转换为主机字节序,读取协议端口或其他 16 位字段时使用;发送前通常反向调用 htons。
16 位网络序转主机序
从网络报文、套接字地址或其他二进制协议中读出 16 位字段后,使用 ntohs 把网络字节序转换为当前主机字节序。端口号是最常见的场景;发送 16 位字段时通常使用反向函数 htons。
签名
uint16_t ntohs(uint16_t netshort);POSIX 环境通常通过 <arpa/inet.h> 声明该函数。
参数与返回值
netshort:必填,uint16_t,其两个字节应按网络字节序表示。- 返回值:转换成当前主机字节序后的
uint16_t,可作为普通整数参与比较、计算或输出。 - 失败路径:该转换没有错误返回,也不会使用
errno报告失败。
ntohs 不知道字段代表端口、长度还是标志位,只执行固定的 16 位字节序转换。
完整示例
下面模拟从网络报文读取两个字节 0x1f 0x90。它们按大端序组成十六进制值 0x1f90,即十进制端口 8080。使用 memcpy 写入 uint16_t 可避免直接把任意字节地址强制转换成未对齐整数指针。
#include <arpa/inet.h>
#include <stdint.h>
#include <stdio.h>
#include <string.h>
int main(void) {
const unsigned char wire[2] = {0x1f, 0x90};
uint16_t netshort;
memcpy(&netshort, wire, sizeof netshort);
uint16_t hostshort = ntohs(netshort);
printf("port: %u\n", (unsigned)hostshort);
return 0;
}预期输出:
port: 8080边界与兼容性
只有字段确实采用网络字节序时才调用 ntohs;如果数据已经是主机序,再转换一次会在小端机器上得到错误值。读取 sockaddr_in.sin_port 时应使用 ntohs 后再作为普通端口号处理,而写入 sin_port 时使用 htons。对于 32 位字段应改用 ntohl,不要截断后再做 16 位转换。Windows Winsock 同样提供 ntohs,但其头文件和套接字环境与这里的 POSIX 示例不同。
uint32_t ntohl(uint32_t netlong);把网络字节序的 32 位整数转换为主机字节序,常用于读取 IPv4 地址或协议中的 32 位数值字段。
32 位网络序转主机序
读取来自网络协议、Socket 或二进制报文的 32 位整数时,用 ntohl 把网络字节序转换成当前主机使用的字节序。转换后的值才能安全地按普通 uint32_t 参与比较、计算或输出。
签名
uint32_t ntohl(uint32_t netlong);POSIX 环境通常从 <arpa/inet.h> 引入声明。
| 参数 | 类型 | 必填 | 含义 |
|---|---|---|---|
netlong |
uint32_t |
是 | 按网络字节序编码的 32 位无符号整数 |
返回值与错误
返回转换后的主机字节序 uint32_t。该函数没有单独的错误返回值,也不会通过返回结果指出输入是否本来就是主机字节序,因此调用方必须明确字段的协议字节序。
在大端主机上转换可能不改变位模式;在小端主机上会调整字节顺序。不要根据当前机器上的观察结果省略转换,否则代码迁移到不同架构时可能得到错误数值。
完整示例
下面先用 htonl 构造一个确定的网络序值,再使用 ntohl 转回主机序,便于在不同端序机器上验证相同行为。
#include <arpa/inet.h>
#include <inttypes.h>
#include <stdint.h>
#include <stdio.h>
int main(void) {
uint32_t original = UINT32_C(0x12345678);
uint32_t network_value = htonl(original);
/* ntohl 的输入必须是网络字节序的 32 位整数。 */
uint32_t host_value = ntohl(network_value);
printf("0x%08" PRIx32 "\n", host_value);
return 0;
}预期输出:
0x12345678边界与兼容性
ntohl 只负责 32 位整数的字节序转换,不会解析文本 IP,也不会验证字段语义。16 位字段应使用 ntohs;如果协议字段不是固定 32 位,先确认协议定义再选择转换函数。
该声明适用于 POSIX 风格 Socket 环境。Windows Winsock 提供相同语义的 ntohl,但所需头文件和初始化要求与 POSIX 不同。