man2/msgget.2

   1 .\" Copyright 1993 Giorgio Ciucci <giorgio@crcc.it>
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\" Added correction due to Nick Duffek <nsd@bbc.com>, aeb, 960426
  26 .\" Modified Wed Nov  6 04:00:31 1996 by Eric S. Raymond <esr@thyrsus.com>
  27 .\" Modified, 8 Jan 2003, Michael Kerrisk, <mtk.manpages@gmail.com>
  28 .\"     Removed EIDRM from errors - that can't happen...
  29 .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  30 .\"     Added notes on capability requirements
  31 .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  32 .\"     Language and formatting clean-ups
  33 .\"     Added notes on /proc files
  34 .\"
  35 .TH MSGGET 2 2018-04-30 "Linux" "Linux Programmer's Manual"
  36 .SH NAME
  37 msgget \- get a System V message queue identifier
  38 .SH SYNOPSIS
  39 .nf
  40 .B #include <sys/types.h>
  41 .B #include <sys/ipc.h>
  42 .B #include <sys/msg.h>
  43 .PP
  44 .BI "int msgget(key_t " key ", int " msgflg );
  45 .fi
  46 .SH DESCRIPTION
  47 The
  48 .BR msgget ()
  49 system call returns the System\ V message queue identifier associated
  50 with the value of the
  51 .I key
  52 argument.
  53 It may be used either to obtain the identifier of a previously created
  54 message queue (when
  55 .I msgflg
  56 is zero and
  57 .I key
  58 does not have the value
  59 .BR IPC_PRIVATE ),
  60 or to create a new set.
  61 .PP
  62 A new message queue is created if
  63 .I key
  64 has the value
  65 .B IPC_PRIVATE
  66 or
  67 .I key
  68 isn't
  69 .BR IPC_PRIVATE ,
  70 no message queue with the given key
  71 .I key
  72 exists, and
  73 .B IPC_CREAT
  74 is specified in
  75 .IR msgflg .
  76 .PP
  77 If
  78 .I msgflg
  79 specifies both
  80 .B IPC_CREAT
  81 and
  82 .B IPC_EXCL
  83 and a message queue already exists for
  84 .IR key ,
  85 then
  86 .BR msgget ()
  87 fails with
  88 .I errno
  89 set to
  90 .BR EEXIST .
  91 (This is analogous to the effect of the combination
  92 .B O_CREAT | O_EXCL
  93 for
  94 .BR open (2).)
  95 .PP
  96 Upon creation, the least significant bits of the argument
  97 .I msgflg
  98 define the permissions of the message queue.
  99 These permission bits have the same format and semantics
 100 as the permissions specified for the
 101 .I mode
 102 argument of
 103 .BR open (2).
 104 (The execute permissions are not used.)
 105 .PP
 106 If a new message queue is created,
 107 then its associated data structure
 108 .I msqid_ds
 109 (see
 110 .BR msgctl (2))
 111 is initialized as follows:
 112 .IP
 113 .I msg_perm.cuid
 114 and
 115 .I msg_perm.uid
 116 are set to the effective user ID of the calling process.
 117 .IP
 118 .I msg_perm.cgid
 119 and
 120 .I msg_perm.gid
 121 are set to the effective group ID of the calling process.
 122 .IP
 123 The least significant 9 bits of
 124 .I msg_perm.mode
 125 are set to the least significant 9 bits of
 126 .IR msgflg .
 127 .IP
 128 .IR msg_qnum ,
 129 .IR msg_lspid ,
 130 .IR msg_lrpid ,
 131 .IR msg_stime ,
 132 and
 133 .I msg_rtime
 134 are set to 0.
 135 .IP
 136 .I msg_ctime
 137 is set to the current time.
 138 .IP
 139 .I msg_qbytes
 140 is set to the system limit
 141 .BR MSGMNB .
 142 .PP
 143 If the message queue already exists the permissions are
 144 verified, and a check is made to see if it is marked for
 145 destruction.
 146 .SH RETURN VALUE
 147 If successful, the return value will be the message queue identifier (a
 148 nonnegative integer), otherwise \-1
 149 with
 150 .I errno
 151 indicating the error.
 152 .SH ERRORS
 153 On failure,
 154 .I errno
 155 is set to one of the following values:
 156 .TP
 157 .B EACCES
 158 A message queue exists for
 159 .IR key ,
 160 but the calling process does not have permission to access the queue,
 161 and does not have the
 162 .B CAP_IPC_OWNER
 163 capability in the user namespace that governs its IPC namespace.
 164 .TP
 165 .B EEXIST
 166 .B IPC_CREAT
 167 and
 168 .BR IPC_EXCL
 169 were specified in
 170 .IR msgflg ,
 171 but a message queue already exists for
 172 .IR key .
 173 .TP
 174 .B ENOENT
 175 No message queue exists for
 176 .I key
 177 and
 178 .I msgflg
 179 did not specify
 180 .BR IPC_CREAT .
 181 .TP
 182 .B ENOMEM
 183 A message queue has to be created but the system does not have enough
 184 memory for the new data structure.
 185 .TP
 186 .B ENOSPC
 187 A message queue has to be created but the system limit for the maximum
 188 number of message queues
 189 .RB ( MSGMNI )
 190 would be exceeded.
 191 .SH CONFORMING TO
 192 POSIX.1-2001, POSIX.1-2008, SVr4.
 193 .SH NOTES
 194 The inclusion of
 195 .I <sys/types.h>
 196 and
 197 .I <sys/ipc.h>
 198 isn't required on Linux or by any version of POSIX.
 199 However,
 200 some old implementations required the inclusion of these header files,
 201 and the SVID also documented their inclusion.
 202 Applications intended to be portable to such old systems may need
 203 to include these header files.
 204 .\" Like Linux, the FreeBSD man pages still document
 205 .\" the inclusion of these header files.
 206 .PP
 207 .B IPC_PRIVATE
 208 isn't a flag field but a
 209 .I key_t
 210 type.
 211 If this special value is used for
 212 .IR key ,
 213 the system call ignores everything but the least significant 9 bits of
 214 .I msgflg
 215 and creates a new message queue (on success).
 216 .PP
 217 The following is a system limit on message queue resources affecting a
 218 .BR msgget ()
 219 call:
 220 .TP
 221 .B MSGMNI
 222 System-wide limit on the number of message queues.
 223 Before Linux 3.19,
 224 .\" commit 0050ee059f7fc86b1df2527aaa14ed5dc72f9973
 225 the default value for this limit was calculated using a formula
 226 based on available system memory.
 227 Since Linux 3.19, the default value is 32,000.
 228 On Linux, this limit can be read and modified via
 229 .IR /proc/sys/kernel/msgmni .
 230 .SS Linux notes
 231 Until version 2.3.20, Linux would return
 232 .B EIDRM
 233 for a
 234 .BR msgget ()
 235 on a message queue scheduled for deletion.
 236 .SH BUGS
 237 The name choice
 238 .B IPC_PRIVATE
 239 was perhaps unfortunate,
 240 .B IPC_NEW
 241 would more clearly show its function.
 242 .SH SEE ALSO
 243 .BR msgctl (2),
 244 .BR msgrcv (2),
 245 .BR msgsnd (2),
 246 .BR ftok (3),
 247 .BR capabilities (7),
 248 .BR mq_overview (7),
 249 .BR sysvipc (7)