mq_receive(3) - Linux 手册页

名称

mq_receive, mq_timedreceive - 从消息队列接收消息

概要

#include <mqueue.h>

ssize_t mq_receive(mqd_t mqdes, char *msg_ptr,
                   size_t msg_len, unsigned *msg_prio);

#include <time.h>
#include <mqueue.h>

ssize_t mq_timedreceive(mqd_t mqdes, char *msg_ptr,
                   size_t msg_len, unsigned *msg_prio,
                   const struct timespec *abs_timeout);

链接 -lrt。

glibc 的功能测试宏要求（参见 feature_test_macros(7)）

mq_timedreceive():: _XOPEN_SOURCE >= 600 || _POSIX_C_SOURCE >= 200112L

描述

mq_receive() 从由文件描述符 mqdes 指示的消息队列中移除最旧且优先级最高的消息，并将其放置在 msg_ptr 指向的缓冲区中。msg_len 参数指定 msg_ptr 指向的缓冲区的大小；这必须大于队列的 mq_msgsize 属性（参见 mq_getattr(3)）。如果 msg_prio 不为 NULL，则指向它的缓冲区用于返回接收到的消息关联的优先级。

如果队列为空，则默认情况下，mq_receive() 会阻塞，直到有消息可用，或者调用被信号处理程序中断。如果消息队列描述符的 O_NONBLOCK 标志已启用，则调用会立即失败，并返回错误 EAGAIN。

mq_timedreceive() 的行为与 mq_receive() 相同，除了当队列为空且消息队列描述符的 O_NONBLOCK 标志未启用时，abs_timeout 指向一个结构体，该结构体指定调用阻塞的时间上限。该上限是自 Epoch（1970-01-01 00:00:00 +0000 (UTC)）以来以秒和纳秒为单位的绝对超时时间，并在以下结构体中指定

struct timespec {
    time_t tv_sec;        /* seconds */
    long   tv_nsec;       /* nanoseconds */
};

如果没有消息可用，并且在调用时超时已经过期，mq_timedreceive() 会立即返回。

返回值

成功时，mq_receive() 和 mq_timedreceive() 返回接收到的消息的字节数；出错时，返回 -1，并设置 errno 以指示错误。

错误

EAGAIN
队列为空，并且为由 mqdes 指示的消息队列描述符设置了 O_NONBLOCK 标志。
EBADF
mqdes 中指定的描述符无效。
EINTR
调用被信号处理程序中断；请参阅 signal(7)。
EINVAL
调用会阻塞，并且 abs_timeout 无效，因为 tv_sec 小于零，或者因为 tv_nsec 小于零或大于 10 亿。
EMSGSIZE: msg_len 小于消息队列的 mq_msgsize 属性。
ETIMEDOUT: 调用超时，无法传输消息。

符合

POSIX.1-2001。

说明

在 Linux 上，mq_timedreceive() 是一个系统调用，而 mq_receive() 是构建在该系统调用之上的库函数。

参见

mq_close(3), mq_getattr(3), mq_notify(3), mq_open(3), mq_send(3), mq_unlink(3), mq_overview(7), time(7)