Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 163 insertions, 0 deletions

diff --git a/man/man3/mq_receive.3 b/man/man3/mq_receive.3
new file mode 100644
index 0000000..368177f
--- /dev/null
+++ b/man/man3/mq_receive.3
@@ -0,0 +1,163 @@
+'\" t
+.\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH mq_receive 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+mq_receive, mq_timedreceive \- receive a message from a message queue
+.SH LIBRARY
+Real-time library
+.RI ( librt ", " \-lrt )
+.SH SYNOPSIS
+.nf
+.B #include <mqueue.h>
+.P
+.BI "ssize_t mq_receive(mqd_t " mqdes ", char " msg_ptr [. msg_len ],
+.BI "                   size_t " msg_len ", unsigned int *" msg_prio );
+.P
+.B #include <time.h>
+.B #include <mqueue.h>
+.P
+.BI "ssize_t mq_timedreceive(mqd_t " mqdes ", \
+char *restrict " msg_ptr [. msg_len ],
+.BI "                   size_t " msg_len ", unsigned int *restrict " msg_prio ,
+.BI "                   const struct timespec *restrict " abs_timeout );
+.fi
+.P
+.ad l
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR mq_timedreceive ():
+.nf
+    _POSIX_C_SOURCE >= 200112L
+.fi
+.SH DESCRIPTION
+.BR mq_receive ()
+removes the oldest message with the highest priority from
+the message queue referred to by the message queue descriptor
+.IR mqdes ,
+and places it in the buffer pointed to by
+.IR msg_ptr .
+The
+.I msg_len
+argument specifies the size of the buffer pointed to by
+.IR msg_ptr ;
+this must be greater than or equal to the
+.I mq_msgsize
+attribute of the queue (see
+.BR mq_getattr (3)).
+If
+.I msg_prio
+is not NULL, then the buffer to which it points is used
+to return the priority associated with the received message.
+.P
+If the queue is empty, then, by default,
+.BR mq_receive ()
+blocks until a message becomes available,
+or the call is interrupted by a signal handler.
+If the
+.B O_NONBLOCK
+flag is enabled for the message queue description,
+then the call instead fails immediately with the error
+.BR EAGAIN .
+.P
+.BR mq_timedreceive ()
+behaves just like
+.BR mq_receive (),
+except that if the queue is empty and the
+.B O_NONBLOCK
+flag is not enabled for the message queue description, then
+.I abs_timeout
+points to a structure which specifies how long the call will block.
+This value is an absolute timeout in seconds and nanoseconds
+since the Epoch, 1970-01-01 00:00:00 +0000 (UTC),
+specified in a
+.BR timespec (3)
+structure.
+.P
+If no message is available,
+and the timeout has already expired by the time of the call,
+.BR mq_timedreceive ()
+returns immediately.
+.SH RETURN VALUE
+On success,
+.BR mq_receive ()
+and
+.BR mq_timedreceive ()
+return the number of bytes in the received message;
+on error, \-1 is returned, with
+.I errno
+set to indicate the error.
+.SH ERRORS
+.TP
+.B EAGAIN
+The queue was empty, and the
+.B O_NONBLOCK
+flag was set for the message queue description referred to by
+.IR mqdes .
+.TP
+.B EBADF
+The descriptor specified in
+.I mqdes
+was invalid or not opened for reading.
+.TP
+.B EINTR
+The call was interrupted by a signal handler; see
+.BR signal (7).
+.TP
+.B EINVAL
+The call would have blocked, and
+.I abs_timeout
+was invalid, either because
+.I tv_sec
+was less than zero, or because
+.I tv_nsec
+was less than zero or greater than 1000 million.
+.TP
+.B EMSGSIZE
+.I msg_len
+was less than the
+.I mq_msgsize
+attribute of the message queue.
+.TP
+.B ETIMEDOUT
+The call timed out before a message could be transferred.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR mq_receive (),
+.BR mq_timedreceive ()
+T}	Thread safety	MT-Safe
+.TE
+.SH VERSIONS
+On Linux,
+.BR mq_timedreceive ()
+is a system call, and
+.BR mq_receive ()
+is a library function layered on top of that system call.
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001.
+.SH SEE ALSO
+.BR mq_close (3),
+.BR mq_getattr (3),
+.BR mq_notify (3),
+.BR mq_open (3),
+.BR mq_send (3),
+.BR mq_unlink (3),
+.BR timespec (3),
+.BR mq_overview (7),
+.BR time (7)