diff options
Diffstat (limited to 'man3p/mq_receive.3p')
| -rw-r--r-- | man3p/mq_receive.3p | 176 |
1 files changed, 176 insertions, 0 deletions
diff --git a/man3p/mq_receive.3p b/man3p/mq_receive.3p new file mode 100644 index 000000000..d60f88ae8 --- /dev/null +++ b/man3p/mq_receive.3p @@ -0,0 +1,176 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "MQ_RECEIVE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" mq_receive +.SH NAME +mq_receive, mq_timedreceive \- receive a message from a message queue +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +\fB#include <mqueue.h> +.br +.sp +ssize_t mq_receive(mqd_t\fP \fImqdes\fP\fB, char *\fP\fImsg_ptr\fP\fB, +size_t\fP \fImsg_len\fP\fB, +.br +\ \ \ \ \ \ unsigned *\fP\fImsg_prio\fP\fB); \fP +\fB +.br +.sp +\fP +.LP +\fB +.br +#include <mqueue.h> +.br +#include <time.h> +.br +ssize_t mq_timedreceive(mqd_t\fP \fImqdes\fP\fB, char *restrict\fP +\fImsg_ptr\fP\fB, +.br +\ \ \ \ \ \ size_t\fP \fImsg_len\fP\fB, unsigned *restrict\fP \fImsg_prio\fP\fB, +.br +\ \ \ \ \ \ const struct timespec *restrict\fP \fIabs_timeout\fP\fB); +\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fImq_receive\fP() function shall receive the oldest of the highest +priority message(s) from the message queue specified by +\fImqdes\fP. If the size of the buffer in bytes, specified by the +\fImsg_len\fP argument, is less than the \fImq_msgsize\fP +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 \fImsg_ptr\fP +argument. +.LP +If the value of \fImsg_len\fP is greater than {SSIZE_MAX}, the result +is implementation-defined. +.LP +If the argument \fImsg_prio\fP is not NULL, the priority of the selected +message shall be stored in the location referenced by +\fImsg_prio\fP. +.LP +If the specified message queue is empty and O_NONBLOCK is not set +in the message queue description associated with \fImqdes\fP, +\fImq_receive\fP() shall block until a message is enqueued on the +message queue or until \fImq_receive\fP() 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 +\fImqdes\fP, no message shall be removed from the queue, and +\fImq_receive\fP() shall return an error. +.LP +The \fImq_timedreceive\fP() function shall receive the oldest of the +highest priority messages from the message queue specified by +\fImqdes\fP as described for the \fImq_receive\fP() function. However, +if O_NONBLOCK was not specified when the message queue was +opened via the \fImq_open\fP() 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\fP(). +.LP +The timeout expires when the absolute time specified by \fIabs_timeout\fP +passes, as measured by the clock on which timeouts +are based (that is, when the value of that clock equals or exceeds +\fIabs_timeout\fP), or if the absolute time specified by +\fIabs_timeout\fP has already been passed at the time of the call. +.LP +If the Timers option is supported, the timeout shall be based on the +CLOCK_REALTIME clock; if the Timers option is not +supported, the timeout shall be based on the system clock as returned +by the \fItime\fP() +function. +.LP +The resolution of the timeout shall be the resolution of the clock +on which it is based. The \fItimespec\fP argument is defined in +the \fI<time.h>\fP header. +.LP +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 \fIabs_timeout\fP parameter need not be checked +if a message can be removed from the message queue +immediately. +.SH RETURN VALUE +.LP +Upon successful completion, the \fImq_receive\fP() \ and \fImq_timedreceive\fP() +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 \fIerrno\fP to +indicate the error. +.SH ERRORS +.LP +The \fImq_receive\fP() \ and \fImq_timedreceive\fP() +functions shall fail if: +.TP 7 +.B EAGAIN +O_NONBLOCK was set in the message description associated with \fImqdes\fP, +and the specified message queue is empty. +.TP 7 +.B EBADF +The \fImqdes\fP argument is not a valid message queue descriptor open +for reading. +.TP 7 +.B EMSGSIZE +The specified message buffer size, \fImsg_len\fP, is less than the +message size attribute of the message queue. +.TP 7 +.B EINTR +The \fImq_receive\fP() \ or \fImq_timedreceive\fP() +operation was interrupted by a signal. +.TP 7 +.B EINVAL +The process or thread would have blocked, and the \fIabs_timeout\fP +parameter specified a nanoseconds field value less than zero +or greater than or equal to 1000 million. +.TP 7 +.B 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. +.sp +.LP +The \fImq_receive\fP() \ and \fImq_timedreceive\fP() +functions may fail if: +.TP 7 +.B EBADMSG +The implementation has detected a data corruption problem with the +message. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fImq_open\fP() , \fImq_send\fP() , \fImq_timedsend\fP() , \fImsgctl\fP() +, \fImsgget\fP() , \fImsgrcv\fP() , \fImsgsnd\fP() , \fItime\fP() +, the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI<mqueue.h>\fP, +\fI<time.h>\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 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 . |