msgctl()-Perform Message Control Operations

#include <sys/msg.h>

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

The msgctl() function provides message control operations as specified by cmd on the message queue specified by msqid.

Parameters

msqid

(Input) Message queue identifier, a positive integer. It is created 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.

buf

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

The cmd parameter can have one of the following values:

IPC_STAT

Put the current value of each member of the msqid_ds data structure associated with msqid into the structure pointed to by buf.

IPC_SET

Set the value of the following members of the msqid_ds data structure associated with msqid to the corresponding value found in the structure pointed to by buf:

• msg_perm.uid

• msg_perm.gid

• msg_perm.mode

• msg_qbytes

IPC_SET can be run only by a thread with appropriate privileges or one that has an effective user ID equal to the value of msg_perm.cuid or msg_perm.uid in the msqid_ds data structure associated with msqid. Only a thread with appropriate privileges can raise the value of msg_qbytes.

IPC_RMID

Remove the message queue identifier specified by msqid from the system and destroy the message queue and msqid_ds data structure associated with it. IPC_RMID can be run only by a thread with appropriate privileges or one that has an effective user ID equal to the value of msg_perm.cuid or msg_perm.uid in the msqid_ds data structure associated with msqid. The structure pointed to by buf is ignored and can be NULL.

Authorities

Figure 1-4. 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 raise the value of msg_qbytes, 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.

If you are accessing a remote file through the Network File System, update operations to file permissions at the server are not reflected at the client until updates to data that is stored locally by the Network File System take place. (Several options on the Add Mounted File System (ADDMFS) command determine the time between refresh operations of local data.) Access to a remote file may also fail due to different mappings of user IDs (UID) or group IDs (GID) on the local and remote systems.

The parameter cmd is IPC_STAT, but 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.

[ERROR_INVALID_PARAMETER]

An invalid parameter was found.

A parameter passed to this function is not valid.

One of the following has occurred:

• The value of cmd is either IPC_SET or IPC_STAT and the value of buf is NULL.

• The value of msqid is not a valid message queue identifier.

• The value of cmd is not a valid command.

• The value of cmd is IPC_SET and the value of msg_qbytes exceeds the system-imposed 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 parameter cmd 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 value of msg_perm.cuid or msg_perm.uid in the data structure associated with msgid.

The parameter cmd is IPC_SET and an attempt is being made to increase the value of msg_qbytes, 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

1. "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)

• msgget()-Get Message Queue

• msgrcv()-Receive Message Operation

• msgsnd()-Send Message Operation

Example

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

#include <sys/msg.h>

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

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