diff options
Diffstat (limited to 'man2/msgctl.2')
| -rw-r--r-- | man2/msgctl.2 | 180 |
1 files changed, 180 insertions, 0 deletions
diff --git a/man2/msgctl.2 b/man2/msgctl.2 new file mode 100644 index 000000000..a0dc291c0 --- /dev/null +++ b/man2/msgctl.2 @@ -0,0 +1,180 @@ +.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" 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 <mtk16@ext.canterbury.ac.nz> +.\" Added notes on CAP_IPC_OWNER requirement +.\" Modified, 17 Jun 2004, Michael Kerrisk <mtk16@ext.canterbury.ac.nz> +.\" Added notes on CAP_SYS_ADMIN requirement for IPC_SET and IPC_RMID +.\" +.TH MSGCTL 2 2004-06-17 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +msgctl \- message control operations +.SH SYNOPSIS +.nf +.B +#include <sys/types.h> +.B +#include <sys/ipc.h> +.B +#include <sys/msg.h> +.fi +.sp +.BI "int msgctl(int " msqid , +.BI "int " cmd , +.BI "struct msqid_ds *" buf ); +.SH DESCRIPTION +This function performs the control operation specified by +.I cmd +on the message queue with identifier +.IR msqid . +Legal values for +.I cmd +are: +.TP +.B IPC_STAT +Copy info from the message queue data structure associated with +.I msqid +into the 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 +.B msqid_ds +structure pointed to by +.I buf +to the message queue data structure, updating also its +.B msg_ctime +member. +The following members of the structure can be updated: +.nf +.sp +.ft B + msg_perm.uid + msg_perm.gid + msg_perm.mode \fR/* only lowest 9-bits */\fP + msg_qbytes +.fi +.ft R +.sp +The calling process must have appropriate (probably, root) privileges +or its effective user\-ID must be that of the creator +.RI ( msg_perm.cuid ) +or owner +.RI ( msg_perm.uid ) +of the message queue. +Appropriate privilege (Linux: the +.B CAP_IPC_RESOURCE +capability) is required to raise the +.B msg_qbytes +value beyond the system parameter +.BR MSGMNB . +.TP +.B IPC_RMID +Immediately remove the message queue and its associated data structure, +awakening all waiting reader and writer processes (with an error +return and +.B errno +set to +.BR EIDRM ). +The calling process must have appropriate (probably, root) privileges +or its effective user\-ID must be either that of the creator or owner +of the message queue. +.SH "RETURN VALUE" +On success, the return value will be +.BR 0 , +otherwise +.B \-1 +with +.B errno +indicating the error. +.SH ERRORS +On failure, +.B errno +is set to one of the following: +.TP 11 +.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. +.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 . +.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 process is not privileged (Linux: it does not have the +.B CAP_SYS_ADMIN +capability). +.SH NOTES +Various fields in a \fIstruct msqid_ds\fP were shorts under Linux 2.2 +and have become longs 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 a IPC_64 flag in +.IR cmd .) +.SH "CONFORMING TO" +SVr4, SVID. SVID does not document the EIDRM error condition. +.SH "SEE ALSO" +.BR msgget (2), +.BR msgrcv (2), +.BR msgsnd (2), +.BR ipc (5), +.BR capabilities (7) |