msgctl Subroutine

Purpose

Provides message control operations.

Library

Standard C Library (libc.a)

Syntax

#include <sys/msg.h>

int msgctl (MessageQueueID,Command,Buffer)
int  MessageQueueID,  Command;
struct msqid_ds * Buffer;

Description

The msgctl subroutine provides a variety of message control operations as specified by the Command parameter and stored in the structure pointed to by the Buffer parameter. The msqid_ds structure is defined in the sys/msg.h file.

The following limits apply to the message queue:

Parameters

Item Description
MessageQueueID Specifies the message queue identifier.
Command The following values for the Command parameter are available:
IPC_STAT
Stores the current value of the above fields of the data structure associated with the MessageQueueID parameter into the msqid_ds structure pointed to by the Buffer parameter.

The current process must have read permission in order to perform this operation.

IPC_SET
Sets the value of the following fields of the data structure associated with the MessageQueueID parameter to the corresponding values found in the structure pointed to by the Buffer parameter:
msg_perm.uid
msg_perm.gid
msg_perm.mode/*Only the low-order 
nine bits*/
msg_qbytes

The effective user ID of the current process must have root user authority or must equal the value of the msg_perm.uid or msg_perm.cuid field in the data structure associated with the MessageQueueID parameter in order to perform this operation. To raise the value of the msg_qbytes field, the effective user ID of the current process must have root user authority.

IPC_RMID
Removes the message queue identifier specified by the MessageQueueID parameter from the system and destroys the message queue and data structure associated with it. The effective user ID of the current process must have root user authority or be equal to the value of the msg_perm.uid or msg_perm.cuid field in the data structure associated with the MessageQueueID parameter to perform this operation.
Buffer Points to a msqid_ds structure.

Return Values

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

Error Codes

The msgctl subroutine is unsuccessful if any of the following conditions is true:

Item Description
EINVAL The Command or MessageQueueID parameter is not valid.
EACCES The Command parameter is equal to the IPC_STAT value, and the calling process was denied read permission.
EPERM The Command parameter is equal to the IPC_RMID value and the effective user ID of the calling process does not have root user authority. Or, the Command parameter is equal to the IPC_SET value, and the effective user ID of the calling process is not equal to the value of the msg_perm.uid field or the msg_perm.cuid field in the data structure associated with the MessageQueueID parameter.
EPERM The Command parameter is equal to the IPC_SET value, an attempt was made to increase the value of the msg_qbytes field, and the effective user ID of the calling process does not have root user authority.
EFAULT The Buffer parameter points outside of the process address space.