summaryrefslogtreecommitdiffstats
path: root/man/man2/msgctl.2
diff options
context:
space:
mode:
Diffstat (limited to 'man/man2/msgctl.2')
-rw-r--r--man/man2/msgctl.2424
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)
generated by cgit v1.2.3 (git 2.39.1) at 2024-11-08 13:18:58 +0000