plucky (3) msgctl.3posix.gz

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‐2017,
       Section 3.226, 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‐2017, Section 3.226, Message Queue, <sys_msg.h>

COPYRIGHT

       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard
       for  Information  Technology  --  Portable  Operating  System  Interface  (POSIX),  The  Open  Group Base
       Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical  and  Electronics
       Engineers, Inc and The Open Group.  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.opengroup.org/unix/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 .