NAME
msgctl - message control operations
SYNOPSIS
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/msg.h>
int msgctl ( int msqid, int cmd, struct msqid_ds *buf )
DESCRIPTION
The function performs the control operation specified by cmd on the message queue with identifier msqid. Legal values for cmd are:
- IPC_STAT
- Copy info from the message queue data structure into the structure pointed to by buf. The user must have read access privileges on the message queue.
- IPC_SET
- Write the values of some members of the msqid_ds structure pointed to by buf to the message queue data structure, updating also its msg_ctime member. Considered members from the user supplied struct msqid_ds pointed to by buf are
- msg_perm.uid
- msg_perm.gid
- msg_perm.mode /* only lowest 9-bits */
- msg_qbytes
- The calling process effective user-ID must be one among super-user, creator or owner of the message queue. Only the super-user can raise the msg_qbytes value beyond the system parameter MSGMNB.
- IPC_RMID
- Remove immediately the message queue and its data structures awakening all waiting reader and writer processes (with an error return and errno set to EIDRM). The calling process effective user-ID must be one among super-user, creator or owner of the message queue.
RETURN VALUE
If successful, the return value will be 0, otherwise -1 with errno indicating the error.
ERRORS
For a failing return, errno will be set to one among the following values:
- EACCES
- The argument cmd is equal to IPC_STAT but the calling process has no read access permissions on the message queue msqid.
- EFAULT
- The argument cmd has value IPC_SET or IPC_STAT but the address pointed to by buf isn't accessible.
- EIDRM
- The message queue was removed.
- EINVAL
- Invalid value for cmd or msqid.
- EPERM
- The argument cmd has value IPC_SET or IPC_RMID but the calling process effective user-ID has insufficient privileges to execute the command. Note
this is also the case of a non super-user process trying to increase the msg_qbytes value beyond the value specified by the system parameter MSGMNB.
NOTES
The IPC_INFO, MSG_STAT and MSG_INFO control calls are used by the ipcs(8) program to provide information on allocated resources. In the future these can be modified as needed or moved to a proc file system interface.
Various fields in a struct msqid_ds were shorts under Linux 2.2 and have become longs under Linux 2.4. To take advantage of this, a recompilation under glibc-2.1.91 or later should suffice. (The kernel distinguishes old and new calls by a IPC_64 flag in cmd.)
CONFORMING TO
SVr4, SVID. SVID does not document the EIDRM error condition.
SEE ALSO
ipc(5), msgget(2), msgsnd(2), msgrcv(2)