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  structure
                 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 sup-
                 plied 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 parameter
                 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 accessi-
                ble.

     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 parame-
                ter 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).