diff options
Diffstat (limited to 'man3/mq_receive.3')
| -rw-r--r-- | man3/mq_receive.3 | 164 |
1 files changed, 164 insertions, 0 deletions
diff --git a/man3/mq_receive.3 b/man3/mq_receive.3 new file mode 100644 index 0000000..40e9973 --- /dev/null +++ b/man3/mq_receive.3 @@ -0,0 +1,164 @@ +'\" t +.\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH mq_receive 3 2023-07-20 "Linux man-pages 6.05.01" +.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> +.PP +.BI "ssize_t mq_receive(mqd_t " mqdes ", char " msg_ptr [. msg_len ], +.BI " size_t " msg_len ", unsigned int *" msg_prio ); +.PP +.B #include <time.h> +.B #include <mqueue.h> +.PP +.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 +.PP +.ad l +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.PP +.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. +.PP +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 . +.PP +.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. +.PP +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 +.sp 1 +.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) |