mirror of https://github.com/mkerrisk/man-pages
439 lines
11 KiB
Groff
439 lines
11 KiB
Groff
.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it)
|
|
.\" and Copyright 2004, 2005 Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\"
|
|
.\" %%%LICENSE_START(VERBATIM)
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond <esr@thyrsus.com>
|
|
.\" Modified Sun Feb 18 01:59:29 2001 by Andries E. Brouwer <aeb@cwi.nl>
|
|
.\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\" Added notes on CAP_IPC_OWNER requirement
|
|
.\" Modified, 17 Jun 2004, Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\" Added notes on CAP_SYS_ADMIN requirement for IPC_SET and IPC_RMID
|
|
.\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\" Language and formatting clean-ups
|
|
.\" Added msqid_ds and ipc_perm structure definitions
|
|
.\" 2005-08-02, mtk: Added IPC_INFO, MSG_INFO, MSG_STAT descriptions
|
|
.\" 2018-03-20, dbueso: Added MSG_STAT_ANY description.
|
|
.\"
|
|
.TH MSGCTL 2 2021-03-22 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
msgctl \- System V message control operations
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <sys/msg.h>
|
|
.PP
|
|
.BI "int msgctl(int " msqid ", int " cmd ", struct msqid_ds *" buf );
|
|
.fi
|
|
.SH DESCRIPTION
|
|
.BR msgctl ()
|
|
performs the control operation specified by
|
|
.I cmd
|
|
on the System\ V message queue with identifier
|
|
.IR msqid .
|
|
.PP
|
|
The
|
|
.I msqid_ds
|
|
data structure is defined in \fI<sys/msg.h>\fP as follows:
|
|
.PP
|
|
.in +4n
|
|
.EX
|
|
struct msqid_ds {
|
|
struct ipc_perm msg_perm; /* Ownership and permissions */
|
|
time_t msg_stime; /* Time of last msgsnd(2) */
|
|
time_t msg_rtime; /* Time of last msgrcv(2) */
|
|
time_t msg_ctime; /* Time of creation or last
|
|
modification by msgctl() */
|
|
unsigned long msg_cbytes; /* # of bytes in queue */
|
|
msgqnum_t msg_qnum; /* # number of messages in queue */
|
|
msglen_t msg_qbytes; /* Maximum # of bytes in queue */
|
|
pid_t msg_lspid; /* PID of last msgsnd(2) */
|
|
pid_t msg_lrpid; /* PID of last msgrcv(2) */
|
|
};
|
|
.EE
|
|
.in
|
|
.PP
|
|
The fields of the
|
|
.I msgid_ds
|
|
structure are as follows:
|
|
.TP 11
|
|
.I msg_perm
|
|
This is an
|
|
.I ipc_perm
|
|
structure (see below) that specifies the access permissions on the message
|
|
queue.
|
|
.TP
|
|
.I msg_stime
|
|
Time of the last
|
|
.BR msgsnd (2)
|
|
system call.
|
|
.TP
|
|
.I msg_rtime
|
|
Time of the last
|
|
.BR msgrcv (2)
|
|
system call.
|
|
.TP
|
|
.I msg_ctime
|
|
Time of creation of queue or time of last
|
|
.BR msgctl ()
|
|
.BR IPC_SET
|
|
operation.
|
|
.TP
|
|
.I msg_cbytes
|
|
Number of bytes in all messages currently on the message queue.
|
|
This is a nonstandard Linux extension that is not specified in POSIX.
|
|
.TP
|
|
.I msg_qnum
|
|
Number of messages currently on the message queue.
|
|
.TP
|
|
.I msg_qbytes
|
|
Maximum number of bytes of message text allowed on the message
|
|
queue.
|
|
.TP
|
|
.I msg_lspid
|
|
ID of the process that performed the last
|
|
.BR msgsnd (2)
|
|
system call.
|
|
.TP
|
|
.I msg_lrpid
|
|
ID of the process that performed the last
|
|
.BR msgrcv (2)
|
|
system call.
|
|
.PP
|
|
The
|
|
.I ipc_perm
|
|
structure is defined as follows
|
|
(the highlighted fields are settable using
|
|
.BR IPC_SET ):
|
|
.PP
|
|
.in +4n
|
|
.EX
|
|
struct ipc_perm {
|
|
key_t __key; /* Key supplied to msgget(2) */
|
|
uid_t \fBuid\fP; /* Effective UID of owner */
|
|
gid_t \fBgid\fP; /* Effective GID of owner */
|
|
uid_t cuid; /* Effective UID of creator */
|
|
gid_t cgid; /* Effective GID of creator */
|
|
unsigned short \fBmode\fP; /* Permissions */
|
|
unsigned short __seq; /* Sequence number */
|
|
};
|
|
.EE
|
|
.in
|
|
.PP
|
|
The least significant 9 bits of the
|
|
.I mode
|
|
field of the
|
|
.I ipc_perm
|
|
structure define the access permissions for the message queue.
|
|
The permission bits are as follows:
|
|
.TS
|
|
l l.
|
|
0400 Read by user
|
|
0200 Write by user
|
|
0040 Read by group
|
|
0020 Write by group
|
|
0004 Read by others
|
|
0002 Write by others
|
|
.TE
|
|
.PP
|
|
Bits 0100, 0010, and 0001 (the execute bits) are unused by the system.
|
|
.PP
|
|
Valid values for
|
|
.I cmd
|
|
are:
|
|
.TP
|
|
.B IPC_STAT
|
|
Copy information from the kernel data structure associated with
|
|
.I msqid
|
|
into the
|
|
.I msqid_ds
|
|
structure pointed to by
|
|
.IR buf .
|
|
The caller must have read permission on the message queue.
|
|
.TP
|
|
.B IPC_SET
|
|
Write the values of some members of the
|
|
.I msqid_ds
|
|
structure pointed to by
|
|
.I buf
|
|
to the kernel data structure associated with this message queue,
|
|
updating also its
|
|
.I msg_ctime
|
|
member.
|
|
.IP
|
|
The following members of the structure are updated:
|
|
.IR msg_qbytes ,
|
|
.IR msg_perm.uid ,
|
|
.IR msg_perm.gid ,
|
|
and (the least significant 9 bits of)
|
|
.IR msg_perm.mode .
|
|
.IP
|
|
The effective UID of the calling process must match the owner
|
|
.RI ( msg_perm.uid )
|
|
or creator
|
|
.RI ( msg_perm.cuid )
|
|
of the message queue, or the caller must be privileged.
|
|
Appropriate privilege (Linux: the
|
|
.B CAP_SYS_RESOURCE
|
|
capability) is required to raise the
|
|
.I msg_qbytes
|
|
value beyond the system parameter
|
|
.BR MSGMNB .
|
|
.TP
|
|
.B IPC_RMID
|
|
Immediately remove the message queue,
|
|
awakening all waiting reader and writer processes (with an error
|
|
return and
|
|
.I errno
|
|
set to
|
|
.BR EIDRM ).
|
|
The calling process must have appropriate privileges
|
|
or its effective user ID must be either that of the creator or owner
|
|
of the message queue.
|
|
The third argument to
|
|
.BR msgctl ()
|
|
is ignored in this case.
|
|
.TP
|
|
.BR IPC_INFO " (Linux-specific)"
|
|
Return information about system-wide message queue limits and
|
|
parameters in the structure pointed to by
|
|
.IR buf .
|
|
This structure is of type
|
|
.I msginfo
|
|
(thus, a cast is required),
|
|
defined in
|
|
.I <sys/msg.h>
|
|
if the
|
|
.B _GNU_SOURCE
|
|
feature test macro is defined:
|
|
.IP
|
|
.in +4n
|
|
.EX
|
|
struct msginfo {
|
|
int msgpool; /* Size in kibibytes of buffer pool
|
|
used to hold message data;
|
|
unused within kernel */
|
|
int msgmap; /* Maximum number of entries in message
|
|
map; unused within kernel */
|
|
int msgmax; /* Maximum number of bytes that can be
|
|
written in a single message */
|
|
int msgmnb; /* Maximum number of bytes that can be
|
|
written to queue; used to initialize
|
|
msg_qbytes during queue creation
|
|
(msgget(2)) */
|
|
int msgmni; /* Maximum number of message queues */
|
|
int msgssz; /* Message segment size;
|
|
unused within kernel */
|
|
int msgtql; /* Maximum number of messages on all queues
|
|
in system; unused within kernel */
|
|
unsigned short msgseg;
|
|
/* Maximum number of segments;
|
|
unused within kernel */
|
|
};
|
|
.EE
|
|
.in
|
|
.IP
|
|
The
|
|
.IR msgmni ,
|
|
.IR msgmax ,
|
|
and
|
|
.I msgmnb
|
|
settings can be changed via
|
|
.I /proc
|
|
files of the same name; see
|
|
.BR proc (5)
|
|
for details.
|
|
.TP
|
|
.BR MSG_INFO " (Linux-specific)"
|
|
Return a
|
|
.I msginfo
|
|
structure containing the same information as for
|
|
.BR IPC_INFO ,
|
|
except that the following fields are returned with information
|
|
about system resources consumed by message queues: the
|
|
.I msgpool
|
|
field returns the number of message queues that currently exist
|
|
on the system; the
|
|
.I msgmap
|
|
field returns the total number of messages in all queues
|
|
on the system; and the
|
|
.I msgtql
|
|
field returns the total number of bytes in all messages
|
|
in all queues on the system.
|
|
.TP
|
|
.BR MSG_STAT " (Linux-specific)"
|
|
Return a
|
|
.I msqid_ds
|
|
structure as for
|
|
.BR IPC_STAT .
|
|
However, the
|
|
.I msqid
|
|
argument is not a queue identifier, but instead an index into
|
|
the kernel's internal array that maintains information about
|
|
all message queues on the system.
|
|
.TP
|
|
.BR MSG_STAT_ANY " (Linux-specific, since Linux 4.17)"
|
|
Return a
|
|
.I msqid_ds
|
|
structure as for
|
|
.BR MSG_STAT .
|
|
However,
|
|
.I msg_perm.mode
|
|
is not checked for read access for
|
|
.IR msqid
|
|
meaning that any user can employ this operation (just as any user may read
|
|
.IR /proc/sysvipc/msg
|
|
to obtain the same information).
|
|
.SH RETURN VALUE
|
|
On success,
|
|
.BR IPC_STAT ,
|
|
.BR IPC_SET ,
|
|
and
|
|
.B IPC_RMID
|
|
return 0.
|
|
A successful
|
|
.B IPC_INFO
|
|
or
|
|
.B MSG_INFO
|
|
operation returns the index of the highest used entry in the
|
|
kernel's internal array recording information about all
|
|
message queues.
|
|
(This information can be used with repeated
|
|
.B MSG_STAT
|
|
or
|
|
.B MSG_STAT_ANY
|
|
operations to obtain information about all queues on the system.)
|
|
A successful
|
|
.B MSG_STAT
|
|
or
|
|
.B MSG_STAT_ANY
|
|
operation returns the identifier of the queue whose index was given in
|
|
.IR msqid .
|
|
.PP
|
|
On failure, \-1 is returned and
|
|
.I errno
|
|
is set to indicate the error.
|
|
.SH ERRORS
|
|
.TP
|
|
.B EACCES
|
|
The argument
|
|
.I cmd
|
|
is equal to
|
|
.B IPC_STAT
|
|
or
|
|
.BR MSG_STAT ,
|
|
but the calling process does not have read permission on the message queue
|
|
.IR msqid ,
|
|
and does not have the
|
|
.B CAP_IPC_OWNER
|
|
capability in the user namespace that governs its IPC namespace.
|
|
.TP
|
|
.B EFAULT
|
|
The argument
|
|
.I cmd
|
|
has the value
|
|
.B IPC_SET
|
|
or
|
|
.BR IPC_STAT ,
|
|
but the address pointed to by
|
|
.I buf
|
|
isn't accessible.
|
|
.TP
|
|
.B EIDRM
|
|
The message queue was removed.
|
|
.TP
|
|
.B EINVAL
|
|
Invalid value for
|
|
.I cmd
|
|
or
|
|
.IR msqid .
|
|
Or: for a
|
|
.B MSG_STAT
|
|
operation, the index value specified in
|
|
.I msqid
|
|
referred to an array slot that is currently unused.
|
|
.TP
|
|
.B EPERM
|
|
The argument
|
|
.I cmd
|
|
has the value
|
|
.B IPC_SET
|
|
or
|
|
.BR IPC_RMID ,
|
|
but the effective user ID of the calling process is not the creator
|
|
(as found in
|
|
.IR msg_perm.cuid )
|
|
or the owner
|
|
(as found in
|
|
.IR msg_perm.uid )
|
|
of the message queue,
|
|
and the caller is not privileged (Linux: does not have the
|
|
.B CAP_SYS_ADMIN
|
|
capability).
|
|
.TP
|
|
.B EPERM
|
|
An attempt
|
|
.RB ( IPC_SET )
|
|
was made to increase
|
|
.I msg_qbytes
|
|
beyond the system parameter
|
|
.BR MSGMNB ,
|
|
but the caller is not privileged (Linux: does not have the
|
|
.B CAP_SYS_RESOURCE
|
|
capability).
|
|
.SH CONFORMING TO
|
|
POSIX.1-2001, POSIX.1-2008, SVr4.
|
|
.\" SVID does not document the EIDRM error condition.
|
|
.SH NOTES
|
|
The
|
|
.BR IPC_INFO ,
|
|
.BR MSG_STAT ,
|
|
and
|
|
.B MSG_INFO
|
|
operations are used by the
|
|
.BR ipcs (1)
|
|
program to provide information on allocated resources.
|
|
In the future these may modified or moved to a
|
|
.I /proc
|
|
filesystem interface.
|
|
.PP
|
|
Various fields in the \fIstruct msqid_ds\fP were
|
|
typed as
|
|
.I short
|
|
under Linux 2.2
|
|
and have become
|
|
.I long
|
|
under Linux 2.4.
|
|
To take advantage of this,
|
|
a recompilation under glibc-2.1.91 or later should suffice.
|
|
(The kernel distinguishes old and new calls by an
|
|
.B IPC_64
|
|
flag in
|
|
.IR cmd .)
|
|
.SH SEE ALSO
|
|
.BR msgget (2),
|
|
.BR msgrcv (2),
|
|
.BR msgsnd (2),
|
|
.BR capabilities (7),
|
|
.BR mq_overview (7),
|
|
.BR sysvipc (7)
|