1.\"	$OpenBSD: msgsnd.2,v 1.11 2003/06/01 20:25:23 jmc 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 August 17, 1995
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 from the message queue specified in
49.Fa msqid .
50.Fa msgp
51points to a structure containing the message.
52This structure should consist of the following members:
53.Bd -literal
54    long mtype;    /* message type */
55    char 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 bytes, with a size up to that of the system limit
63.Pq Dv MSGMAX .
64.Pp
65If the number of bytes already on the message queue plus
66.Fa msgsz
67is bigger than the maximum number of bytes on the message queue
68.Po Va msg_qbytes ,
69 see
70.Xr msgctl 2
71.Pc ,
72or the number of messages on all queues system-wide is already equal to
73the system limit,
74.Fa msgflg
75determines the action of
76.Fn msgsnd .
77If
78.Fa msgflg
79has
80.Dv IPC_NOWAIT
81mask set in it, the call will return immediately.
82If
83.Fa msgflg
84does not have
85.Dv IPC_NOWAIT
86set in it, the call will block until:
87.Bl -bullet
88.It
89The condition which caused the call to block does no longer exist.
90The message will be sent.
91.It
92The message queue is removed, in which case \-1 will be returned, and
93.Va errno
94is set to
95.Er EINVAL .
96.It
97The caller catches a signal.
98The call returns with
99.Va errno
100set to
101.Er EINTR .
102.El
103.Pp
104After a successful call, the data structure associated with the message
105queue is updated in the following way:
106.Bl -bullet
107.It
108.Va msg_cbytes
109is incremented by the size of the message.
110.It
111.Va msg_qnum
112is incremented by 1.
113.It
114.Va msg_lspid
115is set to the pid of the calling process.
116.It
117.Va msg_stime
118is set to the current time.
119.El
120.Sh RETURN VALUES
121Upon successful completion, 0 is returned.
122Otherwise, \-1 is returned and
123.Va errno
124is set to indicate the error.
125.Sh ERRORS
126.Fn msgsnd
127will fail if:
128.Bl -tag -width Er
129.It Bq Er EINVAL
130.Fa msqid
131is not a valid message queue identifier.
132.Pp
133The message queue was removed while
134.Fn msgsnd
135was waiting for a resource to become available in order to deliver the
136message.
137.Pp
138.Fa msgsz
139is less than 0, or greater than
140.Va msg_qbytes .
141.It Bq Er EACCES
142The calling process does not have write access to the message queue.
143.It Bq Er EAGAIN
144There was no space for this message either on the queue, or in the whole
145system, and
146.Dv IPC_NOWAIT
147was set in
148.Fa msgflg .
149.It Bq Er EFAULT
150.Fa msgp
151points to an invalid address.
152.It Bq Er EINTR
153The system call was interrupted by the delivery of a signal.
154.El
155.Sh SEE ALSO
156.Xr msgctl 2 ,
157.Xr msgget 2 ,
158.Xr msgrcv 2
159.Sh HISTORY
160Message queues appeared in the first release of AT&T Unix System V.
161.Sh BUGS
162.Ox
163does not define the
164.Er EIDRM
165error value, which should be used
166in the case of a removed message queue.
167