msgctl(2) — AIX PS/2 1.2.1



MSGCTL(2,L)                 AIX Technical Reference                 MSGCTL(2,L)



-------------------------------------------------------------------------------
msgctl



PURPOSE

Provides message control operations.

LIBRARY

Standard C Library (libc.a)

SYNTAX

#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/msg.h>

int msgctl (msqid, cmd, buf)
int msqid, cmd;
struct msqid.ds *buf;

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 */
  pid_t           msg_lspid;    /* ID of last process to call msgsnd */
  pid_t           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 cmds are available:

IPC_STAT  Stores the current value of the members of the data structure
          associated with the msqid parameter into the msqid.ds structure
          pointed to by the buf parameter.  The current process must have read
          permission in order to perform this operation.






Processed November 7, 1990        MSGCTL(2,L)                                 1



MSGCTL(2,L)                 AIX Technical Reference                 MSGCTL(2,L)



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 parameter:

                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.

IPC_RMID  Removes the message queue identifier specified 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 associated with msqid in order to perform this
          operation.

Warning:  If the Transparent Computing Facility is installed, a message queue
exists only on the cluster site on which the queue was created.  Consequently,
processes that use message queues cannot be migrated to other sites.

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.

ERROR CONDITIONS

The msgctl system call fails if one or more of the following 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 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.





Processed November 7, 1990        MSGCTL(2,L)                                 2



MSGCTL(2,L)                 AIX Technical Reference                 MSGCTL(2,L)



EFAULT  The buf parameter points to a location outside of the process's
        allocated address space.

RELATED INFORMATION

In this book:  "msgget,"  "msgrcv,"  "msgsnd," and "msgxrcv."

















































Processed November 7, 1990        MSGCTL(2,L)                                 3

Museum

Related Articles