huschi.net

MSGCTL(3P)                 POSIX Programmer's Manual                MSGCTL(3P)

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 Def-
       initions volume of IEEE Std 1003.1-2001, Section 3.224, Message Queue).
       It is unspecified whether this function interoperates with the realtime
       interprocess communication facilities defined in Realtime .
       The msgctl() function shall provide message control operations as spec-
       ified 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
       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 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 inter-
       process communication (IPC). Application developers who need to use IPC
       should design their applications so that modules using the IPC routines
       described in XSI Interprocess Communication can be easily  modified  to
       use the alternative interfaces.
RATIONALE
       None.
FUTURE DIRECTIONS
       None.
SEE ALSO
       XSI  Interprocess  Communication,  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 IEEE Std 1003.1-2001, <sys/msg.h>
COPYRIGHT
       Portions of this text are reprinted and reproduced in  electronic  form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
       Specifications  Issue  6,  Copyright  (C) 2001-2003 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 .

IEEE/The Open Group                  2003                           MSGCTL(3P)