| blob | 5c56888f99e4935cc01452b316665dc9908bce9e |
1 .\" $NetBSD: msgctl.2,v 1.15 2010/03/22 19:30:55 joerg 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 August 25, 1999
33 .Dt MSGCTL 2
34 .Os
35 .Sh NAME
36 .Nm msgctl
37 .Nd message control operations
38 .Sh LIBRARY
39 .Lb libc
40 .Sh SYNOPSIS
41 .In sys/msg.h
42 .Ft int
43 .Fn msgctl "int msqid" "int cmd" "struct msqid_ds *buf"
44 .Sh DESCRIPTION
45 The
46 .Fn msgctl
47 system call performs control operations on the message queue specified
48 by
49 .Fa msqid .
50 .Pp
51 Each message queue has a
52 .Sy msqid_ds
53 structure associated with it which contains the following members:
54 .Bd -literal
55 struct ipc_perm msg_perm; /* msg queue permission bits */
56 msgqnum_t msg_qnum; /* # of msgs in the queue */
57 msglen_t msg_qbytes; /* max # of bytes on the queue */
58 pid_t msg_lspid; /* pid of last msgsnd() */
59 pid_t msg_lrpid; /* pid of last msgrcv() */
60 time_t msg_stime; /* time of last msgsnd() */
61 time_t msg_rtime; /* time of last msgrcv() */
62 time_t msg_ctime; /* time of last msgctl() */
63 .Ed
64 .Pp
65 The
66 .Sy ipc_perm
67 structure used inside the
68 .Sy msgid_ds
69 structure is defined in
70 .In sys/ipc.h
71 and contains the following members:
72 .Bd -literal
73 uid_t cuid; /* creator user id */
74 gid_t cgid; /* creator group id */
75 uid_t uid; /* user id */
76 gid_t gid; /* group id */
77 mode_t mode; /* permission (lower 9 bits) */
78 .Ed
79 .Pp
80 The operation to be performed by
81 .Fn msgctl
82 is specified in
83 .Fa cmd
84 and is one of:
85 .Bl -tag -width IPC_RMIDX
86 .It Dv IPC_STAT
87 Gather information about the message queue and place it in the
88 structure pointed to by
89 .Fa buf .
90 .It Dv IPC_SET
91 Set the value of the
92 .Va msg_perm.uid ,
93 .Va msg_perm.gid ,
94 .Va msg_perm.mode
95 and
96 .Va msg_qbytes
97 fields in the structure associated with
98 .Fa msqid .
99 The values are taken from the corresponding fields in the structure
100 pointed to by
101 .Fa buf .
102 This operation can only be executed by the super-user, or a process that
103 has an effective user id equal to either
104 .Va msg_perm.cuid
105 or
106 .Va msg_perm.uid
107 in the data structure associated with the message queue.
108 The value of
109 .Va msg_qbytes
110 can only be increased by the super-user.
111 Values for
112 .Va msg_qbytes
113 that exceed the system limit
114 .Pf ( Dv MSGMNB
115 from
116 .In sys/msg.h )
117 are silently truncated to that limit.
118 .It Dv IPC_RMID
119 Remove the message queue specified by
120 .Fa msqid
121 and destroy the data associated with it.
122 Only the super-user or a process with an effective uid equal to the
123 .Va msg_perm.cuid
124 or
125 .Va msg_perm.uid
126 values in the data structure associated with the queue can do this.
127 .El
128 .Pp
129 The permission to read from or write to a message queue (see
130 .Xr msgsnd 2
131 and
132 .Xr msgrcv 2 )
133 is determined by the
134 .Va msg_perm.mode
135 field in the same way as is done with files (see
136 .Xr chmod 2 ) ,
137 but the effective uid can match either the
138 .Va msg_perm.cuid
139 field or the
140 .Va msg_perm.uid
141 field, and the
142 effective gid can match either
143 .Va msg_perm.cgid
144 or
145 .Va msg_perm.gid .
146 .Sh RETURN VALUES
147 Upon successful completion, a value of 0 is returned.
148 Otherwise, \-1 is returned and the global variable
149 .Va errno
150 is set to indicate the error.
151 .Sh ERRORS
152 .Fn msgctl
153 will fail if:
154 .Bl -tag -width Er
155 .It Bq Er EPERM
156 .Fa cmd
157 is equal to
158 .Dv IPC_SET
159 or
160 .Dv IPC_RMID
161 and the caller is not the super-user, nor does
162 the effective uid match either the
163 .Va msg_perm.uid
164 or
165 .Va msg_perm.cuid
166 fields of the data structure associated with the message queue.
167 .Pp
168 An attempt was made to increase the value of
169 .Va msg_qbytes
170 through
171 .Dv IPC_SET ,
172 but the caller is not the super-user.
173 .It Bq Er EACCES
174 .Fa cmd
175 is
176 .Dv IPC_STAT
177 and the caller has no read permission for this message queue.
178 .It Bq Er EINVAL
179 .Fa msqid
180 is not a valid message queue identifier.
181 .Pp
182 .Fa cmd
183 is not a valid command.
184 .It Bq Er EFAULT
185 .Fa buf
186 specifies an invalid address.
187 .El
188 .Sh SEE ALSO
189 .Xr msgget 2 ,
190 .Xr msgrcv 2 ,
191 .Xr msgsnd 2
192 .Sh STANDARDS
193 The
194 .Nm
195 system call conforms to
196 .St -xsh5 .
197 .Sh HISTORY
198 Message queues appeared in the first release of
199 .At V .