OSF

NAME

msgctl −  Performs 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) ;

PARAMETERS

msqidSpecifies the message queue ID. 

cmdSpecifies the type of command.  The possible commands and the operations they perform are as follows:

IPC_STATQueries the message queue ID by copying the contents of its associated data structure into the buf structure. 

IPC_SETSets the message queue ID by copying values found in the buf structure into corresponding fields in the msqid_ds structure associated with the message queue ID.  This is a restricted operation.  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.  Only superuser can raise the value of msg_qbytes. 

IPC_RMIDRemoves the message queue ID and deallocates its associated msqid_ds structure.  This is a restricted operation.  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. 

bufPoints to a 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 making 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 associated msqid_ds structure.  The cmd value determines which operation is performed. 

The IPC_SET command uses the user-supplied contents of the buf structure to set the following members of the msqid_ds structure associated with the message queue ID:

msg_perm.uid
The owner’s user ID.

msg_perm.gid
The owner’s group ID.

msg_perm.mode
The access modes for the queue.  Only the low-order nine bits are set.

msg_qbytes
The maximum number of bytes on the queue.

msg_ctimeThe time of the last msgctl() operation that changed the structure. 

RETURN VALUES

Upon successful completion, a value of 0 (zero) is returned. Otherwise, a value of -1 is returned and errno is set to indicate the error. 

ERRORS

If the msgctl() function fails, errno may be set to one of the following values:

[EINVAL]The msqid parameter is not a valid message queue ID, or the cmd parameter is not a valid command. 

[EACCES]The cmd parameter is IPC_STAT, but the calling process does not have read permission. 

[EPERM]The cmd parameter is equal to either IPC_RMID or IPC_SET, and the calling process does not have appropriate privilege. 

[EPERM]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 effective user ID of the calling process does not have the SET_OBJ_STAT system privilege. 

[EFAULT]The cmd parameter is IPC_STAT or IPC_SET.  An error occurred in accessing the buf structure. 

RELATED INFORMATION

Functions: msgget(2), msgrcv(2), msgsnd(2)

Data Structures: msqid_ds(4)