$darkmode
RuiChing API 参考手册
V0.9.1
BSD-SOCKET

提供网络通信与协议栈相关的接口,支持多种网络协议和配置管理 更多...

函数

int socket (int domain, int type, int protocol)
 创建网络套接字 更多...
 
int connect (int s, const struct sockaddr *name, socklen_t namelen)
 发起套接字连接请求 更多...
 
int bind (int s, const struct sockaddr *name, socklen_t namelen)
 将套接字绑定到特定的本地地址和端口 更多...
 
int listen (int s, int backlog)
 将套接字标记为被动套接字,准备接受传入连接 更多...
 
int accept (int s, struct sockaddr *addr, socklen_t *addrlen)
 在监听套接字上接受一个传入的连接 更多...
 
int send (int s, const void *dataptr, size_t size, int flags)
 在已连接的套接字上发送数据 更多...
 
int recv (int s, void *mem, size_t len, int flags)
 从已连接的套接字接收数据 更多...
 
int sendto (int s, const void *dataptr, size_t size, int flags, const struct sockaddr *to, socklen_t tolen)
 使用未连接的套接字向指定地址发送数据 更多...
 
int recvfrom (int s, void *mem, size_t len, int flags, struct sockaddr *from, socklen_t *fromlen)
 使用未连接的套接字从指定地址接收数据 更多...
 
int closesocket (int s)
 关闭一个套接字 更多...
 
int getsockopt (int s, int level, int optname, void *optval, socklen_t *optlen)
 获取套接字选项 更多...
 
int setsockopt (int s, int level, int optname, const void *optval, socklen_t optlen)
 设置套接字选项 更多...
 
int getaddrinfo (const char *nodename, const char *servname, const struct addrinfo *hints, struct addrinfo **res)
 获取主机和服务的地址信息 更多...
 
void freeaddrinfo (struct addrinfo *ai)
 释放由 getaddrinfo 分配的 addrinfo 结构体链表内存 更多...
 
int shutdown (int s, int how)
 关闭套接字的部分或全部通信(半关闭) 更多...
 
int recvmsg (int send, struct msghdr *message, int flags)
 从套接字接收消息。 更多...
 
int sendmsg (int s, const struct msghdr *message, int flags)
 在套接字上发送消息 更多...
 
int getpeername (int s, struct sockaddr *name, socklen_t *namelen)
 获取与套接字连接的对端地址 更多...
 
int getsockname (int s, struct sockaddr *name, socklen_t *namelen)
 获取套接字的本地地址信息 更多...
 
int ioctlsocket (int s, long cmd, void *arg)
 控制套接字的 I/O 模式 更多...
 
int socketpair (int domain, int type, int protocol, int *fds)
 创建一对已连接的套接字 更多...
 
struct hostent * gethostbyname (const char *name)
 根据主机名获取主机信息 更多...
 
int gethostbyname_r (const char *name, struct hostent *ret, char *buf, size_t buflen, struct hostent **result, int *h_errnop)
 线程安全地通过主机名获取主机信息 更多...
 
int select (int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout)
 [in] 同步 I/O 复用:在一组文件描述符上复用输入/输出操作。 更多...
 

详细描述

提供网络通信与协议栈相关的接口,支持多种网络协议和配置管理

函数说明

◆ socket()

int socket ( int  domain,
int  type,
int  protocol 
)

创建网络套接字

此函数用于创建套接字,并返回网络通信的文件描述符。 创建的套接字可用于绑定、监听、接收和发送数据等操作

参数
[in]domain通信协议族(地址族),定义套接字所使用的协议。常见取值包括:
协议族 含义
AF_INET IPv4
AF_AT AT 套接字
[in]type套接字类型,决定数据传输的特性。常见取值包括:
类型 含义
SOCK_STREAM 面向连接的字节流通信(如 TCP)
SOCK_DGRAM 无连接的数据报通信(如 UDP)
SOCK_RAW 提供原始网络协议访问
[in]protocol指定套接字所使用的协议。通常设置为 0, 由系统自动选择默认协议:
协议类型 默认协议
SOCK_STREAM TCP
SOCK_DGRAM UDP
返回值
>=0成功,返回文件描述符
-1失败

◆ connect()

int connect ( int  s,
const struct sockaddr *  name,
socklen_t  namelen 
)

发起套接字连接请求

此函数用于将由 s 指定的套接字连接到由 name 指定的服务器地址。 套接字必须先通过 socket() 创建,对于某些类型的套接字,可能需要在调用 connect() 前 ,使用 bind() 绑定到本地地址

参数
[in]s要连接的套接字文件描述符
[in]name指向 sockaddr 结构的指针,指定服务器的目标地址。 具体结构类型(如 IPv4 使用 sockaddr_in)取决于地址族。
[in]namelenname 指向的地址结构的长度(字节数)
返回值
0连接成功
-1连接失败
注解
  • connect() 通常由客户端套接字调用,用于与服务器建立连接。 对于面向连接的协议(如 TCP),此操作会发起连接握手。 对于无连接协议(如 UDP),此操作会指定固定的对端地址

◆ bind()

int bind ( int  s,
const struct sockaddr *  name,
socklen_t  namelen 
)

将套接字绑定到特定的本地地址和端口

此函数将本地地址分配给套接字,由 name 参数指定。 该地址允许套接字接收发送到此地址的数据

参数
[in]s套接字的文件描述符
[in]name指向 sockaddr 结构的指针,指定要绑定的地址。 结构根据地址族不同而不同,如 IPv4 使用 sockaddr_in
[in]namelen指向的 sockaddr 结构的长度(字节数)
返回值
0绑定成功
-1绑定失败
注解
  • 必须先使用 socket() 创建套接字后才能调用 bind()。 绑定通常用于服务器套接字,指定本地 IP 和端口以监听连接。 如果端口设置为 0,系统会自动分配可用端口

◆ listen()

int listen ( int  s,
int  backlog 
)

将套接字标记为被动套接字,准备接受传入连接

此函数将套接字设置为可接受传入连接请求的状态。套接字必须先通过 socket() 创建, 并使用 bind() 绑定到本地地址

参数
[in]s要设置为监听模式的套接字文件描述符
[in]backlog可以排队等待接受的最大挂起连接数。 如果到达的连接数超过 backlog 限制,可能会被拒绝或忽略, 直到服务器接受部分挂起连接为止
返回值
0成功
-1失败
注解
调用 listen() 后,可以使用 accept() 处理连接请求。 backlog 大小影响在被拒绝前可等待接受的连接数

◆ accept()

int accept ( int  s,
struct sockaddr *  addr,
socklen_t *  addrlen 
)

在监听套接字上接受一个传入的连接

此函数从由 s 指定的监听套接字的待处理连接队列中提取第一个连接请求, 并为该连接创建一个新的套接字

参数
[in]s监听套接字的文件描述符
[out]addr一个指向 sockaddr 结构的指针,该结构将接收连接实体的地址。
[out]addrlen一个指向包含 addr 大小的变量的指针。当函数返回时, 此变量将保存实际返回的地址大小
返回值
>=0返回已接受连接的新文件描述符
-1失败
注解
  • 套接字 s 必须使用 socket() 创建, 使用 bind() 绑定, 并使用 listen() 设置为监听状态
  • 原始套接字 s 保持打开状态,并继续监听其他传入的连接。 返回的文件描述符用于与已连接的客户端进行通信

◆ send()

int send ( int  s,
const void *  dataptr,
size_t  size,
int  flags 
)

在已连接的套接字上发送数据

此函数用于在指定的文件描述符 s 所代表的已连接套接字上发送数据。 通常用于面向连接的协议(如 TCP)

参数
[in]s要发送数据的套接字文件描述符,该套接字必须已连接到远程端点
[in]dataptr指向包含待发送数据的缓冲区的指针
[in]size要从缓冲区发送的数据字节数
[in]flags指定发送操作的行为。常用标志包括:
标志位 含义
0 默认操作
MSG_DONTWAIT 非阻塞操作
MSG_NOSIGNAL 发生错误时阻止发送 SIGPIPE 信号
返回值
>0成功,返回已发送的字节数
-1失败,
0远程端关闭连接
注解
send() 函数不保证一次调用会发送所有数据。 如果实际发送的字节数少于请求的字节数,剩余数据应通过后续调用继续发送

◆ recv()

int recv ( int  s,
void *  mem,
size_t  len,
int  flags 
)

从已连接的套接字接收数据

此函数从已连接的套接字读取数据,并将其存储到指定的缓冲区中。 通常用于面向连接的协议(如 TCP)

参数
[in]s要接收数据的已连接套接字的文件描述符
[out]mem指向用于存放接收数据的缓冲区的指针
[in]len缓冲区可接收的最大字节数
[in]flags指定接收操作的行为。常用标志包括:
标志位 含义
0 默认操作
MSG_DONTWAIT 非阻塞操作
MSG_PEEK 仅查看数据但不将其从队列移除
返回值
>0成功时返回实际接收到的字节数
-1失败
0表示远程端已关闭连接
注解
recv() 函数一次调用可能无法接收所有请求的字节数。 需要多次调用 recv() 以读取完整数据

◆ sendto()

int sendto ( int  s,
const void *  dataptr,
size_t  size,
int  flags,
const struct sockaddr *  to,
socklen_t  tolen 
)

使用未连接的套接字向指定地址发送数据

此函数通常用于无连接协议(如 UDP),通过 to 参数指定目标地址,将数据发送到特定目的地

参数
[in]s要发送数据的套接字文件描述符
[in]dataptr指向待发送数据缓冲区的指针
[in]size要发送的数据字节数
[in]flags指定发送操作的行为。常用标志包括:
标志位 含义
0 默认操作
MSG_DONTWAIT 非阻塞操作
MSG_NOSIGNAL 发生错误时阻止发送 SIGPIPE 信号
[in]to指向 sockaddr 结构的指针,指定目标地址 结构类型根据地址族不同而不同(如 IPv4 使用 sockaddr_in)。
[in]tolento 指向的地址结构的长度(字节数)
返回值
>=0成功,返回已发送的字节数
-1失败
注解
  • send()不同,sendto() 每次调用都可指定目标地址, 因此既可用于已连接也可用于未连接的套接字。 在无连接协议中,sendto() 通常无需事先调用 connect()

◆ recvfrom()

int recvfrom ( int  s,
void *  mem,
size_t  len,
int  flags,
struct sockaddr *  from,
socklen_t *  fromlen 
)

使用未连接的套接字从指定地址接收数据

此函数从套接字读取数据,并将其存储到指定的缓冲区中。通常用于无连接协议(如 UDP), 可从特定源地址接收数据

参数
[in]s要接收数据的套接字文件描述符
[out]mem指向用于存放接收数据的缓冲区的指针
[in]len缓冲区可接收的最大字节数
[in]flags指定接收操作的行为。常用标志包括:
标志位 含义
0 默认操作
MSG_DONTWAIT 非阻塞操作
MSG_PEEK 仅查看数据但不将其从队列移除
[out]from指向 sockaddr 结构的指针,该结构将被填充为发送方的地址。 这是数据来源的地址
[in,out]fromlen指向变量的指针,初始时包含 from 结构的大小, 返回时将保存实际返回的地址大小
返回值
>0成功时返回实际接收到的字节数
-1失败
0表示远程端已关闭连接
注解
  • recvfrom() 适用于从任意源地址接收数据,特别适合用于对端地址可能变化的无连接协议。 from 参数会被填充为发送方的地址,可用于识别数据来源

◆ closesocket()

int closesocket ( int  s)

关闭一个套接字

此函数关闭由文件描述符 s 指定的套接字。关闭后,该套接字不能再用于通信。 任何尚未传输的数据可能会丢失

参数
[in]s要关闭的套接字文件描述符
返回值
0关闭成功
-1关闭失败
注解
  • 调用 closesocket() 后,套接字描述符变为无效,不能再用于任何操作。 应及时关闭不再使用的套接字以释放系统资源

◆ getsockopt()

int getsockopt ( int  s,
int  level,
int  optname,
void *  optval,
socklen_t *  optlen 
)

获取套接字选项

此函数用于获取由文件描述符 s 指定的套接字的当前选项值。 选项由 level 和 optname 参数指定。

参数
[in]s要获取选项的套接字文件描述符
[in]level选项所在的协议层。常见取值包括:
协议层 含义
SOL_SOCKET 套接字级选项
IPPROTO_IP IPv4 相关选项
IPPROTO_TCP TCP 相关选项
[in]optname要获取的选项名称。常见选项包括:
选项名 含义
SO_REUSEADDR 是否允许地址重用
SO_RCVBUF 接收缓冲区大小
TCP_NODELAY TCP 是否禁用 Nagle 算法
[out]optval指向用于存放选项值的缓冲区指针,缓冲区需足够大以容纳选项值
[in,out]optlen指向变量的指针,初始时为 optval 缓冲区大小, 返回时为实际返回的选项值大小
返回值
0成功
-1失败
注解
  • getsockopt() 可用于查询套接字的配置和当前状态,如缓冲区大小、超时设置、协议特性等

◆ setsockopt()

int setsockopt ( int  s,
int  level,
int  optname,
const void *  optval,
socklen_t  optlen 
)

设置套接字选项

此函数用于为由文件描述符 s 指定的套接字设置特定选项。 套接字选项影响套接字的行为,通过 level 和 optname 参数指定

参数
[in]s要设置选项的套接字文件描述符
[in]level选项所在的协议层。常见取值包括:
协议层 含义
SOL_SOCKET 套接字级选项
IPPROTO_IP IPv4 相关选项
IPPROTO_TCP TCP 相关选项
[in]optname要设置的选项名称。常见选项包括:
选项名 含义
SO_REUSEADDR 是否允许地址重用
SO_RCVBUF 设置接收缓冲区大小
TCP_NODELAY 是否禁用 TCP 的 Nagle 算法
[in]optval指向包含要设置值的缓冲区指针。缓冲区类型取决于具体选项
[in]optlenoptval 缓冲区的大小(字节数)
返回值
0设置成功
-1设置失败
注解
  • setsockopt() 可用于配置套接字的多种行为,如超时、缓冲区大小、协议特性等。 合理设置选项可影响套接字性能和资源使用

◆ getaddrinfo()

int getaddrinfo ( const char *  nodename,
const char *  servname,
const struct addrinfo *  hints,
struct addrinfo **  res 
)

获取主机和服务的地址信息

此函数根据给定的主机名(nodename)和服务名(servname),以及可选的查询条件(hints), 获取对应的地址信息,并通过 res 返回结果链表

参数
[in]nodename主机名,可以是域名或IP地址字符串,若为NULL则表示本地地址
[in]servname服务名,可以是端口号字符串或服务名称,若为NULL则不指定服务
[in]hints指向 addrinfo 结构体的指针,用于指定查询条件,可为NULL
[out]res指向结果链表头指针的指针,函数成功时会分配并返回地址信息链表
返回值
0成功
-1失败
注解
  • 使用完 res 后需调用 freeaddrinfo 释放内存

◆ freeaddrinfo()

void freeaddrinfo ( struct addrinfo *  ai)

释放由 getaddrinfo 分配的 addrinfo 结构体链表内存

此函数用于释放通过 getaddrinfo 获取的 addrinfo 结构体及其相关的所有内存资源

参数
[in]ai指向需要释放的 addrinfo 结构体链表的指针
注解
  • 释放后,ai 指向的内存不可再被访问

◆ shutdown()

int shutdown ( int  s,
int  how 
)

关闭套接字的部分或全部通信(半关闭)

此函数根据 how 参数的取值,禁用指定套接字的进一步发送或接收操作。 注意,该函数不会关闭套接字本身,仍需调用 close()closesocket() 彻底关闭

参数
[in]s要进行关闭操作的套接字文件描述符
[in]how指定关闭的类型,可取以下值:
含义
SHUT_RD 禁止进一步读取(接收数据)
SHUT_WR 禁止进一步写入(发送数据)
SHUT_RDWR 同时禁止读写(完全关闭)
返回值
0操作成功
-1操作失败
注解
  • shutdown() 用于优雅地关闭套接字的读/写方向, 常用于如 TCP 连接只关闭写端但仍需接收数据的场景
  • 该函数不会释放套接字资源,需后续调用 close()/closesocket() 完全关闭

◆ recvmsg()

int recvmsg ( int  send,
struct msghdr *  message,
int  flags 
)

从套接字接收消息。

recvmsg() 函数从套接字 s 接收数据,并将其存储到由 msghdr 结构描述的缓冲区中。 该函数支持复杂的数据结构,包括多个数据缓冲区和可选的控制信息(辅助数据)

参数
[in]s要接收数据的套接字文件描述符
[out]message指向 msghdr 结构的指针,用于存放接收的数据和相关信息
字段名 含义
msg_name 用于存放源地址的缓冲区(适用于无连接套接字)。
msg_namelen msg_name 缓冲区的大小。
msg_iov iovec 结构数组,指向用于存放接收数据的缓冲区。
msg_iovlen msg_iov 数组的元素个数。
msg_control 用于存放辅助数据(如接收的文件描述符)的缓冲区。
msg_controllen 辅助数据缓冲区的大小。
msg_flags recvmsg() 调用设置的标志,指示消息状态。
[in]flags指定接收操作的行为。常用标志包括:
标志位 含义
MSG_DONTWAIT 非阻塞接收
MSG_PEEK 仅查看数据但不将其从队列移除
MSG_WAITALL 等待接收完整数据
返回值
>0成功时返回实际接收到的字节数
-1失败
注解
recvmsg() 适用于需要接收多缓冲区数据或辅助数据的场景。 可用于面向连接和无连接的套接字,适应多种通信需求

◆ sendmsg()

int sendmsg ( int  s,
const struct msghdr *  message,
int  flags 
)

在套接字上发送消息

sendmsg() 函数通过套接字 s 发送由 msghdr 结构描述的数据。 该函数适用于发送包含多个缓冲区、控制信息或用于数据报套接字的复杂消息

参数
[in]s要发送消息的套接字文件描述符
[in]message指向 msghdr 结构的指针,包含数据、地址和控制信息:
字段名 含义
msg_name 可选的目标地址(用于无连接套接字)
msg_namelen 目标地址的长度
msg_iov 指向待发送数据缓冲区的 iovec 结构数组
msg_iovlen msg_iov 数组的元素个数
msg_control 可选的辅助数据(如 UNIX 域套接字的文件描述符)
msg_controllen 辅助数据缓冲区的大小
msg_flags 与消息相关的标志位
[in]flags指定发送操作的行为。常用标志包括:
标志位 含义
MSG_DONTWAIT 非阻塞发送
MSG_EOR 指示记录结束(面向记录的套接字)
返回值
>0成功时返回实际发送的字节数
-1失败
注解
  • sendmsg() 适用于需要发送多缓冲区数据或辅助数据的场景, 支持灵活的通信方式,如附加文件描述符。可用于面向连接和无连接的套接字

◆ getpeername()

int getpeername ( int  s,
struct sockaddr *  name,
socklen_t *  namelen 
)

获取与套接字连接的对端地址

此函数用于获取与套接字 s 连接的对端(远程)地址信息。 通常用于已连接的套接字(如 TCP),以获取对端主机的地址和端口等信息

参数
[in]s已连接套接字的文件描述符
[out]name指向 sockaddr 结构的指针,该结构将被填充为对端地址。 结构类型(如 IPv4 使用 sockaddr_in)取决于套接字的地址族
[in,out]namelen指向变量的指针,初始时为 name 结构的大小, 返回时将保存实际返回的地址大小
返回值
0成功
-1失败
注解
  • getpeername() 常用于获取 TCP 连接对端的 IP 地址和端口等信息。 仅对已处于连接状态的套接字有效

◆ getsockname()

int getsockname ( int  s,
struct sockaddr *  name,
socklen_t *  namelen 
)

获取套接字的本地地址信息

此函数用于获取与套接字 s 关联的本地地址(IP 地址和端口)。 通常用于已绑定或已连接的套接字,以确定其实际使用的本地地址和端口。

参数
[in]s套接字的文件描述符
[out]name指向 sockaddr 结构的指针,该结构将被填充为本地地址。 结构类型(如 IPv4 使用 sockaddr_in)取决于套接字的地址族
[in,out]namelen指向变量的指针,初始时为 name 结构的大小, 返回时将保存实际返回的地址大小
返回值
0成功
-1失败
注解
  • getsockname() 常用于获取由系统自动分配端口(如绑定端口为 0)时, 实际分配的本地地址和端口信息。
  • 可用于调试或记录本地套接字信息

◆ ioctlsocket()

int ioctlsocket ( int  s,
long  cmd,
void *  arg 
)

控制套接字的 I/O 模式

ioctlsocket() 函数用于操作由文件描述符 s 指定的套接字的 I/O 模式。 主要用于启用或禁用套接字的非阻塞模式,或执行其他与套接字相关的特定操作

参数
[in]s要控制的套接字文件描述符
[in]cmd指定要执行操作的命令。常用命令包括:
命令 含义
FIONBIO 启用或禁用非阻塞模式。arg 非零启用,零禁用。
FIONREAD 获取当前可读取的字节数,结果存储在 arg 指向的变量中。
[in,out]arg指向命令参数的指针。该参数的类型和含义取决于 cmd 的具体命令。 例如,FIONBIO 时,arg 指向一个 long 类型变量, 非零表示启用,零表示禁用非阻塞模式
返回值
0操作成功
-1操作失败
注解
  • 此函数主要用于 Windows 平台,是 Winsock API 的一部分。 其功能类似于 UNIX 类系统中的 fcntl()。 通过 ioctlsocket() 可以灵活地设置套接字的工作模式, 例如设置为非阻塞模式,便于实现异步 I/O 操作。 除了常用的 FIONBIO 和 FIONREAD,还可以根据实际需求使用其他命令进行扩展操作
警告
  • 在不同平台上,ioctlsocket() 的支持命令和行为可能存在差异, 使用时需参考具体平台文档。 非阻塞模式下,I/O 操作可能会立即返回,需正确处理返回值和错误码

◆ socketpair()

int socketpair ( int  domain,
int  type,
int  protocol,
int *  fds 
)

创建一对已连接的套接字

socketpair() 函数用于创建一对互相连接的套接字, 常用于同一台机器上进程或线程间的双向通信。 该函数主要用于 UNIX 类操作系统中的进程间通信(IPC)

参数
[in]domain通信协议族(地址族), 通常使用 AF_UNIX(或 AF_LOCAL)用于本地通信
[in]type套接字类型,常见取值包括:
  • SOCK_STREAM:提供可靠的面向连接通信
  • SOCK_DGRAM:提供无连接、不可靠通信
[in]protocol套接字所使用的协议。通常设置为 0, 表示根据 domain 和 type 选择默认协议
[out]fds整型数组,长度为 2。成功时,fds[0] 和 fds[1] 分别为这对已连接套接字的文件描述符
返回值
0成功
-1失败
注解
  • socketpair() 常用于父子进程(如 fork() 后)或线程间建立通信通道。 向一端写入的数据可从另一端读取
  • 该函数主要在 UNIX 类系统支持,Windows 平台可能不支持

◆ gethostbyname()

struct hostent* gethostbyname ( const char *  name)

根据主机名获取主机信息

此函数用于根据主机名检索主机的相关信息(如 IP 地址等)。

参数
[in]name主机名字符串
返回值
!RT_NULL指向 hostent 结构体的指针,包含主机信息
NULL失败

◆ gethostbyname_r()

int gethostbyname_r ( const char *  name,
struct hostent *  ret,
char *  buf,
size_t  buflen,
struct hostent **  result,
int *  h_errnop 
)

线程安全地通过主机名获取主机信息

此函数是 gethostbyname 的可重入版本,用于根据主机名 name 查询主机信息, 并将结果存储在 ret 指向的结构体中。结果缓冲区由 buf 提供,大小为 buflen。 查询结果的指针通过 result 返回,错误码通过 h_errnop 返回

参数
[in]name要查询的主机名
[in]ret用于存储主机信息的结构体指针
[out]buf用于存储主机信息的缓冲区
[in]buflen缓冲区 buf 的大小
[out]result查询结果的指针输出参数
[out]h_errnop错误码输出参数
返回值
0成功
-1失败

◆ select()

int select ( int  nfds,
fd_set *  readfds,
fd_set *  writefds,
fd_set *  exceptfds,
struct timeval *  timeout 
)

[in] 同步 I/O 复用:在一组文件描述符上复用输入/输出操作。

参数
[in]nfds所有三个集合中编号最高的文件描述符加 1。
[in]readfds指向一组文件描述符的指针,用于检查其是否可读。
[in]writefds指向一组文件描述符的指针,用于检查其是否可写。
[in]exceptfds指向一组文件描述符的指针,用于检查其是否有异常。
[in]timeout等待任一指定文件描述符就绪的最大时间。
返回值
>=0成功
<0失败