Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 424 insertions, 0 deletions

diff --git a/man/man2/msgctl.2 b/man/man2/msgctl.2
new file mode 100644
index 0000000..d965269
--- /dev/null
+++ b/man/man2/msgctl.2
@@ -0,0 +1,424 @@
+'\" t
+.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it)
+.\" and Copyright 2004, 2005 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" 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 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+msgctl \- System V message control operations
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <sys/msg.h>
+.P
+.BI "int msgctl(int " msqid ", int " op ", struct msqid_ds *" buf );
+.fi
+.SH DESCRIPTION
+.BR msgctl ()
+performs the control operation specified by
+.I op
+on the System\ V message queue with identifier
+.IR msqid .
+.P
+The
+.I msqid_ds
+data structure is defined in \fI<sys/msg.h>\fP as follows:
+.P
+.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
+.P
+The fields of the
+.I msqid_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 ()
+.B 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.
+.P
+The
+.I ipc_perm
+structure is defined as follows
+(the highlighted fields are settable using
+.BR IPC_SET ):
+.P
+.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
+.P
+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
+.P
+Bits 0100, 0010, and 0001 (the execute bits) are unused by the system.
+.P
+Valid values for
+.I op
+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
+.I msqid
+meaning that any user can employ this operation (just as any user may read
+.I /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 .
+.P
+On failure, \-1 is returned and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EACCES
+The argument
+.I op
+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 op
+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 op
+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 op
+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 STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001, SVr4.
+.\" SVID does not document the EIDRM error condition.
+.P
+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 op .)
+.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.
+.SH SEE ALSO
+.BR msgget (2),
+.BR msgrcv (2),
+.BR msgsnd (2),
+.BR capabilities (7),
+.BR mq_overview (7),
+.BR sysvipc (7)