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