diff options
Diffstat (limited to 'upstream/archlinux/man3p/mq_receive.3p')
| -rw-r--r-- | upstream/archlinux/man3p/mq_receive.3p | 203 |
1 files changed, 203 insertions, 0 deletions
diff --git a/upstream/archlinux/man3p/mq_receive.3p b/upstream/archlinux/man3p/mq_receive.3p new file mode 100644 index 00000000..426f7233 --- /dev/null +++ b/upstream/archlinux/man3p/mq_receive.3p @@ -0,0 +1,203 @@ +'\" et +.TH MQ_RECEIVE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +mq_receive, +mq_timedreceive +\(em receive a message from a message queue (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include <mqueue.h> +.P +ssize_t mq_receive(mqd_t \fImqdes\fP, char *\fImsg_ptr\fP, size_t \fImsg_len\fP, + unsigned *\fImsg_prio\fP); +.P +#include <mqueue.h> +#include <time.h> +.P +ssize_t mq_timedreceive(mqd_t \fImqdes\fP, char *restrict \fImsg_ptr\fP, + size_t \fImsg_len\fP, unsigned *restrict \fImsg_prio\fP, + const struct timespec *restrict \fIabstime\fP); +.fi +.SH DESCRIPTION +The +\fImq_receive\fR() +function shall receive the oldest of the highest priority +message(s) from the message queue specified by +.IR mqdes . +If the size of the buffer in bytes, specified by the +.IR msg_len +argument, is less than the +.IR mq_msgsize +attribute of the message queue, the function shall fail and return an +error. Otherwise, the selected message shall be removed from the queue +and copied to the buffer pointed to by the +.IR msg_ptr +argument. +.P +If the value of +.IR msg_len +is greater than +{SSIZE_MAX}, +the result is implementation-defined. +.P +If the argument +.IR msg_prio +is not NULL, the priority of the selected message shall be stored in the +location referenced by +.IR msg_prio . +.P +If the specified message queue is empty and O_NONBLOCK +is not set in the message queue description associated with +.IR mqdes , +\fImq_receive\fR() +shall block until a message is enqueued on the message queue or until +\fImq_receive\fR() +is interrupted by a signal. If more than one thread is waiting to +receive a message when a message arrives at an empty queue and the +Priority Scheduling option is supported, then the thread of highest +priority that has been waiting the longest shall be selected to receive +the message. Otherwise, it is unspecified which waiting thread receives +the message. If the specified message queue is empty and O_NONBLOCK is +set in the message queue description associated with +.IR mqdes , +no message shall be removed from the queue, and +\fImq_receive\fR() +shall return an error. +.P +The +\fImq_timedreceive\fR() +function shall receive the oldest of the highest priority messages +from the message queue specified by +.IR mqdes +as described for the +\fImq_receive\fR() +function. However, if O_NONBLOCK was not specified when the message +queue was opened via the +\fImq_open\fR() +function, and no message exists on the queue to satisfy the receive, +the wait for such a message shall be terminated when the specified +timeout expires. If O_NONBLOCK is set, this function is equivalent to +\fImq_receive\fR(). +.P +The timeout expires when the absolute time specified by +.IR abstime +passes, as measured by the clock on which timeouts are based (that is, +when the value of that clock equals or exceeds +.IR abstime ), +or if the absolute time specified by +.IR abstime +has already been passed at the time of the call. +.P +The timeout shall be based on the CLOCK_REALTIME clock. +The resolution of the timeout shall be the resolution of the clock on +which it is based. The +.IR timespec +argument is defined in the +.IR <time.h> +header. +.P +Under no circumstance shall the operation fail with a timeout if a +message can be removed from the message queue immediately. The validity +of the +.IR abstime +parameter need not be checked if a message can be removed from the +message queue immediately. +.SH "RETURN VALUE" +Upon successful completion, the +\fImq_receive\fR() +and +\fImq_timedreceive\fR() +functions shall return the length of the selected message in bytes and +the message shall be removed from the queue. Otherwise, no message +shall be removed from the queue, the functions shall return a value of +\-1, and set +.IR errno +to indicate the error. +.SH ERRORS +These functions shall fail if: +.TP +.BR EAGAIN +O_NONBLOCK was set in the message description associated with +.IR mqdes , +and the specified message queue is empty. +.TP +.BR EBADF +The +.IR mqdes +argument is not a valid message queue descriptor open for reading. +.TP +.BR EMSGSIZE +The specified message buffer size, +.IR msg_len , +is less than the message size attribute of the message queue. +.TP +.BR EINTR +The +\fImq_receive\fR() +or +\fImq_timedreceive\fR() +operation was interrupted by a signal. +.TP +.BR EINVAL +The process or thread would have blocked, and the +.IR abstime +parameter specified a nanoseconds field value less than zero or greater +than or equal to 1\|000 million. +.TP +.BR ETIMEDOUT +The O_NONBLOCK flag was not set when the message queue was opened, but +no message arrived on the queue before the specified timeout expired. +.P +These functions may fail if: +.TP +.BR EBADMSG +The implementation has detected a data corruption problem with the +message. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImq_open\fR\^(\|)", +.IR "\fImq_send\fR\^(\|)", +.IR "\fImsgctl\fR\^(\|)", +.IR "\fImsgget\fR\^(\|)", +.IR "\fImsgrcv\fR\^(\|)", +.IR "\fImsgsnd\fR\^(\|)", +.IR "\fItime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB<mqueue.h>\fP", +.IR "\fB<time.h>\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |