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 2012-05-31 "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 A message queue exists for
 158 .I key
 159 and
 160 .I msgflg
 161 specified both
 162 .B IPC_CREAT
 163 and
 164 .BR IPC_EXCL .
 165 .TP
 166 .B ENOENT
 167 No message queue exists for
 168 .I key
 169 and
 170 .I msgflg
 171 did not specify
 172 .BR IPC_CREAT .
 173 .TP
 174 .B ENOMEM
 175 A message queue has to be created but the system does not have enough
 176 memory for the new data structure.
 177 .TP
 178 .B ENOSPC
 179 A message queue has to be created but the system limit for the maximum
 180 number of message queues
 181 .RB ( MSGMNI )
 182 would be exceeded.
 183 .SH CONFORMING TO
 184 SVr4, POSIX.1-2001.
 185 .SH NOTES
 186 The inclusion of
 187 .I <sys/types.h>
 188 and
 189 .I <sys/ipc.h>
 190 isn't required on Linux or by any version of POSIX.
 191 However,
 192 some old implementations required the inclusion of these header files,
 193 and the SVID also documented their inclusion.
 194 Applications intended to be portable to such old systems may need
 195 to include these header files.
 196 .\" Like Linux, the FreeBSD man pages still document
 197 .\" the inclusion of these header files.
 198
 199 .B IPC_PRIVATE
 200 isn't a flag field but a
 201 .I key_t
 202 type.
 203 If this special value is used for
 204 .IR key ,
 205 the system call ignores everything but the least significant 9 bits of
 206 .I msgflg
 207 and creates a new message queue (on success).
 208 .PP
 209 The following is a system limit on message queue resources affecting a
 210 .BR msgget ()
 211 call:
 212 .TP
 213 .B MSGMNI
 214 System wide maximum number of message queues: policy
 215 dependent
 216 (on Linux, this limit can be read and modified via
 217 .IR /proc/sys/kernel/msgmni ).
 218 .SS Linux notes
 219 Until version 2.3.20 Linux would return
 220 .B EIDRM
 221 for a
 222 .BR msgget ()
 223 on a message queue scheduled for deletion.
 224 .SH BUGS
 225 The name choice
 226 .B IPC_PRIVATE
 227 was perhaps unfortunate,
 228 .B IPC_NEW
 229 would more clearly show its function.
 230 .SH SEE ALSO
 231 .BR msgctl (2),
 232 .BR msgrcv (2),
 233 .BR msgsnd (2),
 234 .BR ftok (3),
 235 .BR capabilities (7),
 236 .BR mq_overview (7),
 237 .BR svipc (7)
 238 .SH COLOPHON
 239 This page is part of release 3.64 of the Linux
 240 .I man-pages
 241 project.
 242 A description of the project,
 243 and information about reporting bugs,
 244 can be found at
 245 \%http://www.kernel.org/doc/man\-pages/.