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

NAME

6       msgctl - System V message control operations
7

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

CONFORMING TO

205       POSIX.1-2001, POSIX.1-2008, SVr4.
206

NOTES

208       The IPC_INFO, MSG_STAT, and MSG_INFO operations are used by the ipcs(1)
209       program  to  provide information on allocated resources.  In the future
210       these may modified or moved to a /proc filesystem interface.
211
212       Various fields in the struct msqid_ds were typed as short  under  Linux
213       2.2 and have become long under Linux 2.4.  To take advantage of this, a
214       recompilation under glibc-2.1.91 or later should suffice.  (The  kernel
215       distinguishes old and new calls by an IPC_64 flag in cmd.)
216

SEE ALSO

218       msgget(2),   msgrcv(2),   msgsnd(2),  capabilities(7),  mq_overview(7),
219       sysvipc(7)
220

COLOPHON

222       This page is part of release 5.13 of the Linux  man-pages  project.   A
223       description  of  the project, information about reporting bugs, and the
224       latest    version    of    this    page,    can     be     found     at
225       https://www.kernel.org/doc/man-pages/.
226
227
228
229Linux                             2021-03-22                         MSGCTL(2)
Impressum