1msgctl(2)                     System Calls Manual                    msgctl(2)
2
3
4

NAME

6       msgctl - System V message control operations
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

STANDARDS

208       POSIX.1-2008.
209

HISTORY

211       POSIX.1-2001, SVr4.
212
213       Various fields in the struct msqid_ds were typed as short  under  Linux
214       2.2 and have become long under Linux 2.4.  To take advantage of this, a
215       recompilation under glibc-2.1.91 or later should suffice.  (The  kernel
216       distinguishes old and new calls by an IPC_64 flag in cmd.)
217

NOTES

219       The IPC_INFO, MSG_STAT, and MSG_INFO operations are used by the ipcs(1)
220       program to provide information on allocated resources.  In  the  future
221       these may modified or moved to a /proc filesystem interface.
222

SEE ALSO

224       msgget(2),   msgrcv(2),   msgsnd(2),  capabilities(7),  mq_overview(7),
225       sysvipc(7)
226
227
228
229Linux man-pages 6.05              2023-03-30                         msgctl(2)
Impressum