MSGCTL


Perform the control operation specified by edx on the message queue with identifier ecx.

Arguments

ecx Message queue ID.
edx Command to perform. It may be one of the following:
IPC_STAT Copy information from the kernel data structure associated with ecx into the msqid_ds structure pointed to by esi. The caller must have read permission on the message queue.

struc msqid_ds
{
.msg_perm    ipc_perm ; Ownership and permissions
.msg_first   rd 1 ; First message on queue, unused
.msg_last    rd 1 ; Last message in queue, unused
.msg_stime   rd 1 ; Time of last MSGSND
.msg_rtime   rd 1 ; Time of last MSGRCV
.msg_ctime   rd 1 ; Time of last change
.msg_lcbytes rd 1 ; *to be documented*
.msg_lqbytes rd 1 ; *to be documented*
.msg_cbytes  rw 1 ; Current number of bytes in queue (non-standard)
.msg_qnum    rw 1 ; Current number of messages in queue
.msg_qbytes  rw 1 ; Maximum number of bytes allowed in queue
.msg_lspid   rw 1 ; PID of last MSGSND
.msg_lrpid   rw 1 ; PID of last MSGRCV
}

struc ipc_perm
{
.key  rd 1
.uid  rw 1
.gid  rw 1
.cuid rw 1
.cgid rw 1
.mode rw 1
.seq  rw 1
}
IPC_SET Write the values of some members of the msqid_ds structure pointed to by esi to the kernel data structure associated with this message queue, updating also its msg_ctime member. The following members of the structure are updated: msg_qbytes, msg_perm.uid, msg_perm.gid, and (the least significant 9 bits of) msg_perm.mode. The effective UID of the calling process must match the owner (msg_perm.uid) or creator (msg_perm.cuid) of the message queue, or the caller must be privileged. Appropriate privilege (the CAP_IPC_RESOURCE capability) is required to raise the msg_qbytes value beyond the system parameter MSGMNB.
IPC_RMID Immediately remove the message queue, awakening all waiting reader and writer processes (with an error return -EIDRM). The calling process must have appropriate privileges or its effective user ID must be either that of the creator or owner of the message queue.
IPC_INFO Returns information about system-wide message queue limits and parameters in the msginfo structure pointed to by esi:

struc msginfo
{
.msgpool rd 1
.msgmap  rd 1
.msgmax  rd 1
.msgmnb  rd 1
.msgmni  rd 1
.msgssz  rd 1
.msgtql  rd 1
.msgseg  rw 1
}

msginfo members:

msgpool
Size in bytes of buffer pool used to hold message data; unused
msgmap
Max. # of entries in message map; unused
msgmax
Max. # of bytes that can be written in a single message
msgmnb
Max. # of bytes that can be written to queue; used to initialize msg_qbytes during queue creation (MSGGET)
msgmni
Max. # of message queues
msgssz
Message segment size; unused
msgtql
Max. # of messages on all queues in system; unused
msgseg
Max. # of segments; unused

The msgmni, msgmax, and msgmnb settings can be changed via /proc files of the same name.

MSG_INFO Returns a msginfo structure (see above) containing the same information as for IPC_INFO, except that the following fields are returned with information about system resources consumed by message queues: the msgpool field returns the number of message queues that currently exist on the system; the msgmap field returns the total number of messages in all queues on the system; and the msgtql field returns the total number of bytes in all messages in all queues on the system.
MSG_STAT Returns a msqid_ds structure as for IPC_STAT. However, the msqid argument is not a queue identifier, but instead an index into the kernel's internal array that maintains information about all message queues on the system.
esi This parameter depends on the command used (edx). See above for information on available commands.

Return values

If the function succeeds the return value depends on the command used:

IPC_STAT, IPC_SET, IPC_RMID Return value is 0.
IPC_INFO, MSG_INFO Return value is the index of the highest used entry in the kernel's internal array recording information about all message queues. (This information can be used with repeated MSG_STAT operations to obtain information about all queues on the system.)
MSG_STAT Return value is the identifier of the queue whose index was given in ecx.

If the function fails the return value is one of the following errno values:

-EACCES The argument edx is equal to IPC_STAT or MSG_STAT, but the calling process does not have read permission on the message queue ecx, and does not have the CAP_IPC_OWNER capability.
-EFAULT The argument edx has the value IPC_SET or IPC_STAT, but the address pointed to by esi isn't accessible.
-EIDRM The message queue was removed.
-EINVAL Invalid value for edx or ecx. Or: for a MSG_STAT operation, the index value specified in ecx referred to an array slot that is currently unused.
-EPERM The argument edx has the value IPC_SET or IPC_RMID, but the effective user ID of the calling process is not the creator (as found in msg_perm.cuid) or the owner (as found in msg_perm.uid) of the message queue, and the process is not privileged (it does not have the CAP_SYS_ADMIN capability).

Remarks

The IPC_INFO, MSG_STAT and MSG_INFO operations are used by the ipcs program to provide information on allocated resources. In the future these may modified or moved to a /proc file system interface.