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 2021-03-22 "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/msg.h>
  41 .PP
  42 .BI "int msgget(key_t " key ", int " msgflg );
  43 .fi
  44 .SH DESCRIPTION
  45 The
  46 .BR msgget ()
  47 system call returns the System\ V message queue identifier associated
  48 with the value of the
  49 .I key
  50 argument.
  51 It may be used either to obtain the identifier of a previously created
  52 message queue (when
  53 .I msgflg
  54 is zero and
  55 .I key
  56 does not have the value
  57 .BR IPC_PRIVATE ),
  58 or to create a new set.
  59 .PP
  60 A new message queue is created if
  61 .I key
  62 has the value
  63 .B IPC_PRIVATE
  64 or
  65 .I key
  66 isn't
  67 .BR IPC_PRIVATE ,
  68 no message queue with the given key
  69 .I key
  70 exists, and
  71 .B IPC_CREAT
  72 is specified in
  73 .IR msgflg .
  74 .PP
  75 If
  76 .I msgflg
  77 specifies both
  78 .B IPC_CREAT
  79 and
  80 .B IPC_EXCL
  81 and a message queue already exists for
  82 .IR key ,
  83 then
  84 .BR msgget ()
  85 fails with
  86 .I errno
  87 set to
  88 .BR EEXIST .
  89 (This is analogous to the effect of the combination
  90 .B O_CREAT | O_EXCL
  91 for
  92 .BR open (2).)
  93 .PP
  94 Upon creation, the least significant bits of the argument
  95 .I msgflg
  96 define the permissions of the message queue.
  97 These permission bits have the same format and semantics
  98 as the permissions specified for the
  99 .I mode
 100 argument of
 101 .BR open (2).
 102 (The execute permissions are not used.)
 103 .PP
 104 If a new message queue is created,
 105 then its associated data structure
 106 .I msqid_ds
 107 (see
 108 .BR msgctl (2))
 109 is initialized as follows:
 110 .IP \(bu 2
 111 .I msg_perm.cuid
 112 and
 113 .I msg_perm.uid
 114 are set to the effective user ID of the calling process.
 115 .IP \(bu
 116 .I msg_perm.cgid
 117 and
 118 .I msg_perm.gid
 119 are set to the effective group ID of the calling process.
 120 .IP \(bu
 121 The least significant 9 bits of
 122 .I msg_perm.mode
 123 are set to the least significant 9 bits of
 124 .IR msgflg .
 125 .IP \(bu
 126 .IR msg_qnum ,
 127 .IR msg_lspid ,
 128 .IR msg_lrpid ,
 129 .IR msg_stime ,
 130 and
 131 .I msg_rtime
 132 are set to 0.
 133 .IP \(bu
 134 .I msg_ctime
 135 is set to the current time.
 136 .IP \(bu
 137 .I msg_qbytes
 138 is set to the system limit
 139 .BR MSGMNB .
 140 .PP
 141 If the message queue already exists the permissions are
 142 verified, and a check is made to see if it is marked for
 143 destruction.
 144 .SH RETURN VALUE
 145 On success,
 146 .BR msgget ()
 147 returns the message queue identifier (a nonnegative integer).
 148 On failure, \-1 is returned, and
 149 .I errno
 150 is set to indicate the error.
 151 .SH ERRORS
 152 .TP
 153 .B EACCES
 154 A message queue exists for
 155 .IR key ,
 156 but the calling process does not have permission to access the queue,
 157 and does not have the
 158 .B CAP_IPC_OWNER
 159 capability in the user namespace that governs its IPC namespace.
 160 .TP
 161 .B EEXIST
 162 .B IPC_CREAT
 163 and
 164 .BR IPC_EXCL
 165 were specified in
 166 .IR msgflg ,
 167 but a message queue already exists for
 168 .IR key .
 169 .TP
 170 .B ENOENT
 171 No message queue exists for
 172 .I key
 173 and
 174 .I msgflg
 175 did not specify
 176 .BR IPC_CREAT .
 177 .TP
 178 .B ENOMEM
 179 A message queue has to be created but the system does not have enough
 180 memory for the new data structure.
 181 .TP
 182 .B ENOSPC
 183 A message queue has to be created but the system limit for the maximum
 184 number of message queues
 185 .RB ( MSGMNI )
 186 would be exceeded.
 187 .SH CONFORMING TO
 188 POSIX.1-2001, POSIX.1-2008, SVr4.
 189 .SH NOTES
 190 .B IPC_PRIVATE
 191 isn't a flag field but a
 192 .I key_t
 193 type.
 194 If this special value is used for
 195 .IR key ,
 196 the system call ignores everything but the least significant 9 bits of
 197 .I msgflg
 198 and creates a new message queue (on success).
 199 .PP
 200 The following is a system limit on message queue resources affecting a
 201 .BR msgget ()
 202 call:
 203 .TP
 204 .B MSGMNI
 205 System-wide limit on the number of message queues.
 206 Before Linux 3.19,
 207 .\" commit 0050ee059f7fc86b1df2527aaa14ed5dc72f9973
 208 the default value for this limit was calculated using a formula
 209 based on available system memory.
 210 Since Linux 3.19, the default value is 32,000.
 211 On Linux, this limit can be read and modified via
 212 .IR /proc/sys/kernel/msgmni .
 213 .SS Linux notes
 214 Until version 2.3.20, Linux would return
 215 .B EIDRM
 216 for a
 217 .BR msgget ()
 218 on a message queue scheduled for deletion.
 219 .SH BUGS
 220 The name choice
 221 .B IPC_PRIVATE
 222 was perhaps unfortunate,
 223 .B IPC_NEW
 224 would more clearly show its function.
 225 .SH SEE ALSO
 226 .BR msgctl (2),
 227 .BR msgrcv (2),
 228 .BR msgsnd (2),
 229 .BR ftok (3),
 230 .BR capabilities (7),
 231 .BR mq_overview (7),
 232 .BR sysvipc (7)