diff options
Diffstat (limited to 'lib/libc/sys/mq_receive.2')
| -rw-r--r-- | lib/libc/sys/mq_receive.2 | 217 |
1 files changed, 0 insertions, 217 deletions
diff --git a/lib/libc/sys/mq_receive.2 b/lib/libc/sys/mq_receive.2 deleted file mode 100644 index 730636b..0000000 --- a/lib/libc/sys/mq_receive.2 +++ /dev/null @@ -1,217 +0,0 @@ -.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org> -.\" All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice(s), this list of conditions and the following disclaimer as -.\" the first lines of this file unmodified other than the possible -.\" addition of one or more copyright notices. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice(s), this list of conditions and the following disclaimer in -.\" the documentation and/or other materials provided with the -.\" distribution. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY -.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR -.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE -.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR -.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF -.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR -.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, -.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE -.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, -.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -.\" -.\" Portions of this text are reprinted and reproduced in electronic form -.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- -.\" Portable Operating System Interface (POSIX), The Open Group Base -.\" Specifications Issue 6, Copyright (C) 2001-2004 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. -.\" -.\" $FreeBSD$ -.\" -.Dd November 29, 2005 -.Dt MQ_RECEIVE 2 -.Os -.Sh NAME -.Nm mq_receive , mq_timedreceive -.Nd "receive a message from message queue (REALTIME)" -.Sh LIBRARY -.Lb librt -.Sh SYNOPSIS -.In mqueue.h -.Ft ssize_t -.Fo mq_receive -.Fa "mqd_t mqdes" -.Fa "char *msg_ptr" -.Fa "size_t msg_len" -.Fa "unsigned *msg_prio" -.Fc -.Ft ssize_t -.Fo mq_timedreceive -.Fa "mqd_t mqdes" -.Fa "char *msg_ptr" -.Fa "size_t msg_len" -.Fa "unsigned *msg_prio" -.Fa "const struct timespec *abs_timeout" -.Fc -.Sh DESCRIPTION -The -.Fn mq_receive -system call receives oldest of the highest priority message(s) from the -message queue specified by -.Fa mqdes . -If the size of the buffer in bytes, specified by the -.Fa msg_len -argument, is less than the -.Va mq_msgsize -attribute of the message queue, the system call will fail and return an -error. -Otherwise, the selected message will be removed from the queue -and copied to the buffer pointed to by the -.Fa msg_ptr -argument. -.Pp -If the argument -.Fa msg_prio -is not -.Dv NULL , -the priority of the selected message will be stored in the -location referenced by -.Fa msg_prio . -If the specified message queue is empty and -.Dv O_NONBLOCK -is not set in the message queue description associated with -.Fa mqdes , -.Fn mq_receive -will block until a message is enqueued on the message queue or until -.Fn mq_receive -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 will be selected to receive the message. -Otherwise, it is unspecified which waiting thread receives the message. -If the specified message queue is empty and -.Dv O_NONBLOCK -is set in the message queue description associated with -.Fa mqdes , -no message -will be removed from the queue, and -.Fn mq_receive -will return an error. -.Pp -The -.Fn mq_timedreceive -system call will receive the oldest of the highest priority messages from the -message queue specified by -.Fa mqdes -as described for the -.Fn mq_receive -system call. -However, if -.Dv O_NONBLOCK -was not specified when the message queue was opened via the -.Fn mq_open -system call, and no message exists on the queue to satisfy the receive, the wait -for such a message will be terminated when the specified timeout expires. -If -.Dv O_NONBLOCK -is set, this system call is equivalent to -.Fn mq_receive . -.Pp -The timeout expires when the absolute time specified by -.Fa abs_timeout -passes, as measured by the clock on which timeouts are based (that is, when -the value of that clock equals or exceeds -.Fa abs_timeout ) , -or if the absolute time specified by -.Fa abs_timeout -has already been passed at the time of the call. -.Pp -The timeout is based on the -.Dv CLOCK_REALTIME -clock. -.Sh RETURN VALUES -Upon successful completion, the -.Fn mq_receive -and -.Fn mq_timedreceive -system calls return the length of the selected message in bytes and the -message is removed from the queue. -Otherwise, no message is removed -from the queue, the system call returns a value of \-1, -and the global variable -.Va errno -is set to indicate the error. -.Sh ERRORS -The -.Fn mq_receive -and -.Fn mq_timedreceive -system calls -will fail if: -.Bl -tag -width Er -.It Bq Er EAGAIN -.Dv O_NONBLOCK -flag is set in the message queue description associated with -.Fa mqdes , -and the specified message queue is empty. -.It Bq Er EBADF -The -.Fa mqdes -argument is not a valid message queue descriptor open for reading. -.It Bq Er EMSGSIZE -The specified message buffer size, -.Fa msg_len , -is less than the message size attribute of the message queue. -.It Bq Er EINTR -The -.Fn mq_receive -or -.Fn mq_timedreceive -operation was interrupted by a signal. -.It Bq Er EINVAL -The process or thread would have blocked, and the -.Fa abs_timeout -parameter specified a nanoseconds field value less than zero or greater -than or equal to 1000 million. -.It Bq Er ETIMEDOUT -The -.Dv O_NONBLOCK -flag was not set when the message queue was opened, but no message arrived -on the queue before the specified timeout expired. -.El -.Sh SEE ALSO -.Xr mq_open 2 , -.Xr mq_send 2 , -.Xr mq_timedsend 2 -.Sh STANDARDS -The -.Fn mq_receive -and -.Fn mq_timedreceive -system calls conform to -.St -p1003.1-2004 . -.Sh HISTORY -Support for -.Tn POSIX -message queues first appeared in -.Fx 7.0 . -.Sh COPYRIGHT -Portions of this text are reprinted and reproduced in electronic form -from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- -Portable Operating System Interface (POSIX), The Open Group Base -Specifications Issue 6, Copyright (C) 2001-2004 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. |
