#include <sys/msg.h> int msgctl(int msqid, int cmd, struct msqid_ds *buf);
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:
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.
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.
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:
|
||||||||||
| 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(). |
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.
| 0 | msgctl() was successful. |
| -1 | msgctl() was not successful. The errno variable is set to indicate the error. |
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.
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.
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.
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.
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:
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 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.
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.
None.
The following example performs a control operation on a message queue.
Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.
#include <sys/msg.h>
main() {
int msqid = 2;
int rc;
struct msqid_ds buf;
rc = msgctl(msqid, IPC_STAT, &buf);
}