summaryrefslogtreecommitdiffstats
path: root/man2/msgget.2
diff options
context:
space:
mode:
Diffstat (limited to 'man2/msgget.2')
-rw-r--r--man2/msgget.2217
1 files changed, 217 insertions, 0 deletions
diff --git a/man2/msgget.2 b/man2/msgget.2
new file mode 100644
index 0000000..0774f49
--- /dev/null
+++ b/man2/msgget.2
@@ -0,0 +1,217 @@
+.\" Copyright 1993 Giorgio Ciucci <giorgio@crcc.it>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" Added correction due to Nick Duffek <nsd@bbc.com>, aeb, 960426
+.\" Modified Wed Nov 6 04:00:31 1996 by Eric S. Raymond <esr@thyrsus.com>
+.\" Modified, 8 Jan 2003, Michael Kerrisk, <mtk.manpages@gmail.com>
+.\" Removed EIDRM from errors - that can't happen...
+.\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
+.\" Added notes on capability requirements
+.\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
+.\" Language and formatting clean-ups
+.\" Added notes on /proc files
+.\"
+.TH msgget 2 2023-03-30 "Linux man-pages 6.05.01"
+.SH NAME
+msgget \- get a System V message queue identifier
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <sys/msg.h>
+.PP
+.BI "int msgget(key_t " key ", int " msgflg );
+.fi
+.SH DESCRIPTION
+The
+.BR msgget ()
+system call returns the System\ V message queue identifier associated
+with the value of the
+.I key
+argument.
+It may be used either to obtain the identifier of a previously created
+message queue (when
+.I msgflg
+is zero and
+.I key
+does not have the value
+.BR IPC_PRIVATE ),
+or to create a new set.
+.PP
+A new message queue is created if
+.I key
+has the value
+.B IPC_PRIVATE
+or
+.I key
+isn't
+.BR IPC_PRIVATE ,
+no message queue with the given key
+.I key
+exists, and
+.B IPC_CREAT
+is specified in
+.IR msgflg .
+.PP
+If
+.I msgflg
+specifies both
+.B IPC_CREAT
+and
+.B IPC_EXCL
+and a message queue already exists for
+.IR key ,
+then
+.BR msgget ()
+fails with
+.I errno
+set to
+.BR EEXIST .
+(This is analogous to the effect of the combination
+.B O_CREAT | O_EXCL
+for
+.BR open (2).)
+.PP
+Upon creation, the least significant bits of the argument
+.I msgflg
+define the permissions of the message queue.
+These permission bits have the same format and semantics
+as the permissions specified for the
+.I mode
+argument of
+.BR open (2).
+(The execute permissions are not used.)
+.PP
+If a new message queue is created,
+then its associated data structure
+.I msqid_ds
+(see
+.BR msgctl (2))
+is initialized as follows:
+.IP \[bu] 3
+.I msg_perm.cuid
+and
+.I msg_perm.uid
+are set to the effective user ID of the calling process.
+.IP \[bu]
+.I msg_perm.cgid
+and
+.I msg_perm.gid
+are set to the effective group ID of the calling process.
+.IP \[bu]
+The least significant 9 bits of
+.I msg_perm.mode
+are set to the least significant 9 bits of
+.IR msgflg .
+.IP \[bu]
+.IR msg_qnum ,
+.IR msg_lspid ,
+.IR msg_lrpid ,
+.IR msg_stime ,
+and
+.I msg_rtime
+are set to 0.
+.IP \[bu]
+.I msg_ctime
+is set to the current time.
+.IP \[bu]
+.I msg_qbytes
+is set to the system limit
+.BR MSGMNB .
+.PP
+If the message queue already exists the permissions are
+verified, and a check is made to see if it is marked for
+destruction.
+.SH RETURN VALUE
+On success,
+.BR msgget ()
+returns the message queue identifier (a nonnegative integer).
+On failure, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EACCES
+A message queue exists for
+.IR key ,
+but the calling process does not have permission to access the queue,
+and does not have the
+.B CAP_IPC_OWNER
+capability in the user namespace that governs its IPC namespace.
+.TP
+.B EEXIST
+.B IPC_CREAT
+and
+.B IPC_EXCL
+were specified in
+.IR msgflg ,
+but a message queue already exists for
+.IR key .
+.TP
+.B ENOENT
+No message queue exists for
+.I key
+and
+.I msgflg
+did not specify
+.BR IPC_CREAT .
+.TP
+.B ENOMEM
+A message queue has to be created but the system does not have enough
+memory for the new data structure.
+.TP
+.B ENOSPC
+A message queue has to be created but the system limit for the maximum
+number of message queues
+.RB ( MSGMNI )
+would be exceeded.
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001, SVr4.
+.SS Linux
+Until Linux 2.3.20, Linux would return
+.B EIDRM
+for a
+.BR msgget ()
+on a message queue scheduled for deletion.
+.SH NOTES
+.B IPC_PRIVATE
+isn't a flag field but a
+.I key_t
+type.
+If this special value is used for
+.IR key ,
+the system call ignores everything but the least significant 9 bits of
+.I msgflg
+and creates a new message queue (on success).
+.PP
+The following is a system limit on message queue resources affecting a
+.BR msgget ()
+call:
+.TP
+.B MSGMNI
+System-wide limit on the number of message queues.
+Before Linux 3.19,
+.\" commit 0050ee059f7fc86b1df2527aaa14ed5dc72f9973
+the default value for this limit was calculated using a formula
+based on available system memory.
+Since Linux 3.19, the default value is 32,000.
+On Linux, this limit can be read and modified via
+.IR /proc/sys/kernel/msgmni .
+.SH BUGS
+The name choice
+.B IPC_PRIVATE
+was perhaps unfortunate,
+.B IPC_NEW
+would more clearly show its function.
+.SH SEE ALSO
+.BR msgctl (2),
+.BR msgrcv (2),
+.BR msgsnd (2),
+.BR ftok (3),
+.BR capabilities (7),
+.BR mq_overview (7),
+.BR sysvipc (7)