Merge from vendor branch BZIP:
[dragonfly.git] / lib / libc / gen / msgsnd.3
CommitLineData
984263bc
MD
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.\" $FreeBSD: src/lib/libc/gen/msgsnd.3,v 1.9.2.5 2001/12/14 18:33:51 ru Exp $
0b84df5c 33.\" $DragonFly: src/lib/libc/gen/msgsnd.3,v 1.4 2006/02/17 19:35:06 swildner Exp $
984263bc
MD
34.\"
35.Dd November 24, 1997
36.Dt MSGSND 3
37.Os
38.Sh NAME
39.Nm msgsnd
40.Nd send a message to a message queue
41.Sh LIBRARY
42.Lb libc
43.Sh SYNOPSIS
44.In sys/types.h
45.In sys/ipc.h
46.In sys/msg.h
47.Ft int
48.Fn msgsnd "int msqid" "void *msgp" "size_t msgsz" "int msgflg"
49.Sh DESCRIPTION
50The
51.Fn msgsnd
52function sends a message to the message queue specified in
53.Fa msqid .
54.Fa msgp
55points to a structure containing the message.
56This structure should
57consist of the following members:
58.Bd -literal
59 long mtype; /* message type */
60 char mtext[1]; /* body of message */
61.Ed
62.Pp
63.Va mtype
64is an integer greater than 0 that can be used for selecting messages (see
65.Xr msgrcv 3 ) ,
66.Va mtext
67is an array of bytes, with a size up to that of the system limit
68.Pf ( Dv MSGMAX ) .
69.Pp
70If the number of bytes already on the message queue plus
71.Fa msgsz
72is bigger than the maximum number of bytes on the message queue
73.Pf ( Va msg_qbytes ,
74see
75.Xr msgctl 3 ) ,
76or the number of messages on all queues system-wide is already equal to
77the system limit,
78.Fa msgflg
79determines the action of
80.Fn msgsnd .
81If
82.Fa msgflg
83has
84.Dv IPC_NOWAIT
85mask set in it, the call will return immediately.
86If
87.Fa msgflg
88does not have
89.Dv IPC_NOWAIT
90set in it, the call will block until:
91.Bl -bullet
92.It
93The condition which caused the call to block does no longer exist.
94The message will be sent.
95.It
96The message queue is removed, in which case -1 will be returned, and
97.Va errno
98is set to
99.Er EINVAL .
100.It
101The caller catches a signal.
102The call returns with
103.Va errno
104set to
105.Er EINTR .
106.El
107.Pp
108After a successful call, the data structure associated with the message
109queue is updated in the following way:
110.Bl -bullet
111.It
112.Va msg_cbytes
113is incremented by the size of the message.
114.It
115.Va msg_qnum
116is incremented by 1.
117.It
118.Va msg_lspid
119is set to the pid of the calling process.
120.It
121.Va msg_stime
122is set to the current time.
123.El
124.Sh RETURN VALUES
125.Rv -std msgsnd
126.Sh ERRORS
127.Fn msgsnd
128will fail if:
129.Bl -tag -width Er
130.It Bq Er EINVAL
131.Fa msqid
132is not a valid message queue identifier
133.Pp
134The message queue was removed while
135.Fn msgsnd
136was waiting for a resource to become available in order to deliver the
137message.
138.Pp
139.Fa msgsz
140is less than 0, or greater than
141.Va msg_qbytes .
142.Pp
143.Fa mtype
144is not greater than 0.
145.It Bq Er EACCES
146The calling process does not have write access to the message queue.
147.It Bq Er EAGAIN
148There was no space for this message either on the queue, or in the whole
149system, and
150.Dv IPC_NOWAIT
151was set in
152.Fa msgflg .
153.It Bq Er EFAULT
154.Fa msgp
155points to an invalid address.
156.It Bq Er EINTR
157The system call was interrupted by the delivery of a signal.
158.El
0b84df5c
SW
159.Sh HISTORY
160Message queues appeared in the first release of AT&T Unix System V.
984263bc 161.Sh BUGS
9bb2a92d
HP
162.Nx Ns ,
163.Dx Ns ,
984263bc
MD
164and
165.Fx
166do not define the
167.Er EIDRM
168error value, which should be used
169in the case of a removed message queue.