# msgctl

## 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.
    


* * *