nanomsg接口函数以及用法
函数的相关解释均翻译自官网,有不合理的地方欢迎广大网友批评指正!
包含以下函数
int nn_socket (int domain, int protocol);
int nn_close (int s);
int nn_setsockopt (int s, int level, int option, const void *optval, size_t optvallen);
int nn_getsockopt (int s, int level, int option, void *optval, size_t *optvallen);
int nn_bind (int s, const char *addr);
int nn_connect (int s, const char *addr);
int nn_shutdown (int s, int how);
int nn_send (int s, const void *buf, size_t len, int flags);
int nn_recv (int s, void *buf, size_t len, int flags);
int nn_sendmsg (int s, const struct nn_msghdr *msghdr, int flags);
int nn_recvmsg (int s, struct nn_msghdr *msghdr, int flags);
1、nn_socket 创建一个SP套接字
int nn_socket (int domain, int protocol); | ||
---|---|---|
参数 | int domain //SP socket类型 | AF_SP//标准全功能 SP 套接字 |
AF_SP_RAW//比较原始的套接字,一般用上面那个 | ||
int protocol //套接字协议类型 | 详细信息见 protocol表 | |
返回值 | 成功返回文件描述符,失败返回-1,并且将errno置为错误类型的值 | |
错误值 | EAFNOSUPPORT | 不支持指定的地址系列 |
EINVAL | 未知协议 | |
EMFILE | 达到打开的SP套接字总数限制或文件描述符的OS限制 | |
ETERM | 数据库终止了 | |
用例 | int s = nn_socket (AF_SP, NN_PUB); | |
功能描述 | 使用指定的域和协议创建一个 sp 套接字 返回新创建的套接字的文件描述符 |
2、int nn_close (int s);关闭一个SP套接字
3、nn_setsockopt 设置套接字选项
int nn_setsockopt (int s, int level, int option, const void *optval, size_t optvallen); | ||
---|---|---|
参数 | int s //SP套接字 | ---- |
int level //选项所在的协议级别 | 详细信息见 level表 | |
int option //level的操作参数 | option选项见下option表 | |
const void *optval //操作字符 | ---- | |
size_t optvallen //操作字符长度 | ---- | |
返回值 | 成功返回0,失败返回-1,并且将errno置为错误类型的值 | |
错误值 | ENOPROTOOPT | option对level的指示无效 |
EINVAL | 未知协议 | |
EBADF | 所提供的socket无效 | |
ETERM | 数据库终止了 | |
用例 | int linger = 1000; nn_setsockopt (s, NN_SOL_SOCKET, NN_LINGER, &linger, sizeof (linger)); nn_setsockopt (s, NN_SUB, NN_SUB_SUBSCRIBE, "ABC", 3); | |
功能描述 | 设置选项的值 |
level参数列举 | |
---|---|
NN_SOL_SOCKET | 通用套接字级别选项 |
NN_SUB | 特定的套接字类型的选项,用套接字作为level参数 |
NN_TCP | 对于特定于传输的选项,使用传输的id作为leave参数 |
NN_SOL_SOCKET的参数列举 | |
---|---|
NN_SNDBUF | 发送缓冲区的大小,单位为字节。为了防止对大于缓冲区的消息进行阻塞,除了发送缓冲区中的数据之外,还可以缓冲正好一个消息。这个选项的类型是 int。默认值是128kb |
NN_RCVBUF | 接收缓冲区的大小,单位为字节。为了防止对大于缓冲区的消息进行阻塞,除了发送缓冲区中的数据之外,还可以缓冲正好一个消息。这个选项的类型是 int。默认值是128kb |
NN_RCVMAXSIZE | 可接收的最大消息大小(以字节为单位)。负值意味着接收的大小仅受可用可寻址内存的限制。这个选项的类型是 int。默认值是1024kb。 |
NN_SNDTIMEO | 套接字上发送操作的超时,以毫秒为单位。如果无法在指定的超时内发送消息,则返回原始输出错误。负值表示无限超时。选项的类型是 int。默认值是 -1。 |
NN_RCVTIMEO | 套接字上 recv 操作的超时,以毫秒为单位。如果在指定的超时内无法接收消息,则返回原始输出错误。负值表示无限超时。选项的类型是 int。默认值是 -1。 |
NN_RECONNECT_IVL | 对于基于连接的传输协议(如 tcp) ,此选项指定在尝试重新建立连接之前,当连接中断时等待的时间(毫秒)。请注意,实际的重新连接间隔可能在一定程度上是随机的,以防止严重的重新连接风暴。选项的类型是 int。默认值为100(0.1秒)。 |
NN_RECONNECT_IVL_MAX | 此选项仅用于NN_RECONNECT_IVL选项。它指定了最大重新连接间隔。每次重新连接尝试时,前一个间隔会加倍,直到到达NN_RECONNECT_IVL_MAX。值为零意味着没有执行截断二进制指数避退算法重新连接,重新连接间隔只基于NN_RECONNECT_IVL。如果重新连接最大值小于NN_RECONNECT_IVL_MAX,它将被忽略。选项的类型是 int。默认值是0。 |
NN_SNDPRIO | 为随后添加到套接字的端点设置出站优先级。此选项对向所有对等点发送消息的套接字类型没有影响。但是,如果套接字类型将每个消息发送到单个对等点(或有限的对等点集) ,具有高优先级的对等点优先于具有低优先级的对等点。选项的类型是 int。最高优先级是1最低优先级是16。默认值是8。 |
NN_RCVPRIO | 设置随后添加到套接字的端点的入站优先级。此选项对无法接收消息的套接字类型没有影响。在接收消息时,从优先级较高的对等点接收消息,然后再从优先级较低的对等点接收消息。选项的类型是 int。最高优先级是1最低优先级是16。默认值是8。 |
NN_IPV4ONLY | 如果设置为1,则只使用 ipv4地址。如果设置为0,则使用 ipv4和 ipv6地址。选项的类型是 int。默认值是1。 |
NN_SOCKET_NAME | 用于错误报告和统计的套接字名称。选项的类型是 string。默认值是“socket.n”,其中 n 是套接字整数。 |
NN_MAXTTL | 设置消息在被删除之前可以通过的最大“跃点”数。每次接收到消息时(例如通过 nn _ device (3)函数)计为单跳。这提供了一种防止无意中发生循环的保护形式。 |
NN_LINGER | 此选项未实现,不应在新代码中使用。如果应用程式需要确保其讯息已传送至远端对端,则应使用确认(在 NN_REQ sockets 上收到回覆时暗示) ,或在调用 nn_close或退出应用程式前插入适当的延迟。 |
4、int nn_getsockopt (int s, int level, int option, void *optval, size_t *optvallen);获取套接字选项
int nn_getsockopt (int s, int level, int option, void *optval, size_t *optvallen); | ||
---|---|---|
参数 | int s //SP套接字 | ---- |
int level //选项所在的协议级别 | 详细信息见 level表 | |
int option //level的操作参数 | option选项见下option表 | |
const void *optval //操作字符 | ---- | |
size_t *optvallen //操作字符长度 | ---- | |
返回值 | 成功返回0,失败返回-1,并且将errno置为错误类型的值 | |
错误值 | ENOPROTOOPT | option对level的指示无效 |
EBADF | 所提供的socket无效 | |
ETERM | 数据库终止了 | |
用例 | int linger; size_t sz = sizeof (linger); nn_getsockopt (s, NN_SOL_SOCKET, NN_LINGER, &linger, &sz); | |
功能描述 | 获取选项的值 |
NN_SOL_SOCKET的参数列举 | |
---|---|
NN_DOMAIN | 返回传递给 nn_socket()的域常量 |
NN_PROTOCOL | 返回传递给nn_socket()的协议常量。 |
NN_LINGER | 指定在调用nn_close()之后套接字应该尝试发送挂起的出站消息的时间,以毫秒为单位。负值意味着无限徘徊。选项的类型是 int。默认值为1000(1秒)。 |
NN_SNDBUF | 发送缓冲区的大小,单位为字节。为了防止对大于缓冲区的消息进行阻塞,除了发送缓冲区中的数据之外,还可以缓冲正好一个消息。这个选项的类型是 int。默认值是128kb |
NN_RCVBUF | 接收缓冲区的大小,单位为字节。为了防止对大于缓冲区的消息进行阻塞,除了发送缓冲区中的数据之外,还可以缓冲正好一个消息。这个选项的类型是 int。默认值是128kb |
NN_RCVMAXSIZE | 可接收的最大消息大小(以字节为单位)。负值意味着接收的大小仅受可用可寻址内存的限制。这个选项的类型是 int。默认值是1024kb。 |
NN_SNDTIMEO | 套接字上发送操作的超时,以毫秒为单位。如果无法在指定的超时内发送消息,则返回原始输出错误。负值表示无限超时。选项的类型是 int。默认值是 -1。 |
NN_RCVTIMEO | 套接字上 recv 操作的超时,以毫秒为单位。如果在指定的超时内无法接收消息,则返回原始输出错误。负值表示无限超时。选项的类型是 int。默认值是 -1。 |
NN_RECONNECT_IVL | 对于基于连接的传输协议(如 tcp) ,此选项指定在尝试重新建立连接之前,当连接中断时等待的时间(毫秒)。请注意,实际的重新连接间隔可能在一定程度上是随机的,以防止严重的重新连接风暴。选项的类型是 int。默认值为100(0.1秒)。 |
NN_RECONNECT_IVL_MAX | 此选项仅用于NN_RECONNECT_IVL选项。它指定了最大重新连接间隔。每次重新连接尝试时,前一个间隔会加倍,直到到达NN_RECONNECT_IVL_MAX。值为零意味着没有执行截断二进制指数避退算法重新连接,重新连接间隔只基于NN_RECONNECT_IVL。如果重新连接最大值小于NN_RECONNECT_IVL_MAX,它将被忽略。选项的类型是 int。默认值是0。 |
NN_SNDPRIO | 为随后添加到套接字的端点设置出站优先级。此选项对向所有对等点发送消息的套接字类型没有影响。但是,如果套接字类型将每个消息发送到单个对等点(或有限的对等点集) ,具有高优先级的对等点优先于具有低优先级的对等点。选项的类型是 int。最高优先级是1最低优先级是16。默认值是8。 |
NN_RCVPRIO | 设置随后添加到套接字的端点的入站优先级。此选项对无法接收消息的套接字类型没有影响。在接收消息时,从优先级较高的对等点接收消息,然后再从优先级较低的对等点接收消息。选项的类型是 int。最高优先级是1最低优先级是16。默认值是8。 |
NN_IPV4ONLY | 如果设置为1,则只使用 ipv4地址。如果设置为0,则使用 ipv4和 ipv6地址。选项的类型是 int。默认值是1。 |
NN_SNDFD | 检索文件描述符,当消息可以发送到套接字时,该文件描述符是可读的。描述符应该只用于轮询,从不读取或写入。选项的类型与平台上的文件描述符的类型相同。也就是说,在 POSIX-complaint 平台上使用 int,在 Windows 上使用 socket。描述符变得无效,一旦套接字关闭,就不应该再使用它。此套接字选项不适用于单向 recv-only 套接字类型。 |
NN_RCVFD | 检索当可以从套接字接收消息时可读的文件描述符。描述符应该只用于轮询,从不读取或写入。选项的类型与平台上的文件描述符的类型相同。也就是说,在 POSIX-complaint 平台上使用 int,在 Windows 上使用 socket。描述符变得无效,一旦套接字关闭,就不应该再使用它。此套接字选项不适用于单向只发送套接字类型。 |
NN_SOCKET_NAME | 用于错误报告和统计的套接字名称。选项的类型是 string。默认值是“socket.n”,其中 n 是套接字整数。 |
NN_MAXTTL | 设置消息在被删除之前可以通过的最大“跃点”数。每次接收到消息时(例如通过 nn _ device (3)函数)计为单跳。这提供了一种防止无意中发生循环的保护形式。 |
5、nn_bind 添加套接字到本地节点
int nn_bind (int s, const char *addr); | ||
---|---|---|
参数 | int s //套接字 | ---- |
const char *addr //套接地址字符串 | 进程内通讯:inproc://test | |
tcp通讯:tcp://127.0.0.1:5555 | ||
返回值 | 如果函数成功,则返回正端点 id。如果函数失败,则返回-1,并将 errno 设置为下面定义的值之一。 | |
错误值 | EBADF | 所提供的socket无效 |
EMFILE | 达到了连接端点的最大数目 | |
EINVAL | 未知协议 | |
ENAMETOOLONG | 提供的地址字符串太长了 | |
ENOPROTOOPT | 请求的传输协议不被支持 | |
EADDRNOTAVAIL | 请求的端点不是本地的 | |
ENODEV | Address指定一个不存在的接口 | |
EADDRINUSE | 请求的本地端点已经在使用中 | |
ETERM | 数据库终止了 | |
用例 | s = nn_socket (AF_SP, NN_PUB); eid1 = nn_bind (s, "inproc://test"); eid2 = nn_bind (s, "tcp://127.0.0.1:5560"); | |
功能描述 | 将本地端点添加到套接字s中,然后其他应用程序可以使用该端点进行连接。 |
6、nn_connect 向套接字添加远程终结点
int nn_connect (int s, const char *addr); | ||
---|---|---|
参数 | int s //套接字 | ---- |
const char *addr //套接地址字符串 | 进程间通讯:ipc:///tmp/test.ipc | |
tcp通讯:tcp://127.0.0.1:5555 | ||
返回值 | 如果函数成功,则返回正端点 id。如果函数失败,返回负值,并将 errno 设置为下面定义的值之一,则可以使用端点 id 以后通过 nn_shutdown (3)函数从套接字中删除端点。 | |
错误值 | EBADF | 所提供的socket无效 |
EMFILE | 达到了连接端点的最大数目 | |
EINVAL | 未知协议 | |
ENAMETOOLONG | 提供的地址字符串太长了 | |
ENOPROTOOPT | 请求的传输协议不被支持 | |
ENODEV | Address指定一个不存在的接口 | |
ETERM | 数据库终止了 | |
用例 | s = nn_socket (AF_SP, NN_PUB); eid1 = nn_connect (s, "ipc:///tmp/test.ipc"); eid2 = nn_connect (s, "tcp://server001:5560"); | |
功能描述 | 将一个远程端点添加到套接字 s 中,然后库将尝试连接到指定的远程端点。 |
7、int nn_shutdown (int s, int how);从套接字中删除端点
int nn_shutdown (int s, int how); | ||
---|---|---|
参数 | int s //SP套接字 | ---- |
int how | nn_connect或者nn_bind返回的值 | |
错误值 | EBADF | 所提供的socket无效 |
EINVAL | how参数不是正在使用的端点 | |
EINTR | 行动被一个信号中断了。端点还没有完全关闭。操作可以通过再次调用 nn_shutdown()重新启动 | |
ETERM | 数据库终止了 | |
用例 | s = nn_socket (AF_SP, NN_PUB); eid = nn_bind (s, "inproc://test"); nn_shutdown (s, eid); | |
功能描述 | 从套接字s中移除一个端点。参数如何指定要移除的端点的 id,这个端点是在先前调用nn_bind()或nn_connect()时返回的,nn_shutdown()调用将立即返回,如果不是,库将尝试通过 NN_LINGER socket 选项在指定的时间内将任何未完成的出站的消息传递到端点。 |
8 、int nn_send (int s, const void *buf, size_t len, int flags);发送消息函数
int nn_send (int s, const void *buf, size_t len, int flags); | ||
---|---|---|
参数 | int s | SP套接字 |
const void *buf | 发送的消息 | |
size_t len | 发送消息长度 | |
int flags | NN_DONTWAIT //指定操作应以非阻塞模式执行。如果不能立即发送消息,则函数将失败,并再次设置 errno。 | |
返回值 | 如果函数成功,则返回消息中的字节数。否则,返回-1,并将 errno 设置为下面定义的值之一。 | |
错误值 | EFAULT | Buf 为 NULL 或者 len 为 nn_msg,消息指针(由 buf 指向)为 NULL |
EBADF | 所提供的socket无效 | |
ENOTSUP | 此套接字类型不支持此操作 | |
EFSM | 此时无法在此套接字上执行此操作,因为该套接字处于不适当的状态。在多个状态之间切换的套接字类型可能会出现此错误 | |
EAGAIN | 请求非阻塞模式,此时无法发送消息 | |
EINTR | 在信息发出之前,信号的传递打断了行动 | |
ETIMEDOUT | 每个套接字类型可能定义自己的特定超时。如果命中此类超时,将返回此错误。 | |
ETERM | 库终止了 | |
用例 | //直接使用数据: nbytes = nn_send (s, "ABC", 3, 0); assert (nbytes == 3); | |
//使用预先分配的消息缓冲区: void *msg = nn_allocmsg(3, 0); strncpy(msg, "ABC", 3); nbytes = nn_send (s, &msg, NN_MSG, 0); assert (nbytes == 3); | ||
功能描述 | 该函数将发送一条消息,其中包含由 buf 参数指向的来自 buffer 的数据,消息长度为 len 字节。 |
9、int nn_recv (int s, void *buf, size_t len, int flags);接收消息
int nn_send (int s, const void *buf, size_t len, int flags); | ||
---|---|---|
参数 | int s | SP套接字 |
const void *buf | 发送的消息 | |
size_t len | 发送消息长度 | |
int flags | NN_DONTWAIT //指定操作应以非阻塞模式执行。如果不能立即发送消息,则函数将失败,并再次设置 errno。 | |
返回值 | 如果函数成功,则返回消息中的字节数。否则,返回-1,并将 errno 设置为下面定义的值之一。 | |
错误值 | EBADF | 所提供的socket无效 |
ENOTSUP | 此套接字类型不支持此操作 | |
EFSM | 此时无法在此套接字上执行此操作,因为该套接字处于不适当的状态。在多个状态之间切换的套接字类型可能会出现此错误 | |
EAGAIN | 请求非阻塞模式,此时无法发送消息 | |
EINTR | 在信息发出之前,信号的传递打断了行动 | |
ETIMEDOUT | 每个套接字类型可能定义自己的特定超时。如果命中此类超时,将返回此错误。 | |
ETERM | 库终止了 | |
用例 | char buf [100]; nbytes = nn_recv (s, buf, sizeof (buf), 0); | |
void *buf = NULL; nbytes = nn_recv (s, &buf, NN_MSG, 0); if (nbytes < 0) { /* handle error */ ... }else { /* process message */ ... nn_freemsg (buf); } | ||
功能描述 | 从套接字 s 接收消息,并将其存储在 buf 参数引用的缓冲区中。任何超过 len 参数指定长度的字节都会被截断。 |
10、int nn_sendmsg (int s, const struct nn_msghdr *msghdr, int flags); nn_send的替代品
int nn_sendmsg (int s, const struct nn_msghdr *msghdr, int flags); | ||
---|---|---|
参数 | int s | SP套接字 |
const struct nn_msghdr *msghdr | 结构体内容见下代码片 | |
int flags | NN_DONTWAIT //指定操作应以非阻塞模式执行。如果不能立即发送消息,则函数将失败,并再次设置 errno。 | |
返回值 | 如果函数成功,则返回消息中的字节数。否则,返回-1,并将 errno 设置为下面定义的值之一。 | |
错误值 | EINVAL | 有多个分散缓冲区,但其中一个的长度设置为 NN_MSG,或者分散缓冲区大于size_t 的iov_len值之和,或者 msghdr 为 NULL.或者原来分配的消息没有被释放。 |
EMSGSIZE | msghdr->msg_iovlen 没有值,或者原来分配的消息没有被释放。 | |
EFAULT | 为预分配消息缓冲区提供的指针或分散缓冲区为空,或长度为0。 | |
EBADF | 所提供的socket无效 | |
ENOTSUP | 此套接字类型不支持此操作 | |
EFSM | 此时无法在此套接字上执行此操作,因为该套接字处于不适当的状态。在多个状态之间切换的套接字类型可能会出现此错误 | |
EAGAIN | 请求非阻塞模式,此时无法发送消息 | |
EINTR | 在信息发出之前,信号的传递打断了行动 | |
ETIMEDOUT | 每个套接字类型可能定义自己的特定超时。如果命中此类超时,将返回此错误。 | |
ETERM | 库终止了 | |
用例 | 见下面代码片段 | |
功能描述 | 将 msghdr 结构体指定的数据连同其他控制数据一起发送到套接字 s。 |
//结构体内容
struct nn_msghdr{
struct nn_iovec *msg_iov; //指向要发送的消息字符串缓冲区结构体地址
int msg_iovlen; //消息缓冲区个数
void *msg_control; //指向与正在发送的消息相关联的控制信息的缓冲区
size_t msg_controllen; //控制信息的长度
};
struct nn_iovec{
void *iov_base; //指向发送消息结构体/字符串地址
size_t iov_len; //发送消息字符串长度
};
//函数使用
//发送多个缓冲数据
struct nn_msghdr hdr;
struct nn_iovec iov [2];
iov [0].iov_base = "Hello";
iov [0].iov_len = 5;
iov [1].iov_base = "World";
iov [1].iov_len = 5;
memset (&hdr, 0, sizeof (hdr));
hdr.msg_iov = iov;
hdr.msg_iovlen = 2;
nn_sendmsg (s, &hdr, 0);
//发送单个缓冲数据
void *msg;
struct nn_msghdr hdr;
struct nn_iovec iov;
msg = nn_allocmsg(12, 0);
strcpy(msg, "Hello World");
iov.iov_base = &msg;
iov.iov_len = NN_MSG;
memset (&hdr, 0, sizeof (hdr));
hdr.msg_iov = &iov;
hdr.msg_iovlen = 1;
nn_sendmsg (s, &hdr, 0);
11、int nn_recvmsg (int s, struct nn_msghdr *msghdr, int flags);nn_recv 的替代品
int nn_recvmsg (int s, struct nn_msghdr *msghdr, int flags); | ||
---|---|---|
参数 | int s | SP套接字 |
const struct nn_msghdr *msghdr | 结构体内容见同上/td> | |
int flags | NN_DONTWAIT //指定操作应以非阻塞模式执行。如果不能立即发送消息,则函数将失败,并再次设置 errno。 | |
返回值 | 如果函数成功,则返回消息中的字节数。否则,返回-1,并将 errno 设置为下面定义的值之一。 | |
错误值 | EBADF | 所提供的socket无效 |
ENOTSUP | 此套接字类型不支持此操作 | |
EFSM | 此时无法在此套接字上执行此操作,因为该套接字处于不适当的状态。在多个状态之间切换的套接字类型可能会出现此错误 | |
EAGAIN | 请求非阻塞模式,此时无法发送消息 | |
EINTR | 在信息发出之前,信号的传递打断了行动 | |
ETIMEDOUT | 每个套接字类型可能定义自己的特定超时。如果命中此类超时,将返回此错误。 | |
ETERM | 库终止了 | |
用例 | 见下面代码片段 | |
功能描述 | 将 msghdr 结构体指定的数据连同其他控制数据一起发送到套接字 s。 |
struct nn_msghdr hdr;
struct nn_iovec iov [2];
char buf0 [4];
char buf1 [2];
iov [0].iov_base = buf0;
iov [0].iov_len = sizeof (buf0);
iov [1].iov_base = buf1;
iov [1].iov_len = sizeof (buf1);
memset (&hdr, 0, sizeof (hdr));
hdr.msg_iov = iov;
hdr.msg_iovlen = 2;
nn_recvmsg (s, &hdr, 0);