msgctl(S)                      6 January 1993                      msgctl(S)


 Name

    msgctl - message control operations

 Syntax


    cc ... -lc


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

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


 Description

    The msgctl system call provides a variety of message control operations
    as specified by cmd.  The following cmds are available:

    IPCRMID       Remove the message queue identifier specified by msqid
                   from the system and destroy the message queue and data
                   structure associated with it.  This cmd can only be exe-
                   cuted by a process that has an effective user ID equal to
                   either that of super user, or to the value of
                   msgperm.cuid or msgperm.uid in the data structure asso-
                   ciated with msqid.

    IPCSET        Set the value of the following members of the data struc-
                   ture associated with msqid to the corresponding value
                   found in the structure pointed to by buf:

                      msg_perm.uid
                      msg_perm.gid
                      msg_perm.mode /* only low 9 bits */
                      msg_qbytes


                   This cmd can only be executed by a process that has an
                   effective user ID equal to either that of super user, or
                   to the value of msgperm.cuid or msgperm.uid in the data
                   structure associated with msqid.  Only super user can
                   raise the value of msgqbytes.

    IPCSTAT       Place the current value of each member of the data struc-
                   ture associated with msqid into the structure pointed to
                   by buf.  The contents of this structure are defined in
                   Intro(S).

    The msgctl system call fails if one or more of the following is true:


    [EACCES]       The cmd argument is equal to IPCSTAT and {READ} operation
                   permission is denied to the calling process.

    [EFAULT]       The buf argument points to an illegal address.

    [EINVAL]       1. The msqid argument is not a valid message queue iden-
                   tifier.
                   2. The cmd argument is not a valid command.

    [EPERM]        1. The cmd argument is equal to IPCRMID or IPCSET.  The
                   effective user ID of the calling process is not equal to
                   that of super user, or to the value of msgperm.cuid or
                   msgperm.uid in the data structure associated with msqid.
                   2. The cmd argument is equal to IPCSET, an attempt is
                   being made to increase to the value of msgqbytes, and the
                   effective user ID of the calling process is not equal to
                   that of super user.


 Diagnostics

    Upon successful completion, a value of 0 is returned. Otherwise, a value
    of -1 is returned, and errno is set to indicate the error.

 See also

    Intro(S), msgget(S), msgop(S)

 Standards conformance

    msgctl is conformant with:
    AT&T SVID Issue 2;
    and X/Open Portability Guide, Issue 3, 1989.