MSGCTL(2)           Linux Programmer's Manual           MSGCTL(2)

NAME
       msgctl - message control operations

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

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

DESCRIPTION
       The  function  performs the control operation specified by
       cmd on the message queue  with  identifier  msqid.   Legal
       values for cmd are:

       IPC_STAT    Copy  info  from the message queue data struc-
                   ture into the structure  pointed  to  by  buf.
                   The  user  must have read access privileges on
                   the message queue.

       IPC_SET     Write  the  values  of  some  members  of  the
                   msqid_ds  structure  pointed  to by buf to the
                   message queue data  structure,  updating  also
                   its msg_ctime member.  Considered members from
                   the user supplied struct msqid_ds  pointed  to
                   by buf are

                        msg_perm.uid
                        msg_perm.gid
                        msg_perm.mode  /* only lowest 9-bits */
                        msg_qbytes

                   The  calling process effective user-ID must be
                   one among super-user, creator or owner of  the
                   message  queue.  Only the super-user can raise
                   the msg_qbytes value beyond the system parame-
                   ter MSGMNB.

       IPC_RMID    Remove  immediately  the message queue and its
                   data structures awakening all  waiting  reader
                   and writer processes (with an error return and
                   errno set  to  EIDRM).   The  calling  process
                   effective    user-ID   must   be   one   among
                   super-user, creator or owner  of  the  message
                   queue.

RETURN VALUE
       If  successful,  the  return value will be 0, otherwise -1
       with errno indicating the error.

ERRORS
       For a failing return, errno will be set to one  among  the
       following values:

       EACCES     The  argument  cmd is equal to IPC_STAT but the
                  calling process has no read access  permissions
                  on the message queue msqid.

       EFAULT     The  argument cmd has value IPC_SET or IPC_STAT
                  but the address pointed to by buf isn't  acces-
                  sible.

       EIDRM      The message queue was removed.

       EINVAL     Invalid value for cmd or msqid.

       EPERM      The  argument cmd has value IPC_SET or IPC_RMID
                  but the calling process effective  user-ID  has
                  insufficient privileges to execute the command.
                  Note this is also the case of a non  super-user
                  process trying to increase the msg_qbytes value
                  beyond the value specified by the system param-
                  eter MSGMNB.

NOTES
       The IPC_INFO, MSG_STAT and MSG_INFO control calls are used
       by the ipcs(8) program to provide information on allocated
       resources.   In the future these can be modified as needed
       or moved to a proc file system interface.

CONFORMING TO
       SVr4, SVID.  SVID dies not document the EIDRM error condi-
       tion.

SEE ALSO
       ipc(5), msgget(2), msgsnd(2), msgrcv(2).

Linux 0.99.13            November 1, 1993                       1