1.\" $OpenBSD: msgsnd.2,v 1.16 2007/09/03 14:37:52 millert Exp $ 2.\" $NetBSD: msgsnd.2,v 1.2 1997/03/27 08:20:36 mikel Exp $ 3.\" 4.\" Copyright (c) 1995 Frank van der Linden 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. All advertising materials mentioning features or use of this software 16.\" must display the following acknowledgement: 17.\" This product includes software developed for the NetBSD Project 18.\" by Frank van der Linden 19.\" 4. The name of the author may not be used to endorse or promote products 20.\" derived from this software without specific prior written permission 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 23.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 24.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 25.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 26.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 27.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 28.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 29.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 30.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 31.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 32.\"/ 33.Dd $Mdocdate: September 3 2007 $ 34.Dt MSGSND 2 35.Os 36.Sh NAME 37.Nm msgsnd 38.Nd send a message to a message queue 39.Sh SYNOPSIS 40.Fd #include <sys/types.h> 41.Fd #include <sys/ipc.h> 42.Fd #include <sys/msg.h> 43.Ft int 44.Fn msgsnd "int msqid" "const void *msgp" "size_t msgsz" "int msgflg" 45.Sh DESCRIPTION 46The 47.Fn msgsnd 48function sends a message to the message queue specified by 49.Fa msqid . 50.Fa msgp 51points to a structure containing the message. 52This structure should consist of the following members: 53.Bd -literal -offset indent 54long mtype; /* message type */ 55char mtext[1]; /* body of message */ 56.Ed 57.Pp 58.Va mtype 59is an integer greater than 0 that can be used for selecting messages (see 60.Xr msgrcv 2 ) ; 61.Va mtext 62is an array of 63.Fa msgsz 64bytes, with a size between 0 and that of the system limit 65.Pq Dv MSGMAX . 66.Pp 67If the number of bytes already on the message queue plus 68.Fa msgsz 69is bigger than the maximum number of bytes on the message queue 70.Po Va msg_qbytes , 71 see 72.Xr msgctl 2 73.Pc , 74or the number of messages on all queues system-wide is already equal to 75the system limit, 76.Fa msgflg 77determines the action of 78.Fn msgsnd . 79If 80.Fa msgflg 81has 82.Dv IPC_NOWAIT 83mask set in it, the call will return immediately. 84If 85.Fa msgflg 86does not have 87.Dv IPC_NOWAIT 88set in it, the call will block until: 89.Bl -bullet 90.It 91The condition which caused the call to block does no longer exist. 92The message will be sent. 93.It 94The message queue is removed, in which case \-1 will be returned, and 95.Va errno 96is set to 97.Er EINVAL . 98.It 99The caller catches a signal. 100The call returns with 101.Va errno 102set to 103.Er EINTR . 104.El 105.Pp 106After a successful call, the data structure associated with the message 107queue is updated in the following way: 108.Bl -bullet 109.It 110.Va msg_cbytes 111is incremented by the size of the message. 112.It 113.Va msg_qnum 114is incremented by 1. 115.It 116.Va msg_lspid 117is set to the pid of the calling process. 118.It 119.Va msg_stime 120is set to the current time. 121.El 122.Sh RETURN VALUES 123Upon successful completion, 0 is returned. 124Otherwise, \-1 is returned and 125.Va errno 126is set to indicate the error. 127.Sh ERRORS 128.Fn msgsnd 129will fail if: 130.Bl -tag -width Er 131.It Bq Er EINVAL 132.Fa msqid 133is not a valid message queue identifier. 134.Pp 135.Fa msgsz 136is greater than 137.Va msg_qbytes . 138.It Bq Er EACCES 139The calling process does not have write access to the message queue. 140.It Bq Er EAGAIN 141There was no space for this message either on the queue, or in the whole 142system, and 143.Dv IPC_NOWAIT 144was set in 145.Fa msgflg . 146.It Bq Er EFAULT 147.Fa msgp 148points to an invalid address. 149.It Bq Er EINTR 150The system call was interrupted by the delivery of a signal. 151.It Bq Er EIDRM 152The message queue was removed while 153.Fn msgsnd 154was waiting for a resource to become available in order to deliver the 155message. 156.El 157.Sh SEE ALSO 158.Xr msgctl 2 , 159.Xr msgget 2 , 160.Xr msgrcv 2 161.Sh HISTORY 162Message queues appeared in the first release of AT&T Unix System V. 163