'\"macro stdmacro
.if n .pH g2.msgctl @(#)msgctl	41.4 of 5/26/91
.\" Copyright 1991 UNIX System Laboratories, Inc.
.\" Copyright 1989, 1990 AT&T
.nr X
.if \nX=0 .ds x} msgctl 2 "" "\&"
.if \nX=1 .ds x} msgctl 2 ""
.if \nX=2 .ds x} msgctl 2 "" "\&"
.if \nX=3 .ds x} msgctl "" "" "\&"
.TH \*(x}
.SH NAME
\f4msgctl\f1 \- message control operations
.SH SYNOPSIS
\f4#include <sys/types.h>\f1
.br
\f4#include <sys/ipc.h>\f1
.br
\f4#include <sys/msg.h>\f1
.PP
.nf
\f4int msgctl(int msqid, int cmd, .../\(** struct msqid_ds \(**buf \(**/);\f1
.fi
.SH DESCRIPTION
\f4msgctl\fP
provides a variety of message control operations as specified by
.IR cmd .
The following
.IR cmd s
are available:
.TP 12
\f4IPC_STAT\f1
Place the current value of each member of the data structure associated with
.I msqid
into the structure pointed to by
.IR buf .
The contents of this structure are defined in
\f4intro\fP(2).
.TP
\f4IPC_SET\f1
Set the value of the following members of the data structure associated with
.I msqid
to the corresponding value found in the structure pointed to by
.IR buf :
.RS 18
.nf
.ft 4
msg_perm.uid
msg_perm.gid
msg_perm.mode /\(** only access permission bits \(**/
msg_qbytes
.ft 1
.fi
.RE
.IP "" 12
This \f2cmd\fP can only be executed by a process that has an effective user
.SM ID
equal to the value of \f4msg_perm.cuid\f1 or \f4msg_perm.uid\f1
in the data structure associated with \f2msqid\fP, or by a process
that has the super-user privilege.
.P
A process with the super-user privilege can raise the value of
\f4msg_qbytes\f1.
.TP
\f4IPC_RMID\f1
Remove the message queue identifier specified by
.I msqid
from the system and destroy the message queue and data structure
associated with it.
This \f2cmd\fP can only be executed by a process that has an effective user
.SM ID
equal to either that of super user, or to the value of
\f4msg_perm.cuid\f1
or 
\f4msg_perm.uid\f1
in the data structure associated with
.IR msqid .
.PP
\f4msgctl\fP
fails if one or more of the following are true:
.TP 15
\f4EACCES\fP
.I cmd
is
\f4IPC_STAT\f1
and
operation permission is denied to the calling process [see
\f4intro\fP(2)].
.TP 15
\f4EFAULT\fP
.I buf
points to an illegal address.
.TP
\f4EINVAL\fP
.I msqid
is not a valid message queue identifier.
.TP
\f4EINVAL\fP
.I cmd
is not a valid command.
.TP
\f4EINVAL\fP
\f2cmd\f1 is \f4IPC_SET\fP and \f4msg_perm.uid\fP or \f4msg_perm.gid\fP
is not valid.
.TP
\f4EOVERFLOW\fP
\f2cmd\f1 is \f4IPC_STAT\fP and \f2uid\f1 or \f2gid\f1 is too large
to be stored in the structure pointed to by \f2buf\f1.
.TP
\f4EPERM\fP
\f2cmd\fP is \f4IPC_RMID\f1 or \f4IPC_SET\f1,
the effective user
.SM ID
of the calling process is not equal to
the value of \f4msg_perm.cuid\f1 or \f4msg_perm.uid\f1
in the data structure associated with
\f2msqid\fP and the process does not have the super-user privilege.
.TP
\f4EPERM\fP
\f2cmd\fP is \f4IPC_SET\f1, an attempt is being made to increase to
the value of \f4msg_qbytes\f1, and the calling process does not have
the super-user privilege.
.SH SEE ALSO
\f4intro\fP(2), \f4msgget\fP(2), \f4msgop\fP(2).
.SH "DIAGNOSTICS"
Upon successful completion, a value of 0 is returned. Otherwise, a
value of \-1 is returned and
\f4errno\fP
is set to indicate the error.
.\"	@(#)msgctl.2	6.2 of 9/6/83
.Ee