original/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 2014-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
  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 A new message queue is created if
  54 .I key
  55 has the value
  56 .B IPC_PRIVATE
  57 or
  58 .I key
  59 isn't
  60 .BR IPC_PRIVATE ,
  61 no message queue with the given key
  62 .I key
  63 exists, and
  64 .B IPC_CREAT
  65 is specified in
  66 .IR msgflg .
  67 .PP
  68 If
  69 .I msgflg
  70 specifies both
  71 .B IPC_CREAT
  72 and
  73 .B IPC_EXCL
  74 and a message queue already exists for
  75 .IR key ,
  76 then
  77 .BR msgget ()
  78 fails with
  79 .I errno
  80 set to
  81 .BR EEXIST .
  82 (This is analogous to the effect of the combination
  83 .B O_CREAT | O_EXCL
  84 for
  85 .BR open (2).)
  86 .PP
  87 Upon creation, the least significant bits of the argument
  88 .I msgflg
  89 define the permissions of the message queue.
  90 These permission bits have the same format and semantics
  91 as the permissions specified for the
  92 .I mode
  93 argument of
  94 .BR open (2).
  95 (The execute permissions are not used.)
  96 .PP
  97 If a new message queue is created,
  98 then its associated data structure
  99 .I msqid_ds
 100 (see
 101 .BR msgctl (2))
 102 is initialized as follows:
 103 .IP
 104 .I msg_perm.cuid
 105 and
 106 .I msg_perm.uid
 107 are set to the effective user ID of the calling process.
 108 .IP
 109 .I msg_perm.cgid
 110 and
 111 .I msg_perm.gid
 112 are set to the effective group ID of the calling process.
 113 .IP
 114 The least significant 9 bits of
 115 .I msg_perm.mode
 116 are set to the least significant 9 bits of
 117 .IR msgflg .
 118 .IP
 119 .IR msg_qnum ,
 120 .IR msg_lspid ,
 121 .IR msg_lrpid ,
 122 .IR msg_stime ,
 123 and
 124 .I msg_rtime
 125 are set to 0.
 126 .IP
 127 .I msg_ctime
 128 is set to the current time.
 129 .IP
 130 .I msg_qbytes
 131 is set to the system limit
 132 .BR MSGMNB .
 133 .PP
 134 If the message queue already exists the permissions are
 135 verified, and a check is made to see if it is marked for
 136 destruction.
 137 .SH RETURN VALUE
 138 If successful, the return value will be the message queue identifier (a
 139 nonnegative integer), otherwise \-1
 140 with
 141 .I errno
 142 indicating the error.
 143 .SH ERRORS
 144 On failure,
 145 .I errno
 146 is set to one of the following values:
 147 .TP
 148 .B EACCES
 149 A message queue exists for
 150 .IR key ,
 151 but the calling process does not have permission to access the queue,
 152 and does not have the
 153 .B CAP_IPC_OWNER
 154 capability.
 155 .TP
 156 .B EEXIST
 157 .B IPC_CREAT
 158 and
 159 .BR IPC_EXCL
 160 were specified in
 161 .IR msgflg ,
 162 but a message queue already exists for
 163 .IR key .
 164 .TP
 165 .B ENOENT
 166 No message queue exists for
 167 .I key
 168 and
 169 .I msgflg
 170 did not specify
 171 .BR IPC_CREAT .
 172 .TP
 173 .B ENOMEM
 174 A message queue has to be created but the system does not have enough
 175 memory for the new data structure.
 176 .TP
 177 .B ENOSPC
 178 A message queue has to be created but the system limit for the maximum
 179 number of message queues
 180 .RB ( MSGMNI )
 181 would be exceeded.
 182 .SH CONFORMING TO
 183 SVr4, POSIX.1-2001.
 184 .SH NOTES
 185 The inclusion of
 186 .I <sys/types.h>
 187 and
 188 .I <sys/ipc.h>
 189 isn't required on Linux or by any version of POSIX.
 190 However,
 191 some old implementations required the inclusion of these header files,
 192 and the SVID also documented their inclusion.
 193 Applications intended to be portable to such old systems may need
 194 to include these header files.
 195 .\" Like Linux, the FreeBSD man pages still document
 196 .\" the inclusion of these header files.
 197
 198 .B IPC_PRIVATE
 199 isn't a flag field but a
 200 .I key_t
 201 type.
 202 If this special value is used for
 203 .IR key ,
 204 the system call ignores everything but the least significant 9 bits of
 205 .I msgflg
 206 and creates a new message queue (on success).
 207 .PP
 208 The following is a system limit on message queue resources affecting a
 209 .BR msgget ()
 210 call:
 211 .TP
 212 .B MSGMNI
 213 System-wide limit on the number of message queues: policy
 214 dependent
 215 (on Linux, this limit can be read and modified via
 216 .IR /proc/sys/kernel/msgmni ).
 217 .SS Linux notes
 218 Until version 2.3.20, Linux would return
 219 .B EIDRM
 220 for a
 221 .BR msgget ()
 222 on a message queue scheduled for deletion.
 223 .SH BUGS
 224 The name choice
 225 .B IPC_PRIVATE
 226 was perhaps unfortunate,
 227 .B IPC_NEW
 228 would more clearly show its function.
 229 .SH SEE ALSO
 230 .BR msgctl (2),
 231 .BR msgrcv (2),
 232 .BR msgsnd (2),
 233 .BR ftok (3),
 234 .BR capabilities (7),
 235 .BR mq_overview (7),
 236 .BR svipc (7)
 237 .SH COLOPHON
 238 This page is part of release 3.68 of the Linux
 239 .I man-pages
 240 project.
 241 A description of the project,
 242 information about reporting bugs,
 243 and the latest version of this page,
 244 can be found at
 245 \%http://www.kernel.org/doc/man\-pages/.