August 25, 1999 MSGCTL 2

### NAME

msgctl - message control operations

### LIBRARY

Standard C Library (libc, -lc)

### SYNOPSIS

```int` msgctl(```int msqid``, int cmd``, struct msqid_ds *buf`)

### DESCRIPTION

The msgctl(``) system call performs control operations on the message queue specified by ```msqid`.

Each message queue has a msqid_ds structure associated with it which contains the following members: ``

        struct ipc_perm msg_perm; /* msg queue permission bits */
        msgqnum_t msg_qnum;       /* # 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 ipc_perm structure used inside the msgid_ds structure is defined in <```sys/ipc.h`> and contains the following members: ``

        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 (lower 9 bits) */

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 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 <```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 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

Upon successful completion, a value of 0 is returned. Otherwise, -1 is returned and the global variable errno is set to indicate the error.

### ERRORS

msgctl(``) will fail if:

[```EPERM`]
  ```cmd` 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 was made to increase the value of msg_qbytes through ```IPC_SET`, but the caller is not the super-user.

[```EACCES`]
  ```cmd` is ```IPC_STAT` and the caller has no read permission 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.

### SEE ALSO

msgget(2), msgrcv(2), msgsnd(2)

### STANDARDS

The msgctl system call conforms to X/Open System Interfaces and Headers Issue 5 (``XSH5'') .

### HISTORY

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