msgctl(2) message control operations

LIBRARY

Lb libc

SYNOPSIS

In sys/types.h In sys/ipc.h In sys/msg.h Ft int Fn msgctl int msqid int cmd struct msqid_ds *buf

DESCRIPTION

The Fn msgctl system call performs some control operations on the message queue specified by Fa msqid .

Each message queue has a data structure associated with it, parts of which may be altered by Fn msgctl and parts of which determine the actions of Fn msgctl . The data structure is defined in In sys/msg.h and contains (amongst others) the following members:

struct msqid_ds {
        struct  ipc_perm msg_perm;      /* msg queue permission bits */
        struct  msg *msg_first; /* first message in the queue */
        struct  msg *msg_last;  /* last message in the queue */
        msglen_t msg_cbytes;    /* number of bytes in use on the queue */
        msgqnum_t msg_qnum;     /* number of msgs in the queue */
        msglen_t 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 Vt ipc_perm structure used inside the Vt msqid_ds structure is defined in 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;   /* r/w permission */
        unsigned short  seq;    /* sequence # (to generate unique ipcid) */
        key_t           key;    /* user specified msg/sem/shm key */
};

The operation to be performed by Fn msgctl is specified in Fa cmd and is one of:

IPC_STAT
Gather information about the message queue and place it in the structure pointed to by Fa 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 Fa msqid . The values are taken from the corresponding fields in the structure pointed to by Fa buf . This operation can only be executed by the super-user, 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 super-user. Values for msg_qbytes that exceed the system limit (MSGMNB from In sys/msg.h ) are silently truncated to that limit.
IPC_RMID
Remove the message queue specified by Fa msqid and destroy the data associated with it. Only the super-user 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 either 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

RETURN VALUES

Rv -std msgctl

ERRORS

The Fn msgctl function will fail if:

Bq Er EPERM
The Fa cmd argument is equal to IPC_SET or IPC_RMID and the caller is not the super-user, 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 super-user.

Bq Er EACCES
The command is IPC_STAT and the caller has no read permission for this message queue.
Bq Er EINVAL
The Fa msqid argument is not a valid message queue identifier.

cmd is not a valid command.

Bq Er EFAULT
The Fa buf argument specifies an invalid address.

HISTORY

Message queues appeared in the first release of AT&T System V .