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

NAME

6       msgctl - 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 message
17       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() */
24               time_t         msg_rtime;    /* Time of last msgrcv() */
25               time_t         msg_ctime;    /* Time of last change */
26               unsigned long  __msg_cbytes; /* Current number of bytes in
27                                               queue (non-standard) */
28               msgqnum_t      msg_qnum;     /* Current number of messages
29                                               in queue */
30               msglen_t       msg_qbytes;   /* Maximum number of bytes
31                                               allowed in queue */
32               pid_t          msg_lspid;    /* PID of last msgsnd() */
33               pid_t          msg_lrpid;    /* PID of last msgrcv() */
34           };
35
36       The ipc_perm structure is defined in <sys/ipc.h> as follows (the  high‐
37       lighted fields are settable using IPC_SET):
38
39           struct ipc_perm {
40               key_t key;            /* Key supplied to msgget() */
41               uid_t uid;            /* Effective UID of owner */
42               gid_t gid;            /* Effective GID of owner */
43               uid_t cuid;           /* Effective UID of creator */
44               gid_t cgid;           /* Effective GID of creator */
45               unsigned short mode;  /* Permissions */
46               unsigned short seq;   /* Sequence number */
47           };
48
49       Valid values for cmd are:
50
51       IPC_STAT
52              Copy  information from the kernel data structure associated with
53              msqid into the msqid_ds structure pointed to by buf.  The caller
54              must have read permission on the message queue.
55
56       IPC_SET
57              Write  the  values  of  some  members  of the msqid_ds structure
58              pointed to by buf to the kernel data structure  associated  with
59              this  message  queue,  updating  also its msg_ctime member.  The
60              following members of  the  structure  are  updated:  msg_qbytes,
61              msg_perm.uid,  msg_perm.gid,  and  (the least significant 9 bits
62              of) msg_perm.mode.  The effective UID  of  the  calling  process
63              must  match  the owner (msg_perm.uid) or creator (msg_perm.cuid)
64              of the message queue, or the caller must be privileged.   Appro‐
65              priate  privilege  (Linux:  the  CAP_IPC_RESOURCE capability) is
66              required to raise the msg_qbytes value beyond the system parame‐
67              ter MSGMNB.
68
69       IPC_RMID
70              Immediately  remove  the  message  queue,  awakening all waiting
71              reader and writer processes (with an error return and errno  set
72              to EIDRM).  The calling process must have appropriate privileges
73              or its effective user ID must be either that of the  creator  or
74              owner of the message queue.
75
76       IPC_INFO (Linux specific)
77              Returns  information  about system-wide message queue limits and
78              parameters in the structure pointed to by buf.   This  structure
79              is  of  type  msginfo  (thus,  a  cast  is required), defined in
80              <sys/msg.h> if the _GNU_SOURCE feature test macro is defined:
81
82                struct msginfo {
83                    int msgpool; /* Size in bytes of buffer pool used
84                                    to hold message data; unused */
85                    int msgmap;  /* Max. # of entries in message
86                                    map; unused */
87                    int msgmax;  /* Max. # of bytes that can be
88                                    written in a single message */
89                    int msgmnb;  /* Max. # of bytes that can be written to
90                                    queue; used to initialize msg_qbytes
91                                    during queue creation (msgget()) */
92                    int msgmni;  /* Max. # of message queues */
93                    int msgssz;  /* Message segment size; unused */
94                    int msgtql;  /* Max. # of messages on all queues
95                                    in system; unused */
96                    unsigned short int msgseg;
97                                 /* Max. # of segments; unused */
98                };
99
100              The msgmni, msgmax, and msgmnb settings can be changed via /proc
101              files of the same name; see proc(5) for details.
102
103       MSG_INFO (Linux specific)
104              Returns  a  msginfo structure containing the same information as
105              for IPC_INFO, except that the following fields are returned with
106              information  about  system resources consumed by message queues:
107              the msgpool field returns the number of message queues that cur‐
108              rently  exist  on the system; the msgmap field returns the total
109              number of messages in all queues on the system; and  the  msgtql
110              field  returns  the total number of bytes in all messages in all
111              queues on the system.
112
113       MSG_STAT (Linux specific)
114              Returns a msqid_ds structure  as  for  IPC_STAT.   However,  the
115              msqid  argument  is not a queue identifier, but instead an index
116              into the kernel's  internal  array  that  maintains  information
117              about all message queues on the system.
118

RETURN VALUE

120       On  success,  IPC_STAT,  IPC_SET,  and IPC_RMID return 0.  A successful
121       IPC_INFO or MSG_INFO operation returns the index of  the  highest  used
122       entry  in  the  kernel's internal array recording information about all
123       message queues.  (This information can be used with  repeated  MSG_STAT
124       operations  to  obtain  information about all queues on the system.)  A
125       successful MSG_STAT operation returns the identifier of the queue whose
126       index was given in msqid.
127
128       On error, -1 is returned with errno indicating the error.
129

ERRORS

131       On failure, errno is set to one of the following:
132
133       EACCES     The  argument  cmd is equal to IPC_STAT or MSG_STAT, but the
134                  calling process does not have read permission on the message
135                  queue msqid, and does not have the CAP_IPC_OWNER capability.
136
137       EFAULT     The  argument cmd has the value IPC_SET or IPC_STAT, but the
138                  address pointed to by buf isn't accessible.
139
140       EIDRM      The message queue was removed.
141
142       EINVAL     Invalid value for cmd or msqid.  Or: for a  MSG_STAT  opera‐
143                  tion,  the  index  value  specified  in msqid referred to an
144                  array slot that is currently unused.
145
146       EPERM      The argument cmd has the value IPC_SET or IPC_RMID, but  the
147                  effective  user ID of the calling process is not the creator
148                  (as found in  msg_perm.cuid)  or  the  owner  (as  found  in
149                  msg_perm.uid)  of  the message queue, and the process is not
150                  privileged (Linux: it does not have the CAP_SYS_ADMIN  capa‐
151                  bility).
152

NOTES

154       The  IPC_INFO, MSG_STAT and MSG_INFO operations are used by the ipcs(8)
155       program to provide information on allocated resources.  In  the  future
156       these may modified or moved to a /proc file system interface.
157
158       Various  fields  in the struct msqid_ds were shorts under Linux 2.2 and
159       have become longs under Linux 2.4. To take advantage of this, a  recom‐
160       pilation  under glibc-2.1.91 or later should suffice.  (The kernel dis‐
161       tinguishes old and new calls by an IPC_64 flag in cmd.)
162

CONFORMING TO

164       SVr4, POSIX.1-2001.
165

SEE ALSO

167       msgget(2),  msgrcv(2),  msgsnd(2),   capabilities(7),   mq_overview(7),
168       svipc(7)
169
170
171
172Linux 2.6.9                       2004-11-10                         MSGCTL(2)
Impressum