2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
2007-06-20 22:33:04 +00:00
|
|
|
.TH "MSGCTL" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" msgctl
|
2007-09-20 06:03:25 +00:00
|
|
|
.SH 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.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
|
|
|
msgctl \- XSI message control operations
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.LP
|
|
|
|
\fB#include <sys/msg.h>
|
|
|
|
.br
|
|
|
|
.sp
|
|
|
|
int msgctl(int\fP \fImsqid\fP\fB, int\fP \fIcmd\fP\fB, struct msqid_ds
|
|
|
|
*\fP\fIbuf\fP\fB); \fP
|
|
|
|
\fB
|
|
|
|
.br
|
|
|
|
\fP
|
|
|
|
.SH DESCRIPTION
|
|
|
|
.LP
|
|
|
|
The \fImsgctl\fP() function operates on XSI message queues (see the
|
|
|
|
Base Definitions volume of IEEE\ Std\ 1003.1-2001,
|
|
|
|
Section 3.224, Message Queue). It is unspecified whether this function
|
|
|
|
interoperates with the realtime interprocess communication facilities
|
|
|
|
defined in \fIRealtime\fP .
|
|
|
|
.LP
|
|
|
|
The \fImsgctl\fP() function shall provide message control operations
|
|
|
|
as specified by \fIcmd\fP. The following values for
|
|
|
|
\fIcmd\fP, and the message control operations they specify, are:
|
|
|
|
.TP 7
|
|
|
|
IPC_STAT
|
|
|
|
Place the current value of each member of the \fBmsqid_ds\fP data
|
|
|
|
structure associated with \fImsqid\fP into the structure
|
|
|
|
pointed to by \fIbuf\fP. The contents of this structure are defined
|
|
|
|
in \fI<sys/msg.h>\fP.
|
|
|
|
.TP 7
|
|
|
|
IPC_SET
|
|
|
|
Set the value of the following members of the \fBmsqid_ds\fP data
|
|
|
|
structure associated with \fImsqid\fP to the corresponding
|
|
|
|
value found in the structure pointed to by \fIbuf\fP:
|
|
|
|
.sp
|
|
|
|
.RS
|
|
|
|
.nf
|
|
|
|
|
|
|
|
\fBmsg_perm.uid
|
|
|
|
msg_perm.gid
|
|
|
|
msg_perm.mode
|
|
|
|
msg_qbytes
|
|
|
|
\fP
|
|
|
|
.fi
|
|
|
|
.RE
|
|
|
|
.LP
|
|
|
|
IPC_SET can only be executed by a process with appropriate privileges
|
|
|
|
or that has an effective user ID equal to the value of
|
|
|
|
\fBmsg_perm.cuid\fP or \fBmsg_perm.uid\fP in the \fBmsqid_ds\fP data
|
|
|
|
structure associated with \fImsqid\fP. Only a process with
|
|
|
|
appropriate privileges can raise the value of \fBmsg_qbytes\fP.
|
|
|
|
.TP 7
|
|
|
|
IPC_RMID
|
|
|
|
Remove the message queue identifier specified by \fImsqid\fP from
|
|
|
|
the system and destroy the message queue and \fBmsqid_ds\fP
|
|
|
|
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 \fBmsg_perm.cuid\fP or \fBmsg_perm.uid\fP
|
|
|
|
in the \fBmsqid_ds\fP data structure
|
|
|
|
associated with \fImsqid\fP.
|
|
|
|
.sp
|
|
|
|
.SH RETURN VALUE
|
|
|
|
.LP
|
|
|
|
Upon successful completion, \fImsgctl\fP() shall return 0; otherwise,
|
|
|
|
it shall return -1 and set \fIerrno\fP to indicate the
|
|
|
|
error.
|
|
|
|
.SH ERRORS
|
|
|
|
.LP
|
|
|
|
The \fImsgctl\fP() function shall fail if:
|
|
|
|
.TP 7
|
|
|
|
.B EACCES
|
|
|
|
The argument \fIcmd\fP is IPC_STAT and the calling process does not
|
|
|
|
have read permission; see \fIXSI Interprocess Communication\fP .
|
|
|
|
.TP 7
|
|
|
|
.B EINVAL
|
|
|
|
The value of \fImsqid\fP is not a valid message queue identifier;
|
|
|
|
or the value of \fIcmd\fP is not a valid command.
|
|
|
|
.TP 7
|
|
|
|
.B EPERM
|
|
|
|
The argument \fIcmd\fP 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 \fBmsg_perm.cuid\fP or \fBmsg_perm.uid\fP in the data
|
|
|
|
structure associated with \fImsqid\fP.
|
|
|
|
.TP 7
|
|
|
|
.B EPERM
|
|
|
|
The argument \fIcmd\fP is IPC_SET, an attempt is being made to increase
|
|
|
|
to the value of \fBmsg_qbytes\fP, and the effective
|
|
|
|
user ID of the calling process does not have appropriate privileges.
|
|
|
|
.sp
|
|
|
|
.LP
|
|
|
|
\fIThe following sections are informative.\fP
|
|
|
|
.SH EXAMPLES
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH APPLICATION USAGE
|
|
|
|
.LP
|
|
|
|
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 \fIXSI Interprocess Communication\fP
|
|
|
|
can be easily modified to use the alternative
|
|
|
|
interfaces.
|
|
|
|
.SH RATIONALE
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH FUTURE DIRECTIONS
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH SEE ALSO
|
|
|
|
.LP
|
|
|
|
\fIXSI Interprocess Communication\fP , \fIRealtime\fP , \fImq_close\fP()
|
2007-09-20 06:11:55 +00:00
|
|
|
, \fImq_getattr\fP(), \fImq_notify\fP(), \fImq_open\fP(), \fImq_receive\fP()
|
|
|
|
, \fImq_send\fP(), \fImq_setattr\fP(), \fImq_unlink\fP(), \fImsgget\fP()
|
2007-09-20 06:12:53 +00:00
|
|
|
, \fImsgrcv\fP(),
|
2007-09-20 06:11:55 +00:00
|
|
|
\fImsgsnd\fP(), the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
|
2004-11-03 13:51:07 +00:00
|
|
|
\fI<sys/msg.h>\fP
|
|
|
|
.SH COPYRIGHT
|
|
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
|
|
event of any discrepancy between this version and the original IEEE and
|
|
|
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
|
|
is the referee document. The original Standard can be obtained online at
|
|
|
|
http://www.opengroup.org/unix/online.html .
|