[RFC PATCH 1/3] mqueue: uapi: add struct mq_peek_attr and F_MQ_PEEK

[Shaurya Rane]

Add the user-visible interface for non-destructive POSIX message queue
inspection via fcntl(2).

POSIX message queues have no way to inspect queued messages without
consuming them: mq_receive() always dequeues the message it returns.
This makes it impossible for checkpoint/restore tools such as CRIU to
save and replay message queue contents without destroying the queue
state in the process.

struct mq_peek_attr describes the request: the caller specifies an
index into the queue in receive order (0 = next message that
mq_receive() would return, i.e. highest priority, FIFO within same
priority) and a buffer to receive the payload.  On return, msg_prio is
filled with the message priority and the return value is the number of
bytes copied.

F_MQ_PEEK = F_LINUX_SPECIFIC_BASE + 17 is the new fcntl command that
accepts a pointer to struct mq_peek_attr.

Link: https://github.com/checkpoint-restore/criu/issues/2285
Signed-off-by: Shaurya Rane <ssrane_b23@xxxxxxxxxxxxx>
---
 include/uapi/linux/fcntl.h  |  6 ++++++
 include/uapi/linux/mqueue.h | 21 +++++++++++++++++++++
 2 files changed, 27 insertions(+)

diff --git a/include/uapi/linux/fcntl.h b/include/uapi/linux/fcntl.h
index aadfbf6e0cb3..ea34f87de0fb 100644
--- a/include/uapi/linux/fcntl.h
+++ b/include/uapi/linux/fcntl.h
@@ -84,6 +84,12 @@
 #define F_GETDELEG		(F_LINUX_SPECIFIC_BASE + 15)
 #define F_SETDELEG		(F_LINUX_SPECIFIC_BASE + 16)
 
+/*
+ * Peek at a POSIX message queue message by index without consuming it.
+ * Argument is a pointer to struct mq_peek_attr (see <linux/mqueue.h>).
+ */
+#define F_MQ_PEEK		(F_LINUX_SPECIFIC_BASE + 17)
+
 /* Argument structure for F_GETDELEG and F_SETDELEG */
 struct delegation {
 	__u32	d_flags;	/* Must be 0 */
diff --git a/include/uapi/linux/mqueue.h b/include/uapi/linux/mqueue.h
index b516b66840ad..7133b84c70d1 100644
--- a/include/uapi/linux/mqueue.h
+++ b/include/uapi/linux/mqueue.h
@@ -53,4 +53,25 @@ struct mq_attr {
 
 #define NOTIFY_COOKIE_LEN	32
 
+/*
+ * Argument structure for fcntl(F_MQ_PEEK).
+ *
+ * Peek at a POSIX message queue message by index without removing it.
+ * @offset:   Index in receive order (0 = highest priority, next to dequeue).
+ *            FIFO ordering is preserved within the same priority level.
+ * @msg_prio: Output: priority of the message at @offset.
+ * @buf_len:  Size of the caller-provided buffer at @buf.
+ * @buf:      Output: message payload is written here; truncated to @buf_len
+ *            bytes if the message is larger.
+ *
+ * Returns the number of bytes copied on success, -ENOMSG if @offset is
+ * >= mq_curmsgs, or a negative error code on failure.
+ */
+struct mq_peek_attr {
+	__s32		 offset;
+	__u32		 msg_prio;
+	__kernel_size_t  buf_len;
+	char __user	*buf;
+};
+
 #endif
-- 
2.34.1