MSGCTL(2) BSD Programmer's Manual MSGCTL(2)
msgctl - message control operations
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/msg.h>
int
msgctl(int msqid, int cmd, struct msqid_ds *buf);
The msgctl() system call performs some control operations on the message
queue specified by msqid.
Each message queue has a data structure associated with it, parts of
which may be altered by msgctl() and parts of which determine the actions
of msgctl(). The data structure is defined in <sys/msg.h> and contains
(amongst others) the following members:
struct msqid_ds {
struct ipc_perm msg_perm; /* msg queue permission bits */
u_long msg_cbytes; /* # of bytes in use on the queue */
u_long msg_qnum; /* # of msgs in the queue */
u_long msg_qbytes; /* max # of bytes on the queue */
pid_t msg_lspid; /* pid of last msgsnd() */
pid_t msg_lrpid; /* pid of last msgrcv() */
time_t msg_stime; /* time of last msgsnd() */
time_t msg_rtime; /* time of last msgrcv() */
time_t msg_ctime; /* time of last msgctl() */
};
The ipc_perm structure used inside the shmid_ds structure is defined in
<sys/ipc.h> and looks like this:
struct ipc_perm {
uid_t cuid; /* creator user id */
gid_t cgid; /* creator group id */
uid_t uid; /* user id */
gid_t gid; /* group id */
mode_t mode; /* permission (9 bits, see chmod(2)) */
u_short seq; /* sequence # (to generate unique id) */
key_t key; /* user specified msg/sem/shm key */
};
The operation to be performed by msgctl() is specified in cmd and is one
of:
IPC_STAT Gather information about the message queue and place it in the
structure pointed to by buf.
IPC_SET Set the value of the msg_perm.uid, msg_perm.gid, msg_perm.mode
and msg_qbytes fields in the structure associated with msqid.
The values are taken from the corresponding fields in the
structure pointed to by buf. This operation can only be exe-
cuted by the superuser, or a process that has an effective
user ID equal to either msg_perm.cuid or msg_perm.uid in the
data structure associated with the message queue. The value of
msg_qbytes can only be increased by the superuser. Values for
msg_qbytes that exceed the system limit (MSGMNB from
<sys/msg.h>) are silently truncated to that limit.
IPC_RMID Remove the message queue specified by msqid and destroy the
data associated with it. Only the superuser or a process with
an effective UID equal to the msg_perm.cuid or msg_perm.uid
values in the data structure associated with the queue can do
this.
The permission to read from or write to a message queue (see msgsnd(2)
and msgrcv(2)) is determined by the msg_perm.mode field in the same way
as is done with files (see chmod(2)), but the effective UID can match ei-
ther the msg_perm.cuid field or the msg_perm.uid field, and the effective
GID can match either msg_perm.cgid or msg_perm.gid.
Upon successful completion, a value of 0 is returned. Otherwise, -1 is
returned and the global variable errno is set to indicate the error.
msgctl() will fail if:
[EPERM] cmd is equal to IPC_SET or IPC_RMID and the caller is not
the superuser, nor does the effective UID match either the
msg_perm.uid or msg_perm.cuid fields of the data structure
associated with the message queue.
An attempt is made to increase the value of msg_qbytes
through IPC_SET but the caller is not the superuser.
[EACCES] The command is IPC_STAT and the caller has no read permis-
sion for this message queue.
[EINVAL] msqid is not a valid message queue identifier.
cmd is not a valid command.
[EFAULT] buf specifies an invalid address.
msgget(2), msgrcv(2), msgsnd(2)
Message queues appeared in the first release of AT&T Unix System V.
MirBSD #10-current August 17, 1995 1