man2/msgget.2

   1 .\" Copyright 1993 Giorgio Ciucci <giorgio@crcc.it>
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" Added correction due to Nick Duffek <nsd@bbc.com>, aeb, 960426
   6 .\" Modified Wed Nov  6 04:00:31 1996 by Eric S. Raymond <esr@thyrsus.com>
   7 .\" Modified, 8 Jan 2003, Michael Kerrisk, <mtk.manpages@gmail.com>
   8 .\"     Removed EIDRM from errors - that can't happen...
   9 .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  10 .\"     Added notes on capability requirements
  11 .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  12 .\"     Language and formatting clean-ups
  13 .\"     Added notes on /proc files
  14 .\"
  15 .TH msgget 2 (date) "Linux man-pages (unreleased)"
  16 .SH NAME
  17 msgget \- get a System V message queue identifier
  18 .SH LIBRARY
  19 Standard C library
  20 .RI ( libc ", " \-lc )
  21 .SH SYNOPSIS
  22 .nf
  23 .B #include <sys/msg.h>
  24 .P
  25 .BI "int msgget(key_t " key ", int " msgflg );
  26 .fi
  27 .SH DESCRIPTION
  28 The
  29 .BR msgget ()
  30 system call returns the System\ V message queue identifier associated
  31 with the value of the
  32 .I key
  33 argument.
  34 It may be used either to obtain the identifier of a previously created
  35 message queue (when
  36 .I msgflg
  37 is zero and
  38 .I key
  39 does not have the value
  40 .BR IPC_PRIVATE ),
  41 or to create a new set.
  42 .P
  43 A new message queue is created if
  44 .I key
  45 has the value
  46 .B IPC_PRIVATE
  47 or
  48 .I key
  49 isn't
  50 .BR IPC_PRIVATE ,
  51 no message queue with the given key
  52 .I key
  53 exists, and
  54 .B IPC_CREAT
  55 is specified in
  56 .IR msgflg .
  57 .P
  58 If
  59 .I msgflg
  60 specifies both
  61 .B IPC_CREAT
  62 and
  63 .B IPC_EXCL
  64 and a message queue already exists for
  65 .IR key ,
  66 then
  67 .BR msgget ()
  68 fails with
  69 .I errno
  70 set to
  71 .BR EEXIST .
  72 (This is analogous to the effect of the combination
  73 .B O_CREAT | O_EXCL
  74 for
  75 .BR open (2).)
  76 .P
  77 Upon creation, the least significant bits of the argument
  78 .I msgflg
  79 define the permissions of the message queue.
  80 These permission bits have the same format and semantics
  81 as the permissions specified for the
  82 .I mode
  83 argument of
  84 .BR open (2).
  85 (The execute permissions are not used.)
  86 .P
  87 If a new message queue is created,
  88 then its associated data structure
  89 .I msqid_ds
  90 (see
  91 .BR msgctl (2))
  92 is initialized as follows:
  93 .IP \[bu] 3
  94 .I msg_perm.cuid
  95 and
  96 .I msg_perm.uid
  97 are set to the effective user ID of the calling process.
  98 .IP \[bu]
  99 .I msg_perm.cgid
 100 and
 101 .I msg_perm.gid
 102 are set to the effective group ID of the calling process.
 103 .IP \[bu]
 104 The least significant 9 bits of
 105 .I msg_perm.mode
 106 are set to the least significant 9 bits of
 107 .IR msgflg .
 108 .IP \[bu]
 109 .IR msg_qnum ,
 110 .IR msg_lspid ,
 111 .IR msg_lrpid ,
 112 .IR msg_stime ,
 113 and
 114 .I msg_rtime
 115 are set to 0.
 116 .IP \[bu]
 117 .I msg_ctime
 118 is set to the current time.
 119 .IP \[bu]
 120 .I msg_qbytes
 121 is set to the system limit
 122 .BR MSGMNB .
 123 .P
 124 If the message queue already exists the permissions are
 125 verified, and a check is made to see if it is marked for
 126 destruction.
 127 .SH RETURN VALUE
 128 On success,
 129 .BR msgget ()
 130 returns the message queue identifier (a nonnegative integer).
 131 On failure, \-1 is returned, and
 132 .I errno
 133 is set to indicate the error.
 134 .SH ERRORS
 135 .TP
 136 .B EACCES
 137 A message queue exists for
 138 .IR key ,
 139 but the calling process does not have permission to access the queue,
 140 and does not have the
 141 .B CAP_IPC_OWNER
 142 capability in the user namespace that governs its IPC namespace.
 143 .TP
 144 .B EEXIST
 145 .B IPC_CREAT
 146 and
 147 .B IPC_EXCL
 148 were specified in
 149 .IR msgflg ,
 150 but a message queue already exists for
 151 .IR key .
 152 .TP
 153 .B ENOENT
 154 No message queue exists for
 155 .I key
 156 and
 157 .I msgflg
 158 did not specify
 159 .BR IPC_CREAT .
 160 .TP
 161 .B ENOMEM
 162 A message queue has to be created but the system does not have enough
 163 memory for the new data structure.
 164 .TP
 165 .B ENOSPC
 166 A message queue has to be created but the system limit for the maximum
 167 number of message queues
 168 .RB ( MSGMNI )
 169 would be exceeded.
 170 .SH STANDARDS
 171 POSIX.1-2008.
 172 .SH HISTORY
 173 POSIX.1-2001, SVr4.
 174 .SS Linux
 175 Until Linux 2.3.20, Linux would return
 176 .B EIDRM
 177 for a
 178 .BR msgget ()
 179 on a message queue scheduled for deletion.
 180 .SH NOTES
 181 .B IPC_PRIVATE
 182 isn't a flag field but a
 183 .I key_t
 184 type.
 185 If this special value is used for
 186 .IR key ,
 187 the system call ignores everything but the least significant 9 bits of
 188 .I msgflg
 189 and creates a new message queue (on success).
 190 .P
 191 The following is a system limit on message queue resources affecting a
 192 .BR msgget ()
 193 call:
 194 .TP
 195 .B MSGMNI
 196 System-wide limit on the number of message queues.
 197 Before Linux 3.19,
 198 .\" commit 0050ee059f7fc86b1df2527aaa14ed5dc72f9973
 199 the default value for this limit was calculated using a formula
 200 based on available system memory.
 201 Since Linux 3.19, the default value is 32,000.
 202 On Linux, this limit can be read and modified via
 203 .IR /proc/sys/kernel/msgmni .
 204 .SH BUGS
 205 The name choice
 206 .B IPC_PRIVATE
 207 was perhaps unfortunate,
 208 .B IPC_NEW
 209 would more clearly show its function.
 210 .SH SEE ALSO
 211 .BR msgctl (2),
 212 .BR msgrcv (2),
 213 .BR msgsnd (2),
 214 .BR ftok (3),
 215 .BR capabilities (7),
 216 .BR mq_overview (7),
 217 .BR sysvipc (7)