msgctl(2)msgctl(2)NAMEmsgctl - Perform message control operations
SYNOPSIS
#include <sys/msg.h>
int msgctl(
int msqid,
int cmd,
struct msqid_ds *buf );
Application developers might want to specify #include statements for
<sys/types.h> and <sys/ipc.h> before the one for <sys/msg.h> if pro‐
grams are being developed for multiple platforms. The additional
#include statements are not required on Tru64 UNIX systems or by ISO or
X/Open standards, but may be required on other vendors' systems that
conform to these standards.
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
msgctl(): XSH4.0, XSH4.2, XSH5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Specifies the message queue ID. Specifies the type of command. The
possible commands and the operations they perform are as follows:
Queries the message queue ID by copying the contents of its associated
data structure into the buf structure. The process must have mandatory
read access to the message queue with respect to all access control
policies. Sets the message queue ID by copying values found in the buf
structure into corresponding fields in the msqid_ds structure associ‐
ated with the message queue ID. This operation is restricted. The
effective user ID of the calling process must be equal to that of supe‐
ruser or equal to the value of msg_perm.uid or msg_perm.cuid in the
associated msqid_ds structure. Only superuser can raise the value of
msg_qbytes. Removes the message queue ID and deallocates its associ‐
ated msqid_ds structure. This operation is restricted. The effective
user ID of the calling process must be equal to that of superuser or
equal to the value of msg_perm.uid or msg_perm.cuid in the associated
msqid_ds structure. Points to an msqid_ds structure. This structure is
used only with the IPC_STAT and IPC_SET commands. With IPC_STAT, the
results of the query are copied to this structure. With IPC_SET, the
values in this structure are used to set the corresponding fields in
the msqid_ds structure associated with the message queue ID. In either
case, the calling process must have allocated the structure before mak‐
ing the call.
DESCRIPTION
The msgctl() function allows a process to query or set the contents of
the msqid_ds structure associated with the specified message queue ID.
It also allows a process to remove the message queue ID and its associ‐
ated msqid_ds structure. The cmd value determines which operation is
performed.
The IPC_SET command uses the user-supplied contents of the buf struc‐
ture to set the following members of the msqid_ds structure associated
with the message queue ID: The owner's user ID. The owner's group ID.
The access modes for the queue. Only the low-order nine bits are set.
The maximum number of bytes on the queue. The time of the last suc‐
cessful IPC_SET operation.
RETURN VALUES
Upon successful completion, msgctl() returns a value of 0 (zero). Oth‐
erwise, a value of -1 is returned and errno is set to indicate the
error.
ERRORS
The msgctl() function sets errno to the specified values for the fol‐
lowing conditions: The cmd parameter is IPC_STAT, but the calling
process does not have read permission. [Tru64 UNIX] The cmd parameter
is IPC_STAT or IPC_SET, and an error occurred in accessing the buf
structure. The msqid parameter is not a valid message queue ID, or the
cmd parameter is not a valid command. One of the following occurred:
The cmd parameter is equal to either IPC_RMID or IPC_SET, and the call‐
ing process does not have appropriate privilege. The cmd parameter is
equal to IPC_SET, and an attempt is being made to increase the value of
the msg_qbytes parameter when the calling process does not have the
superuser privilege.
SEE ALSO
Functions: msgget(2), msgrcv(2), msgsnd(2)
Data Structures: msqid_ds(4)
Standards: standards(5)msgctl(2)