summaryrefslogtreecommitdiffstats
path: root/man2/msgctl.2
diff options
context:
space:
mode:
Diffstat (limited to 'man2/msgctl.2')
-rw-r--r--man2/msgctl.2424
1 files changed, 0 insertions, 424 deletions
diff --git a/man2/msgctl.2 b/man2/msgctl.2
deleted file mode 100644
index 27aca82..0000000
--- a/man2/msgctl.2
+++ /dev/null
@@ -1,424 +0,0 @@
-'\" 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-03-03 "Linux man-pages 6.7"
-.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-01 19:18:51 +0000