Added man pages for msgctl(3), msgget(3), msgrcv(3) and msgsnd(3).

Obtained from: NetBSD

1 files changed, 181 insertions, 0 deletions

diff --git a/lib/libc/gen/msgrcv.3 b/lib/libc/gen/msgrcv.3
new file mode 100644
index 0000000..db61fab
--- /dev/null
+++ b/lib/libc/gen/msgrcv.3
@@ -0,0 +1,181 @@
+.\"	$NetBSD: msgrcv.2,v 1.1 1995/10/16 23:49:20 jtc Exp $	
+.\"
+.\" Copyright (c) 1995 Frank van der Linden
+.\" 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, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"      This product includes software developed for the NetBSD Project
+.\"      by Frank van der Linden
+.\" 4. The name of the author may not be used to endorse or promote products
+.\"    derived from this software without specific prior written permission
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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.
+.\"/
+.Dd August 17, 1995
+.Dt MSGRCV 3
+.Os NetBSD
+.Sh NAME
+.Nm msgrcv
+.Nd receive a message from a message queue
+.Sh SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <sys/ipc.h>
+.Fd #include <sys/msg.h>
+.Ft int
+.Fn msgrcv "int msqid" "void *msgp" "size_t msgsz" "long msgtyp" "int msgflg"
+.Sh DESCRIPTION
+The 
+.Fn msgrcv
+function receives a message from the message queue specified in
+.Fa msqid ,
+and places it into the structure pointed to by
+.Fa msgp .
+This structure should consist of the following members:
+.Bd -literal
+    long mtype;    /* message type */
+    char mtext[1]; /* body of message */
+.Ed
+
+.Va mtype
+is an integer greater than 0 that can be used for selecting messages,
+.Va mtext
+is an array of bytes, with a size up to that of the system limit (MSGMAX).
+
+The value of
+.Fa msgtyp
+has one of the following meanings:
+.Bl -bullet
+.It
+.Fa msgtyp
+is greater than 0. The first message of type
+.Fa msgtyp
+will be received.
+.It
+.Fa msgtyp
+is equal to 0. The first message on the queue will be received.
+.It
+.Fa msgtyp
+is less than 0. The first message of the lowest message type that is
+less than or equal to the absolute value of
+.Fa msgtyp
+will be received.
+.El
+
+.Fa msgsz
+specifies the maximum length of the requested message. If the received
+message has a length greater than
+.Fa msgsz
+it will be silently truncated if the MSG_NOERROR flag is set in
+.Fa msgflg ,
+otherwise an error will be returned.
+
+If no matching message is present on the message queue specified by
+.Fa msqid ,
+the behavior of
+.Fn msgrcv
+depends on whether the IPC_NOWAIT flag is set in
+.Fa msgflg
+or not. If IPC_NOWAIT is set,
+.Fn msgrcv
+will immediately return a value of -1, and set
+.Va errno
+to EAGAIN. If IPC_NOWAIT is not set, the calling process will be blocked
+until:
+.Bl -bullet
+.It
+A message of the requested type becomes available on the message queue.
+.It
+The message queue is removed, in which case -1 will be returned, and
+.Va errno
+set to EINVAL.
+.It
+A signal is received and caught. -1 is returned, and
+.Va errno
+set to EINTR.
+.El
+
+If a message is successfully received, the data structure associated with
+.Fa msqid
+is updated as follows:
+.Bl -bullet
+.It
+.Va msg_cbytes
+is decremented by the size of the message.
+.It
+.Va msg_lrpid
+is set to the pid of the caller.
+.It
+.Va msg_lrtime
+is set to the current time.
+.It
+.Va msg_qnum
+is decremented by 1.
+.Sh RETURN VALUES
+Upon successful completion,
+.Fn msgrcv
+returns the number of bytes received into the
+.Va mtext
+field of the structure pointed to by
+.Fa msgp .
+Otherwise, -1 is returned, and
+.Va errno
+set to indicate the error.
+.Sh ERRORS
+.Fn msgrcv
+will fail if:
+.Bl -tag -width Er
+.It Bq Er EINVAL
+.Fa msqid
+is not a valid message queue identifier
+
+The message queue was removed while
+.Fn msgrcv
+was waiting for a message of the requested type to become available on it.
+
+.Fa msgsz
+is less than 0.
+.It Bq Er E2BIG
+A matching message was received, but its size was greater than
+.Fa msgsz
+and the MSG_NOERROR flag was not set in
+.Fa msgflg .
+.It Bq Er EACCESS
+The calling process does not have read access to the message queue.
+.It Bq Er EFAULT
+.Fa msgp
+points to an invalid address.
+.It Bq Er EINTR
+The system call was interrupted by the delivery of a signal.
+.It Bq Er EAGAIN
+There is no message of the requested type available on the message queue,
+and IPC_NOWAIT is set in
+.Fa msgflg .
+.Sh SEE ALSO
+.Xr msgsnd 3 ,
+.Xr msgctl 3 ,
+.Xr msgget 3
+.Sh BUGS
+NetBSD and FreeBSD do not define the EIDRM error value, which should be used in
+the case of a removed message queue, nor the ENOMSG value, which
+should be used when no suitable message is available and IPC_NOWAIT
+is set.
+.Sh HISTORY
+Message queues appeared in the first release of AT&T Unix System V.