msgctl
Purpose
Provides message control operations.
Syntax
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/msg.h>
int msgctl (msqid, cmd, buf)
-- or --
int msgctl (msqid, cmd, mtype)
int msqid, cmd;
struct msqid_ds *buf;
int mtype;
Description
The msgctl system call provides a variety of message
control operations as specified by cmd parameter. The
buf parameter points to a structure of type msqid_ds.
The msqid_ds structure is defined in the sys/msg.h header
file, and it contains the following members:
struct ipc_perm msg_perm; /* Operation permission structure */
struct msg *msg_first; /* Ptr to first message on the queue */
struct msg *msg_last; /* Ptr to last message on the queue */
ushort msg_cbytes; /* Current number of bytes on the queue */
ushort msg_qnum; /* Number of messages on the queue */
ushort msg_qbytes; /* Maximum number of bytes on the queue */
ushort msg_lspid; /* ID of last process to call msgsnd */
ushort msg_lrpid; /* ID of last process to call msgrcv */
time_t msg_stime; /* Time of last msgsnd call */
time_t msg_rtime; /* Time of last msgrcv call */
time_t msg_ctime; /* Time of the last change to this */
/* structure with a msgctl call */
/* The following members support Distributed Services IPC: */
long msg_nid; /* DS - real queue's node ID */
int msg_qid; /* DS - real queue's queue ID */
key_t msg_rkey; /* DS - caller's mapped key */
ushort msg_lsnid; /* DS - nid of last msgsnd */
ushort msg_lrnid; /* DS - nid of last msgrcv */
mtyp_t msg_mtype; /* DS - server's mtype value */
int msg_bootcnt; /* DS - server's boot count */
struct node *msg_conn; /* DS - connect for this surrogate */
The following cmds are available:
IPC_STAT Stores the current value of the first eleven
members of the data structure associated with
the msqid parameter into the msqid_ds struc-
ture pointed to by the buf parameter. The
structure members that support Distributed
Services are not included.
The current process must have read permission
in order to perform this operation. If the
queue resides in a remote node, then the
information in the structure (msg_lspid,
msg_stime, and so on) is relative to that
node.
If the last sent (or received) message came
from a node other than the one that holds the
queue, then the process ID (pid) reported for
msg_lspid is the process ID of the trans-
action process that actually operated on the
queue, not the process ID at the remote
machine.
IPC_SET Sets the value of the following members of
the data structure associated with the msqid
parameter to the corresponding values found
in the structure pointed to by the buf param-
eter:
msg_perm.uid
msg_perm.gid
msg_perm.mode /* Only the low-order nine bits */
msg_qbytes
The current process must have an effective
user ID equal to either that of superuser or
to the value of msg_perm.uid in the data
structure associated with msqid in order to
perform this operation. To raise the value
of msg_qbytes, the effective user ID of the
current process must be superuser.
If msqid identifies a remote queue, the
remote node uses the translated versions of
the caller's user and group IDs to determine
if the caller has permission to delete the
queue. See Managing the AIX Operating
System.
For remote queues, the user and group IDs of
the calling process are sent to the node
where the queue resides. The remote node
performs inbound ID translation and uses the
result to determine if the caller has permis-
sion to run the command. See Managing the
AIX Operating System for a discussion of user
and group ID translation.
IPC_RMID Removes the message queue identifier speci-
fied by the msqid parameter from the system
and destroys the message queue and data
structure associated with it. The current
process must have an effective user ID equal
to either that of superuser or to the value
of msg_perm.uid in the data structure associ-
ated with msqid in order to perform this
operation.
If msqid identifies a remote queue, the
remote node uses the translated versions of
the caller's user and group IDs to determine
if the caller has permission to delete the
queue. See Managing the AIX Operating System
for a discussion of user and group ID trans-
lation.
If a remote queue cannot be removed (for
example, if permission is denied), then the
local queue header is not removed either.
Otherwise, both the remote and local queue
information is removed.
If Distributed Services is installed on your system, the
following cmds are also available:
IPC_STAT2 Returns information about message queues,
including the Distributed Services structure
members, regardless of whether the queue is
remote or local. buf is assumed to point to
a msqid_ds structure. New programs that wish
to learn status information about IPC queues
should use IPC_STAT2 rather than IPC_STAT.
IPC_RMID2 Removes the local header for the remote queue
associated with msqid without attempting to
remove the remote queue itself. If msqid
does not identify a remote queue, then msgctl
sets errno to EINVAL. Like IPC_RMID,
IPC_RMID2 requires that the current process
have an effective user ID equal to either
that of superuser or to the value of
msg_perm.uid in the data structure associated
with msqid in order to perform this opera-
tion.
IPC_MTYP Returns the current mtype value and post
increments the mtype value. The mtype value
is not allowed to become negative. The mtype
value is returned in *buf, which is assumed
to be a pointer to a long integer. For
further information on use of the IPC_MTYP
cmd, see the discussion of bidirectional
queues in "System Calls" of AIX Operating
System Programming Tools and Interfaces.
Return Value
Upon successful completion, a value of 0 is returned. If
the msgctl system call fails, a value of -1 is returned
and errno is set to indicate the error.
Diagnostics
The msgctl system call fails if one or more of the fol-
lowing are true:
EINVAL msqid is not a valid message queue identifier.
EINVAL cmd is not a valid command.
EACCES cmd is equal to IPC_STAT and read permission
is denied to the calling process.
EPERM cmd is equal to IPC_RMID, IPC_SET, or
IPC_RMID2 and the effective user ID of the
calling process (translated for a remote
queue) is not equal to that of superuser, nor
is it equal to the value of msg_perm.uid in
the data structure associated with msqid.
EPERM cmd is equal to IPC_SET, an attempt is being
made to increase to the value of msg_qbytes,
and the effective user ID of the calling
process is not equal to that of superuser.
EFAULT The buf parameter &pointsout..
If Distributed Services is installed on your system,
msgctl can also fail if one or more of the following are
true:
EINVAL The cmd specified was IPC_RMID2, but msqid
does not identify a remote queue.
ESTALE The current boot count of the server is the
same as when the msqid was obtained.
EDIST The server has blocked new inbound
requests.
EDIST Outbound requests are currently blocked.
EDIST The server has a release level of Distrib-
uted Services that cannot communicate with
this node.
EAGAIN The server is too busy to accept the
request.
EPERM The translate tables of the server did not
contain any entry for either the effective
user ID or effective group ID of the
calling process.
ENOMEM Either this node or the server does not
have enough memory available to service the
request.
ENOCONNECT An attempt to establish a new network con-
nection with a remote node failed.
EBADCONNECT An attempt to use an existing network con-
nection with a remote node failed.
Related Information
In this book: "msgget," "msgrcv," "msgsnd," "msgxrcv,"
"create_ipc_prof," "del_ipc_prof," and -- Heading id
'fipcpro' unknown --.
Managing the AIX Operating System.
AIX Operating System Programming Tools and Interfaces.