msgctl Subroutine

Base Operating System and Extensions Technical Reference, Volume 1

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:

Maximum message size is 65,535 bytes for releases prior to AIX 4.1.5 and is 4 Megabytes for release 4.1.5 and later releases.
Maximum number of messages per queue is 8192.
Maximum number of message queue IDs is 4096 for AIX releases before 4.3.2 and 131072 for AIX 4.3.2 and following.
Maximum number of bytes in a queue is 4 65,535 for releases prior to AIX 4.1.5 and is 4 Megabytes for release 4.1.5 and later releases.

Parameters

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 its process ID 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:

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.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The msgget subroutine, msgrcv subroutine, msgsnd subroutine, msgxrcv subroutine.