.\" 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 2012-05-31 "Linux" "Linux Programmer's Manual"
+.TH MSGCTL 2 2020-04-11 "Linux" "Linux Programmer's Manual"
.SH NAME
-msgctl \- message control operations
+msgctl \- System V message control operations
.SH SYNOPSIS
.nf
.B #include <sys/types.h>
.B #include <sys/ipc.h>
.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 message queue with identifier
+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:
-.nf
+.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 last change */
+ time_t msg_ctime; /* Creation time/time of last
+ modification via msgctl() */
unsigned long __msg_cbytes; /* Current number of bytes in
queue (nonstandard) */
msgqnum_t msg_qnum; /* Current number of messages
pid_t msg_lspid; /* PID of last msgsnd(2) */
pid_t msg_lrpid; /* PID of last msgrcv(2) */
};
+.EE
.in
-.fi
+.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_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.
+.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.
.PP
The
.I ipc_perm
(the highlighted fields are settable using
.BR IPC_SET ):
.PP
-.nf
.in +4n
+.EX
struct ipc_perm {
key_t __key; /* Key supplied to msgget(2) */
uid_t \fBuid\fP; /* Effective UID of owner */
unsigned short \fBmode\fP; /* Permissions */
unsigned short __seq; /* Sequence number */
};
+.EE
.in
-.fi
+.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
.RI ( msg_perm.cuid )
of the message queue, or the caller must be privileged.
Appropriate privilege (Linux: the
-.B CAP_IPC_RESOURCE
+.B CAP_SYS_RESOURCE
capability) is required to raise the
.I msg_qbytes
value beyond the system parameter
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)"
-Returns information about system-wide message queue limits and
+Return information about system-wide message queue limits and
parameters in the structure pointed to by
.IR buf .
This structure is of type
if the
.B _GNU_SOURCE
feature test macro is defined:
-.nf
+.IP
.in +4n
-
+.EX
struct msginfo {
int msgpool; /* Size in kibibytes of buffer pool
used to hold message data;
/* Maximum number of segments;
unused within kernel */
};
-
+.EE
.in
-.fi
+.IP
The
.IR msgmni ,
.IR msgmax ,
for details.
.TP
.BR MSG_INFO " (Linux-specific)"
-Returns a
+Return a
.I msginfo
structure containing the same information as for
.BR IPC_INFO ,
in all queues on the system.
.TP
.BR MSG_STAT " (Linux-specific)"
-Returns a
+Return a
.I msqid_ds
structure as for
.BR IPC_STAT .
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 ,
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 error, \-1 is returned with
.I errno
indicating the error.
.IR msqid ,
and does not have the
.B CAP_IPC_OWNER
-capability.
+capability in the user namespace that governs its IPC namespace.
.TP
.B EFAULT
The argument
(as found in
.IR msg_perm.uid )
of the message queue,
-and the process is not privileged (Linux: it does not have the
+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
-SVr4, POSIX.1-2001.
+POSIX.1-2001, POSIX.1-2008, SVr4.
.\" SVID does not document the EIDRM error condition.
.SH NOTES
The inclusion of
to include these header files.
.\" Like Linux, the FreeBSD man pages still document
.\" the inclusion of these header files.
-
+.PP
The
.BR IPC_INFO ,
.B MSG_STAT
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 /proc file system
-interface.
-
+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
.BR msgsnd (2),
.BR capabilities (7),
.BR mq_overview (7),
-.BR svipc (7)
+.BR sysvipc (7)
projects / thirdparty / man-pages.git / blobdiff