1MSGCTL(2)                  Linux Programmer's Manual                 MSGCTL(2)
2
3
4

NAME

6       msgctl - System V message control operations
7

SYNOPSIS

9       #include <sys/types.h>
10       #include <sys/ipc.h>
11       #include <sys/msg.h>
12
13       int msgctl(int msqid, int cmd, struct msqid_ds *buf);
14

DESCRIPTION

16       msgctl()  performs  the  control operation specified by cmd on the Sys‐
17       tem V message queue with identifier msqid.
18
19       The msqid_ds data structure is defined in <sys/msg.h> as follows:
20
21           struct msqid_ds {
22               struct ipc_perm msg_perm;   /* Ownership and permissions */
23               time_t          msg_stime;  /* Time of last msgsnd(2) */
24               time_t          msg_rtime;  /* Time of last msgrcv(2) */
25               time_t          msg_ctime;  /* Time of creation or last
26                                              modification by msgctl() */
27               unsigned long   msg_cbytes; /* # of bytes in queue */
28               msgqnum_t       msg_qnum;   /* # number of messages in queue */
29               msglen_t        msg_qbytes; /* Maximum # of bytes in queue */
30               pid_t           msg_lspid;  /* PID of last msgsnd(2) */
31               pid_t           msg_lrpid;  /* PID of last msgrcv(2) */
32           };
33
34       The fields of the msgid_ds structure are as follows:
35
36       msg_perm   This is an ipc_perm structure (see below) that specifies the
37                  access permissions on the message queue.
38
39       msg_stime  Time of the last msgsnd(2) system call.
40
41       msg_rtime  Time of the last msgrcv(2) system call.
42
43       msg_ctime  Time  of  creation of queue or time of last msgctl() IPC_SET
44                  operation.
45
46       msg_cbytes Number of bytes in all messages  currently  on  the  message
47                  queue.   This  is  a nonstandard Linux extension that is not
48                  specified in POSIX.
49
50       msg_qnum   Number of messages currently on the message queue.
51
52       msg_qbytes Maximum number of bytes of message text allowed on the  mes‐
53                  sage queue.
54
55       msg_lspid  ID  of  the process that performed the last msgsnd(2) system
56                  call.
57
58       msg_lrpid  ID of the process that performed the last  msgrcv(2)  system
59                  call.
60
61       The  ipc_perm  structure  is defined as follows (the highlighted fields
62       are settable using IPC_SET):
63
64           struct ipc_perm {
65               key_t          __key;       /* Key supplied to msgget(2) */
66               uid_t          uid;         /* Effective UID of owner */
67               gid_t          gid;         /* Effective GID of owner */
68               uid_t          cuid;        /* Effective UID of creator */
69               gid_t          cgid;        /* Effective GID of creator */
70               unsigned short mode;        /* Permissions */
71               unsigned short __seq;       /* Sequence number */
72           };
73
74       The least significant 9 bits of the mode field of the  ipc_perm  struc‐
75       ture  define the access permissions for the message queue.  The permis‐
76       sion bits are as follows:
77
78       0400   Read by user
79       0200   Write by user
80       0040   Read by group
81       0020   Write by group
82       0004   Read by others
83       0002   Write by others
84
85       Bits 0100, 0010, and 0001 (the execute bits) are unused by the system.
86
87       Valid values for cmd are:
88
89       IPC_STAT
90              Copy information from the kernel data structure associated  with
91              msqid into the msqid_ds structure pointed to by buf.  The caller
92              must have read permission on the message queue.
93
94       IPC_SET
95              Write the values of  some  members  of  the  msqid_ds  structure
96              pointed  to  by buf to the kernel data structure associated with
97              this message queue, updating also its msg_ctime member.
98
99              The following members of the structure are updated:  msg_qbytes,
100              msg_perm.uid,  msg_perm.gid,  and  (the least significant 9 bits
101              of) msg_perm.mode.
102
103              The effective UID of the calling process must  match  the  owner
104              (msg_perm.uid)  or creator (msg_perm.cuid) of the message queue,
105              or the caller must be privileged.  Appropriate privilege (Linux:
106              the  CAP_SYS_RESOURCE  capability)  is  required  to  raise  the
107              msg_qbytes value beyond the system parameter MSGMNB.
108
109       IPC_RMID
110              Immediately remove the  message  queue,  awakening  all  waiting
111              reader  and writer processes (with an error return and errno set
112              to EIDRM).  The calling process must have appropriate privileges
113              or  its  effective user ID must be either that of the creator or
114              owner of the message queue.  The third argument to  msgctl()  is
115              ignored in this case.
116
117       IPC_INFO (Linux-specific)
118              Return  information  about  system-wide message queue limits and
119              parameters in the structure pointed to by buf.   This  structure
120              is  of  type  msginfo  (thus,  a  cast  is required), defined in
121              <sys/msg.h> if the _GNU_SOURCE feature test macro is defined:
122
123                  struct msginfo {
124                      int msgpool; /* Size in kibibytes of buffer pool
125                                      used to hold message data;
126                                      unused within kernel */
127                      int msgmap;  /* Maximum number of entries in message
128                                      map; unused within kernel */
129                      int msgmax;  /* Maximum number of bytes that can be
130                                      written in a single message */
131                      int msgmnb;  /* Maximum number of bytes that can be
132                                      written to queue; used to initialize
133                                      msg_qbytes during queue creation
134                                      (msgget(2)) */
135                      int msgmni;  /* Maximum number of message queues */
136                      int msgssz;  /* Message segment size;
137                                      unused within kernel */
138                      int msgtql;  /* Maximum number of messages on all queues
139                                      in system; unused within kernel */
140                      unsigned short msgseg;
141                                   /* Maximum number of segments;
142                                      unused within kernel */
143                  };
144
145              The msgmni, msgmax, and msgmnb settings can be changed via /proc
146              files of the same name; see proc(5) for details.
147
148       MSG_INFO (Linux-specific)
149              Return  a  msginfo  structure containing the same information as
150              for IPC_INFO, except that the following fields are returned with
151              information  about  system resources consumed by message queues:
152              the msgpool field returns the number of message queues that cur‐
153              rently  exist  on the system; the msgmap field returns the total
154              number of messages in all queues on the system; and  the  msgtql
155              field  returns  the total number of bytes in all messages in all
156              queues on the system.
157
158       MSG_STAT (Linux-specific)
159              Return a msqid_ds structure as for IPC_STAT.  However, the msqid
160              argument  is  not  a queue identifier, but instead an index into
161              the kernel's internal array that maintains information about all
162              message queues on the system.
163
164       MSG_STAT_ANY (Linux-specific, since Linux 4.17)
165              Return   a   msqid_ds   structure  as  for  MSG_STAT.   However,
166              msg_perm.mode is not checked for read access for  msqid  meaning
167              that  any  user  can employ this operation (just as any user may
168              read /proc/sysvipc/msg to obtain the same information).
169

RETURN VALUE

171       On success, IPC_STAT, IPC_SET, and IPC_RMID  return  0.   A  successful
172       IPC_INFO  or  MSG_INFO  operation returns the index of the highest used
173       entry in the kernel's internal array recording  information  about  all
174       message  queues.   (This information can be used with repeated MSG_STAT
175       or MSG_STAT_ANY operations to obtain information about  all  queues  on
176       the  system.)   A successful MSG_STAT or MSG_STAT_ANY operation returns
177       the identifier of the queue whose index was given in msqid.
178
179       On error, -1 is returned with errno indicating the error.
180

ERRORS

182       On failure, errno is set to one of the following:
183
184       EACCES The argument cmd is equal to IPC_STAT or MSG_STAT, but the call‐
185              ing  process  does not have read permission on the message queue
186              msqid, and does not have the  CAP_IPC_OWNER  capability  in  the
187              user namespace that governs its IPC namespace.
188
189       EFAULT The  argument cmd has the value IPC_SET or IPC_STAT, but the ad‐
190              dress pointed to by buf isn't accessible.
191
192       EIDRM  The message queue was removed.
193
194       EINVAL Invalid value for cmd or msqid.  Or: for a  MSG_STAT  operation,
195              the  index  value  specified  in msqid referred to an array slot
196              that is currently unused.
197
198       EPERM  The argument cmd has the value IPC_SET or IPC_RMID, but the  ef‐
199              fective  user  ID  of the calling process is not the creator (as
200              found in msg_perm.cuid) or the owner (as found in  msg_perm.uid)
201              of  the  message queue, and the caller is not privileged (Linux:
202              does not have the CAP_SYS_ADMIN capability).
203
204       EPERM  An attempt (IPC_SET) was made to increase msg_qbytes beyond  the
205              system  parameter  MSGMNB,  but  the  caller  is  not privileged
206              (Linux: does not have the CAP_SYS_RESOURCE capability).
207

CONFORMING TO

209       POSIX.1-2001, POSIX.1-2008, SVr4.
210

NOTES

212       The inclusion of <sys/types.h> and <sys/ipc.h> isn't required on  Linux
213       or by any version of POSIX.  However, some old implementations required
214       the inclusion of these header files, and the SVID also documented their
215       inclusion.   Applications  intended  to be portable to such old systems
216       may need to include these header files.
217
218       The IPC_INFO, MSG_STAT, and MSG_INFO operations are used by the ipcs(1)
219       program  to  provide information on allocated resources.  In the future
220       these may modified or moved to a /proc filesystem interface.
221
222       Various fields in the struct msqid_ds were typed as short  under  Linux
223       2.2 and have become long under Linux 2.4.  To take advantage of this, a
224       recompilation under glibc-2.1.91 or later should suffice.  (The  kernel
225       distinguishes old and new calls by an IPC_64 flag in cmd.)
226

SEE ALSO

228       msgget(2),   msgrcv(2),   msgsnd(2),  capabilities(7),  mq_overview(7),
229       sysvipc(7)
230

COLOPHON

232       This page is part of release 5.10 of the Linux  man-pages  project.   A
233       description  of  the project, information about reporting bugs, and the
234       latest    version    of    this    page,    can     be     found     at
235       https://www.kernel.org/doc/man-pages/.
236
237
238
239Linux                             2020-11-01                         MSGCTL(2)
Impressum