New pages for POSIX message queues API

1 files changed, 148 insertions, 0 deletions

diff --git a/man3/mq_receive.3 b/man3/mq_receive.3
new file mode 100644
index 00000000..6df05aa4
--- /dev/null
+++ b/man3/mq_receive.3
@@ -0,0 +1,148 @@
+'\" t
+.\" Hey Emacs! This file is -*- nroff -*- source.
+.\"
+.\" Copyright (C) 2006 Michael Kerrisk <mtk-manpages@gmx.net>
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one.
+.\" 
+.\" Since the Linux kernel and libraries are constantly changing, this
+.\" manual page may be incorrect or out-of-date.  The author(s) assume no
+.\" responsibility for errors or omissions, or for damages resulting from
+.\" the use of the information contained herein.  
+.\" 
+.\" Formatted or processed versions of this manual, if unaccompanied by
+.\" the source, must acknowledge the copyright and authors of this work.
+.\"
+.TH MQ_RECEIVE 3 2006-02-25 "Linux 2.6.16" "Linux Programmer's Manual"
+.SH NAME
+mq_receive, mq_timedreceive \- receive a message from a message queue
+.SH SYNOPSIS
+.nf
+.B #include <mqueue.h>
+.sp
+.BI "mqd_t mq_receive(mqd_t " mqdes ", char *" msg_ptr ,
+.BI "               size_t " msg_len ", unsigned *" msg_prio );
+.sp
+.B #define _XOPEN_SOURCE 600
+.B #include <time.h>
+.B #include <mqueue.h>
+.sp
+.BI "mqd_t mq_timedreceive(mqd_t " mqdes ", char *" msg_ptr ,
+.BI "               size_t " msg_len ", unsigned *" msg_prio ,
+.BI "               const struct timespec *" abs_timeout );
+.fi
+.SH DESCRIPTION
+.BR mq_receive ()
+removes the oldest message with the highest priority from 
+the message queue referred to by the 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 the
+.I mq_msgsize
+attribute of the queue (see 
+.BR mq_getattr (3)).
+If
+.I prio
+is not NULL, then the buffer to which it points is used 
+to return the priority associated with the received message.
+
+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 .
+
+.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 a ceiling on the time for which 
+the call will block.
+This ceiling is an absolute timeout in seconds and nanoseconds
+since the Epoch (midnight on the morning of 1 January 1970),
+specified in the following structure:
+.sp
+.RS
+.nf
+struct timespec {
+    time_t tv_sec;        /* seconds */
+    long   tv_nsec;       /* nanoseconds */
+};
+
+.fi
+.RE
+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.
+.TP
+.B EMSGSIZE
+.IR msg_len 
+was less than the 
+.I mq_msgsize
+attribute of the message queue.
+.TP
+.B EINTR
+The call was interrupted by a signal handler.
+.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 ETIMEDOUT
+The call timed out before a message could be transferred.
+.SH CONFORMING TO
+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 mq_overview (7)