diff options
author | mpp <mpp@FreeBSD.org> | 1996-02-12 07:03:24 +0000 |
---|---|---|
committer | mpp <mpp@FreeBSD.org> | 1996-02-12 07:03:24 +0000 |
commit | cb589475e89a2cc44f1d7a42a4a5f31e18e4019b (patch) | |
tree | c92d049bf7cb7ec30c80409daaaf318e151dfe99 /lib/libc/gen/msgrcv.3 | |
parent | 177e9b7f674ddc9669079404a10d1a12ab985b7f (diff) | |
download | FreeBSD-src-cb589475e89a2cc44f1d7a42a4a5f31e18e4019b.zip FreeBSD-src-cb589475e89a2cc44f1d7a42a4a5f31e18e4019b.tar.gz |
Added man pages for msgctl(3), msgget(3), msgrcv(3) and msgsnd(3).
Obtained from: NetBSD
Diffstat (limited to 'lib/libc/gen/msgrcv.3')
-rw-r--r-- | lib/libc/gen/msgrcv.3 | 181 |
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. |