PROLOG

       This  manual  page  is part of the POSIX Programmer's Manual.  The Linux implementation of this interface
       may differ (consult the corresponding Linux manual page for details of Linux behavior), or the  interface
       may not be implemented on Linux.

NAME

       msgctl — XSI message control operations

SYNOPSIS

       #include <sys/msg.h>

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

DESCRIPTION

       The  msgctl()  function  operates on XSI message queues (see the Base Definitions volume of POSIX.1‐2008,
       Section 3.225, Message Queue).  It is unspecified whether this function interoperates with  the  realtime
       interprocess communication facilities defined in Section 2.8, Realtime.

       The msgctl() function shall provide message control operations as specified by cmd.  The following values
       for cmd, and the message control operations they specify, are:

       IPC_STAT    Place  the  current value of each member of the msqid_ds data structure associated with msqid
                   into the structure pointed to by  buf.   The  contents  of  this  structure  are  defined  in
                   <sys/msg.h>.

       IPC_SET     Set  the  value of the following members of the msqid_ds data structure associated with msqid
                   to the corresponding value found in the structure pointed to by buf:

                       msg_perm.uid
                       msg_perm.gid
                       msg_perm.mode
                       msg_qbytes

                   Also, the msg_ctime timestamp shall be set to the  current  time,  as  described  in  Section
                   2.7.1, IPC General Description.

                   IPC_SET  can  only  be  executed  by  a  process  with  appropriate privileges or that has an
                   effective user ID equal to the value of msg_perm.cuid or msg_perm.uid in  the  msqid_ds  data
                   structure  associated  with  msqid.  Only a process with appropriate privileges can raise the
                   value of msg_qbytes.

       IPC_RMID    Remove the message queue identifier specified by  msqid  from  the  system  and  destroy  the
                   message queue and msqid_ds data structure associated with it. IPC_RMD can only be executed by
                   a process with appropriate privileges or one that has an effective user ID equal to the value
                   of msg_perm.cuid or msg_perm.uid in the msqid_ds data structure associated with msqid.

RETURN VALUE

       Upon  successful  completion,  msgctl()  shall  return  0; otherwise, it shall return −1 and set errno to
       indicate the error.

ERRORS

       The msgctl() function shall fail if:

       EACCES The argument cmd is IPC_STAT and the calling process does not have read  permission;  see  Section
              2.7, XSI Interprocess Communication.

       EINVAL The  value  of  msqid  is not a valid message queue identifier; or the value of cmd is not a valid
              command.

       EPERM  The argument cmd is IPC_RMID or IPC_SET and the effective user ID of the calling  process  is  not
              equal  to  that  of  a  process  with  appropriate  privileges and it is not equal to the value of
              msg_perm.cuid or msg_perm.uid in the data structure associated with msqid.

       EPERM  The argument cmd is IPC_SET, an attempt is being made to increase to the value of msg_qbytes,  and
              the effective user ID of the calling process does not have appropriate privileges.

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       The  POSIX  Realtime  Extension  defines  alternative  interfaces  for  interprocess communication (IPC).
       Application developers who need to use IPC should design their applications so that modules using the IPC
       routines described in Section 2.7, XSI Interprocess Communication can  be  easily  modified  to  use  the
       alternative interfaces.

RATIONALE

       None.

FUTURE DIRECTIONS

       None.

SEE ALSO

       Section   2.7,   XSI   Interprocess  Communication,  Section  2.8,  Realtime,  mq_close(),  mq_getattr(),
       mq_notify(), mq_open(), mq_receive(), mq_send(), mq_setattr(), mq_unlink(), msgget(), msgrcv(), msgsnd()

       The Base Definitions volume of POSIX.1‐2008, Section 3.225, Message Queue, <sys_msg.h>

COPYRIGHT

       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2013 Edition,
       Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open  Group  Base
       Specifications  Issue 7, Copyright (C) 2013 by the Institute of Electrical and Electronics Engineers, Inc
       and The Open Group.  (This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In  the  event
       of  any  discrepancy between this version and the original IEEE and The Open Group Standard, the original
       IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at
       http://www.unix.org/online.html .

       Any typographical or formatting errors that appear in this page are most likely to have  been  introduced
       during   the   conversion  of  the  source  files  to  man  page  format.  To  report  such  errors,  see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .

IEEE/The Open Group                                   2013                                        MSGCTL(3POSIX)