mqueue

mqueue 提供进程间消息队列通信功能，支持消息的创建、打开、发送、接收、属性查询与设置，以及定时收发和异步通知机制。

头文件清单

#include "open_source/musl/include/mqueue.h"

接口清单

接口名称	功能简述
mq_close	关闭消息队列描述符
mq_getattr	获取消息队列属性
mq_notify	注册或移除消息队列异步通知
mq_open	打开或创建消息队列
mq_receive	从消息队列接收消息
mq_send	向消息队列发送消息
mq_setattr	设置消息队列属性
mq_timedreceive	定时接收消息
mq_timedsend	定时发送消息
mq_unlink	移除消息队列

Functions

mq_close

int mq_close(mqd_t mqdes)

头文件清单

#include "open_source/musl/include/mqueue.h"

功能说明

• 关闭已打开的消息队列描述符
• 释放该描述符对应的私有资源
• 当消息队列已被标记为删除且无其他打开的描述符时，删除消息队列

前置条件

• 调用时序约束：当前接口必须在 mq_open() 成功返回后调用
• 依赖关系：传入的 mqd_t 描述符必须为 mq_open() 返回的有效消息队列描述符

入参

名称	参数类型	详细说明	约束取值范围
mqdes	mqd_t	消息队列描述符	有效的 mq_open() 返回值

返回值

• 返回类型：int

返回值	文字含义	触发场景
0	关闭成功	描述符合法且关闭操作成功
-1	关闭失败	描述符无效、描述符状态异常或内存释放失败，errno 设置为 EBADF/EFAULT

mq_getattr

int mq_getattr(mqd_t mqdes, struct mq_attr *mqstat)

头文件清单

#include "open_source/musl/include/mqueue.h"

功能说明

• 获取消息队列的属性信息
• 返回消息队列的最大消息数、消息大小、当前消息数量及标志位
• 属性信息通过 mq_attr 结构体输出

前置条件

• 调用时序约束：当前接口必须在 mq_open() 成功返回后调用
• 依赖关系：传入的 mqd_t 描述符必须为 mq_open() 返回的有效消息队列描述符

入参

名称	参数类型	详细说明	约束取值范围
mqdes	mqd_t	消息队列描述符	有效的 mq_open() 返回值

出参

名称	数据类型	输出说明
mqstat	struct mq_attr *	输出消息队列属性，包含 mq_flags、mq_maxmsg、mq_msgsize、mq_curmsgs

返回值

• 返回类型：int

返回值	文字含义	触发场景
0	获取成功	描述符合法且获取操作成功
-1	获取失败	描述符无效或 mqstat 为 NULL，errno 设置为 EBADF/EINVAL

mq_notify

int mq_notify(mqd_t mqdes, const struct sigevent *sevp)

头文件清单

#include "open_source/musl/include/mqueue.h"

功能说明

• 注册异步通知，当消息队列从空变为非空时向进程发送信号
• 若 sevp 非 NULL，注册通知；若 sevp 为 NULL，移除已注册的通知
• 同一消息队列同一时刻仅允许一个进程注册通知

前置条件

• 调用时序约束：当前接口必须在 mq_open() 成功返回后调用
• 依赖关系：传入的 mqd_t 描述符必须为 mq_open() 返回的有效消息队列描述符，且描述符应具有读权限

入参

名称	参数类型	详细说明	约束取值范围
mqdes	mqd_t	消息队列描述符	有效的 mq_open() 返回值
sevp	const struct sigevent *	通知配置结构体指针，NULL 表示移除通知	非 NULL 时指向有效的 sigevent 结构体 / NULL

返回值

• 返回类型：int

返回值	文字含义	触发场景
0	注册/移除成功	操作成功完成
-1	注册/移除失败	描述符无效或已有其他进程注册通知，errno 设置为 EBADF/EBUSY

mq_open

mqd_t mq_open(const char *name, int oflag, ...)

头文件清单

#include "open_source/musl/include/mqueue.h"

功能说明

• 打开或创建一个消息队列
• 支持以 O_CREAT 标志创建新的消息队列，以 O_EXCL 标志排他性创建
• 打开已存在的消息队列时，分配并返回一个新的私有描述符

前置条件

• 调用时序约束：消息队列名称必须合法（非空、长度不超过 PATH_MAX-1）
• 依赖关系：创建消息队列时需要系统有足够的队列资源和内存

入参

名称	参数类型	详细说明	约束取值范围
name	const char *	消息队列名称	非 NULL，长度大于 0 且不超过 PATH_MAX-1
oflag	int	打开标志	O_RDONLY / O_WRONLY / O_RDWR / O_CREAT / O_EXCL / O_NONBLOCK
...	可变参数	创建消息队列时的可变参数，包含 mode 和 struct mq_attr *	当 oflag 包含 O_CREAT 时需提供

返回值

• 返回类型：mqd_t

返回值	文字含义	触发场景
有效 mqd_t	打开/创建成功	消息队列打开或创建成功
(mqd_t)-1	打开/创建失败	名称无效、队列已存在（O_EXCL）、队列不存在（无 O_CREAT）、资源不足，errno 设置为 EINVAL/EEXIST/ENOENT/ENOSPC

mq_receive

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

头文件清单

#include "open_source/musl/include/mqueue.h"

功能说明

• 从消息队列中接收一条消息
• 接收的消息存入指定的缓冲区，返回接收到的消息长度
• 若消息队列为空且未设置非阻塞标志，则阻塞等待直到有消息可读

前置条件

• 调用时序约束：当前接口必须在 mq_open() 成功返回后调用
• 依赖关系：传入的 mqd_t 描述符必须为 mq_open() 返回的有效消息队列描述符，且描述符应具有读权限（O_RDONLY 或 O_RDWR）
• 上下文限制：msg_ptr 缓冲区大小不小于消息队列的单条消息大小

入参

名称	参数类型	详细说明	约束取值范围
mqdes	mqd_t	消息队列描述符	有效的 mq_open() 返回值
msg_len	size_t	缓冲区大小	大于 0，且不小于消息队列的单条消息大小

出参

名称	数据类型	输出说明
msg_ptr	char *	输出接收到的消息内容，由调用方分配内存、函数填充
msg_prio	unsigned *	输出消息优先级，可为 NULL 表示不获取优先级

返回值

• 返回类型：ssize_t

返回值	文字含义	触发场景
>= 0	接收成功，返回接收到的消息长度	成功从消息队列中读取消息
-1	接收失败	描述符无效、缓冲区过小、无读权限或超时，errno 设置为 EBADF/EMSGSIZE/EINVAL/ETIMEDOUT/EAGAIN

mq_send

int mq_send(mqd_t mqdes, const char *msg_ptr, size_t msg_len, unsigned msg_prio)

头文件清单

#include "open_source/musl/include/mqueue.h"

功能说明

• 向消息队列发送一条消息
• 发送指定长度的消息到消息队列
• 若消息队列已满且未设置非阻塞标志，则阻塞等待直到有空间可写入

前置条件

• 调用时序约束：当前接口必须在 mq_open() 成功返回后调用
• 依赖关系：传入的 mqd_t 描述符必须为 mq_open() 返回的有效消息队列描述符，且描述符应具有写权限（O_WRONLY 或 O_RDWR）
• 上下文限制：消息长度不能超过消息队列的单条消息大小

入参

名称	参数类型	详细说明	约束取值范围
mqdes	mqd_t	消息队列描述符	有效的 mq_open() 返回值
msg_ptr	const char *	待发送消息的缓冲区	非 NULL
msg_len	size_t	消息长度	大于 0，且不超过消息队列的单条消息大小
msg_prio	unsigned	消息优先级	0 ~ MQ_PRIO_MAX-1

返回值

• 返回类型：int

返回值	文字含义	触发场景
0	发送成功	消息成功写入消息队列
-1	发送失败	描述符无效、消息过长、无写权限、优先级超限或超时，errno 设置为 EBADF/EMSGSIZE/EINVAL/ETIMEDOUT/EAGAIN

mq_setattr

int mq_setattr(mqd_t mqdes, const struct mq_attr *__restrict newattr, struct mq_attr *__restrict oldattr)

头文件清单

#include "open_source/musl/include/mqueue.h"

功能说明

• 设置消息队列的属性
• 仅支持设置 O_NONBLOCK 标志位，其他属性字段不可通过此接口修改
• 可选地在设置前获取当前属性值

前置条件

• 调用时序约束：当前接口必须在 mq_open() 成功返回后调用
• 依赖关系：传入的 mqd_t 描述符必须为 mq_open() 返回的有效消息队列描述符

入参

名称	参数类型	详细说明	约束取值范围
mqdes	mqd_t	消息队列描述符	有效的 mq_open() 返回值
newattr	const struct mq_attr *__restrict	待设置的属性结构体指针	非 NULL，仅 mq_flags 中的 O_NONBLOCK 位有效

出参

名称	数据类型	输出说明
oldattr	struct mq_attr *__restrict	输出修改前的消息队列属性（当 oldattr 非 NULL 时）

返回值

• 返回类型：int

返回值	文字含义	触发场景
0	设置成功	描述符合法且设置操作成功
-1	设置失败	描述符无效或 newattr 为 NULL，errno 设置为 EBADF/EINVAL

mq_timedreceive

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

头文件清单

#include "open_source/musl/include/mqueue.h"

功能说明

• 从消息队列中定时接收一条消息
• 当消息队列为空时，在指定的绝对超时时间内等待消息到达
• 超时时间到达后若仍无消息可读，则返回失败

前置条件

• 调用时序约束：当前接口必须在 mq_open() 成功返回后调用
• 依赖关系：传入的 mqd_t 描述符必须为 mq_open() 返回的有效消息队列描述符，且描述符应具有读权限（O_RDONLY 或 O_RDWR）
• 上下文限制：msg_ptr 缓冲区大小不小于消息队列的单条消息大小；abs_timeout 指向的时间值必须合法

入参

名称	参数类型	详细说明	约束取值范围
mqdes	mqd_t	消息队列描述符	有效的 mq_open() 返回值
msg_len	size_t	缓冲区大小	大于 0，且不小于消息队列的单条消息大小
abs_timeout	const struct timespec *__restrict	绝对超时时间	非 NULL 时必须为合法的 timespec 值

出参

名称	数据类型	输出说明
msg_ptr	char *__restrict	输出接收到的消息内容，由调用方分配内存、函数填充
msg_prio	unsigned *__restrict	输出消息优先级，可为 NULL 表示不获取优先级

返回值

• 返回类型：ssize_t

返回值	文字含义	触发场景
>= 0	接收成功，返回接收到的消息长度	成功从消息队列中读取消息
-1	接收失败	描述符无效、缓冲区过小、无读权限、超时时间非法或超时，errno 设置为 EBADF/EMSGSIZE/EINVAL/ETIMEDOUT/EAGAIN

mq_timedsend

int mq_timedsend(mqd_t mqdes, const char *msg_ptr, size_t msg_len, unsigned msg_prio, const struct timespec *abs_timeout)

头文件清单

#include "open_source/musl/include/mqueue.h"

功能说明

• 向消息队列定时发送一条消息
• 当消息队列已满时，在指定的绝对超时时间内等待空间可用
• 超时时间到达后若仍无空间可写入，则返回失败

前置条件

• 调用时序约束：当前接口必须在 mq_open() 成功返回后调用
• 依赖关系：传入的 mqd_t 描述符必须为 mq_open() 返回的有效消息队列描述符，且描述符应具有写权限（O_WRONLY 或 O_RDWR）
• 上下文限制：消息长度不能超过消息队列的单条消息大小；abs_timeout 指向的时间值必须合法

入参

名称	参数类型	详细说明	约束取值范围
mqdes	mqd_t	消息队列描述符	有效的 mq_open() 返回值
msg_ptr	const char *	待发送消息的缓冲区	非 NULL
msg_len	size_t	消息长度	大于 0，且不超过消息队列的单条消息大小
msg_prio	unsigned	消息优先级	0 ~ MQ_PRIO_MAX-1
abs_timeout	const struct timespec *	绝对超时时间	非 NULL 时必须为合法的 timespec 值

返回值

• 返回类型：int

返回值	文字含义	触发场景
0	发送成功	消息成功写入消息队列
-1	发送失败	描述符无效、消息过长、无写权限、优先级超限、超时时间非法或超时，errno 设置为 EBADF/EMSGSIZE/EINVAL/ETIMEDOUT/EAGAIN

mq_unlink

int mq_unlink(const char *name)

头文件清单

#include "open_source/musl/include/mqueue.h"

功能说明

• 移除指定名称的消息队列
• 当消息队列仍有打开的描述符时，标记为待删除，待所有描述符关闭后实际删除
• 当消息队列无打开的描述符时，立即删除消息队列

前置条件

• 调用时序约束：消息队列名称必须合法（非空、长度不超过 PATH_MAX-1）
• 依赖关系：消息队列必须已通过 mq_open() 创建

入参

名称	参数类型	详细说明	约束取值范围
name	const char *	消息队列名称	非 NULL，长度大于 0 且不超过 PATH_MAX-1

返回值

• 返回类型：int

返回值	文字含义	触发场景
0	移除成功	消息队列成功删除或标记为待删除
-1	移除失败	名称无效、消息队列不存在或仍有描述符打开，errno 设置为 EINVAL/ENOENT/EINTR/EAGAIN

Type definitions

mqd_t

typedef size_t mqd_t;

使用说明

用于消息队列描述符的类型定义，作为 mq_close、mq_getattr、mq_notify、mq_open、mq_receive、mq_send、mq_setattr、mq_timedreceive、mq_timedsend 接口的参数或返回值类型。

Structures

mq_attr

#ifdef __LITEOS__
struct mq_attr {
    long mq_flags;    /* Message queue flags */
    long mq_maxmsg;   /* Maximum number of messages */
    long mq_msgsize;  /* Maximum size of a message */
    long mq_curmsgs;  /* Number of messages in the current message queue */
};
#endif

成员说明

成员名称	数据类型	描述
mq_flags	long	消息队列标志位
mq_maxmsg	long	最大消息数
mq_msgsize	long	单条消息最大大小
mq_curmsgs	long	当前消息队列中的消息数量