msgctl(2)                      DG/UX R4.11MU05                     msgctl(2)


NAME
       msgctl - get or set message queue attributes or destroy a message
       queue

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

       int  msgctl (msqid, cmd, buf)
       int  msqid;
       int  cmd;
       struct msqidds * buf;

   where:
       msqid     A message queue identifier
       cmd       The message control operation to be performed
       buf       The address of a message queue attribute record (used only
                 if cmd is IPC_STAT or IPC_SET)

DESCRIPTION
       Use msgctl to get and set message queue attributes or to destroy a
       message queue.  The subject message queue is identified by msqid.
       The action performed by msgctl depends on the value of cmd as
       follows:

       IPC_STAT  The user-visible msqid_ds structure is returned in buf.  If
                 an error occurs, the contents of buf are undefined.

       IPC_SET   The following message queue attributes are set to the
                 values found in the structure pointed to by buf: user id
                 (msg_perm.uid), group id (msg_perm.gid), permission rights
                 (in msg_perm.mode), and the maximum size (msg_qbytes).

                 If an error occurs, the message queue remains unchanged.
                 Otherwise, the last change time (msg_ctime) is set to the
                 current time.

       IPC_RMID  The message queue is destroyed.  All resources consumed by
                 the message queue are freed and the message queue
                 identifier is invalidated.  All queued messages are lost.

                 If an error occurs, the message queue remains unchanged.

       Note that the msqidds struct that is returned with the IPC_STAT and
       IPC_SET action arguments differs in the ELF and COFF environments.
       Specifically, the fields msgcbytes, msgqnum, and msgqbytes are
       type unsigned long in the ELF environment and type unsigned short in
       the COFF environment. In both environments, a message queue allows
       the attributes reported in these fields to have values larger than
       will fit in a short container.  Therefore, if a COFF program uses
       msgctl(2) with the IPC_STAT option, the kernel might not report the
       correct values for these attributes.

ACCESS CONTROL
       Operation permission depends on the value of cmd as follows:

       IPC_STAT  The calling process is required to have read access to the
                 message queue.

       IPC_SET   The effective user id of the calling process must be equal
                 to the message queue's user id, the message queue creator's
                 user id, or the calling process must have appropriate
                 privilege.  If the maximum size of the message queue is
                 increased, the calling process must have appropriate
                 privilege.

       IPC_RMID  The effective user id of the calling process must be equal
                 to the message queue's user id, the message queue creator's
                 user id, or the calling process must have appropriate
                 privilege.

RETURN VALUE
       0      Completed successfully.

       -1     An error occurred.  errno is set to indicate the error.

DIAGNOSTICS
       Errno may be set to one of the following error codes regardless of
       the value of cmd:

       EINVAL    msqid is not a valid message queue identifier.

       EINVAL    cmd is not a valid command.

       If cmd is IPC_STAT, errno may be set to one of these values:

       EACCES    Read permission is denied to the calling process.

       EFAULT    buf points to an illegal address.

       If cmd is IPC_SET, errno may be set to one of these values:

       EPERM     Permission to change the message queue attributes is denied
                 to the calling process.

       EPERM     Permission to increase to the maximum size of the message
                 queue is denied to the calling process.

       EFAULT    buf points to an illegal address.

       If cmd is IPC_RMID, errno may be set to this value:

       EPERM     Permission to remove the message queue is denied to the
                 calling process.

SEE ALSO
       intro(2), ipcrm(1), ipcs(1), msgget(2), msgrcv(2), msgsnd(2),
       appropriateprivilege(5).
       capdefaults(5).

NOTES
       For systems supporting the DG/UX Capability Option, appropriate
       privilege is defined as having one or more specific capabilities
       enabled in the effective capability set of the calling process.  See
       capdefaults(5) for the default capability for this system call.

       On systems without the DG/UX Capability Option, appropriate privilege
       means that the process has an effective UID of root.  See the
       appropriateprivilege(5) man page for more information.  means that
       the process has an effective UID of root.


Licensed material--property of copyright holder(s)