diff options
Diffstat (limited to 'man2/msgctl.2')
| -rw-r--r-- | man2/msgctl.2 | 424 |
1 files changed, 0 insertions, 424 deletions
diff --git a/man2/msgctl.2 b/man2/msgctl.2 deleted file mode 100644 index 926f683a9..000000000 --- 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 (date) "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> -.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 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. -.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 -.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 . -.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 STANDARDS -POSIX.1-2008. -.SH HISTORY -POSIX.1-2001, SVr4. -.\" SVID does not document the EIDRM error condition. -.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 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) |