msgctl()--Perform Message Control Operations

Syntax

 #include <sys/msg.h>

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

  Service Program Name: QP0ZUSHR

  Default Public Authority: *USE

  Threadsafe: Yes

The msgctl() function allows the caller to control the message queue specified by the msqid parameter.

A message queue is controlled by setting the cmd parameter to one of the following values:

IPC_RMID (0x00000000)

Remove the message queue identifier msqid from the system and destroy any messages on the message queue. Any threads that are waiting in msgsnd() or msgrcv() are woken up and msgsnd() or msgrcv() returns with a return value of -1 and errno set to EIDRM.

The IPC_RMID command can be run only by a thread with appropriate privileges or one that has an effective user ID equal to the user ID of the owner or the user ID of the creator of the message queue. The structure pointed to by *buf is ignored and can be NULL.

IPC_SET (0x00000001)

Set the user ID of the owner, the group ID of the owner, the permissions, and the maximum number of bytes for the message queue to the values in the msg_perm.uid, msg_perm.gid, msg_perm.mode, and msg_qbytes members of the msqid_ds data structure pointed to by *buf.

The IPC_SET command can be run only by a thread with appropriate privileges or one that has an effective user ID equal to the user ID of the owner or the user ID of the creator of the message queue.

In addition, only a thread with appropriate privileges can increase the maximum number of bytes for the message queue.

IPC_STAT (0x00000002)

Store the current value of each member of the msqid_ds data structure into the structure pointed to by *buf. The IPC_STAT command requires read permission to the message queue.

Parameters

msqid

(Input) Message queue identifier, a positive integer. It is returned by the msgget() function and used to identify the message queue on which to perform the control operation.

cmd

(Input) Command, the control operation to perform on the message queue. Valid values are listed above.

buf

(I/O) Pointer to the message queue data structure to be used to get or set message queue information.

The members of the msqid_ds structure are as follows:

struct ipc_perm msg_perm

The members of the ipc_perm structure are as follows:

uid_t uid	The user ID of the owner of the message queue.
gid_t gid	The group ID of the owner of the message queue.
uid_t cuid	The user ID of the creator of the message queue.
gid_t cgid	The group ID of the creator of the message queue.
mode_t mode	The permissions for the message queue.

msgnum_t msg_qnum

The number of messages currently on the message queue.

msglen_t msg_qbytes

The maximum number of bytes allowed on the message queue.

pid_t msg_lspid

The process ID of the last job to send a message using msgsnd().

pid_t msg_lrpid

The process ID of the last job to receive a message using msgrcv().

time_t msg_stime

The time the last job sent a message to the message queue using msgsnd().

time_t msg_rtime

The time the last job received a message from the message queue using msgrcv().

time_t msg_ctime

The time the last job changed the message queue using msgctl().

Authorities

Authorization Required for msgctl()

Object Referred to	Authority Required	errno
Message queue for which state information is retrieved (cmd = IPC_STAT)	Read	EACCES
Message queue for which state information is set (cmd = IPC_SET)	See Note	EPERM
Message queue to be removed (cmd = IPC_RMID)	See Note	EPERM

Note: To set message queue information or to remove a message queue, the thread must be the owner or creator of the queue, or have appropriate privileges. To increase the maximum number of bytes for the message queue, a thread must have appropriate privileges.

Return Value

0	msgctl() was successful.
-1	msgctl() was not successful. The errno variable is set to indicate the error.

Error Conditions

If msgctl() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.

[EACCES]

Permission denied.

An attempt was made to access an object in a way forbidden by its object access permissions.

The thread does not have access to the specified file, directory, component, or path.

The cmd parameter is IPC_STAT and the calling thread does not have read permission.

[EDAMAGE]

A damaged object was encountered.

A referenced object is damaged. The object cannot be used.

The message queue has been damaged by a previous message queue operation.

[EFAULT]

The address used for an argument is not correct.

In attempting to use an argument in a call, the system detected an address that is not valid.

While attempting to access a parameter passed to this function, the system detected an address that is not valid.

[EINVAL]

The value specified for the argument is not correct.

A function was passed incorrect argument values, or an operation was attempted on an object and the operation specified is not supported for that type of object.

An argument value is not valid, out of range, or NULL.

One of the following has occurred:

The msqid parameter is not a valid message queue identifier.
The cmd parameter is not a valid command.
The cmd parameter is IPC_SET and the value of msg_qbytes exceeds the system limit.

[EPERM]

Operation not permitted.

You must have appropriate privileges or be the owner of the object or other resource to do the requested operation.

The cmd parameter is equal to IPC_RMID or IPC_SET and both of the following are true:

the caller does not have the appropriate privileges.
the effective user ID of the caller is not equal to the user ID of the owner or the user ID of the creator of the message queue.

The cmd parameter is IPC_SET and an attempt is being made to increase the maximum number of bytes for the message queue, but the the caller does not have appropriate privileges.

[EUNKNOWN]

Unknown system state.

The operation failed because of an unknown system state. See any messages in the job log and correct any errors that are indicated, then retry the operation.

Error Messages

None.

Usage Notes

"Appropriate privileges" is defined to be *ALLOBJ special authority. If the user profile under which the thread is running does not have *ALLOBJ special authority, the caller does not have appropriate privileges.

Related Information

The <sys/msg.h> file (see Header Files for UNIX-Type Functions)
Message Queues for the current system limits.
msgget()--Get Message Queue
msgrcv()--Receive Message Operation
msgsnd()--Send Message Operation

Example

See Code disclaimer information for information pertaining to code examples.

The following example performs a control operation on a message queue:

#include <sys/msg.h>

main() {
  int msqid = 2;
  int rc;
  struct msqid_ds buf;

  rc = msgctl(msqid, IPC_STAT, &buf);
}

API introduced: V3R6

Top | UNIX-Type APIs | APIs by category