man2/msgget.2

   1 .\" Copyright 1993 Giorgio Ciucci <giorgio@crcc.it>
   2 .\"
   3 .\" Permission is granted to make and distribute verbatim copies of this
   4 .\" manual provided the copyright notice and this permission notice are
   5 .\" preserved on all copies.
   6 .\"
   7 .\" Permission is granted to copy and distribute modified versions of this
   8 .\" manual under the conditions for verbatim copying, provided that the
   9 .\" entire resulting derived work is distributed under the terms of a
  10 .\" permission notice identical to this one.
  11 .\"
  12 .\" Since the Linux kernel and libraries are constantly changing, this
  13 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  14 .\" responsibility for errors or omissions, or for damages resulting from
  15 .\" the use of the information contained herein.  The author(s) may not
  16 .\" have taken the same level of care in the production of this manual,
  17 .\" which is licensed free of charge, as they might when working
  18 .\" professionally.
  19 .\"
  20 .\" Formatted or processed versions of this manual, if unaccompanied by
  21 .\" the source, must acknowledge the copyright and authors of this work.
  22 .\"
  23 .\" Added correction due to Nick Duffek <nsd@bbc.com>, aeb, 960426
  24 .\" Modified Wed Nov  6 04:00:31 1996 by Eric S. Raymond <esr@thyrsus.com>
  25 .\" Modified, 8 Jan 2003, Michael Kerrisk, <mtk16@ext.canterbury.ac.nz>
  26 .\"     Removed EIDRM from errors - that can't happen...
  27 .\" Modified, 27 May 2004, Michael Kerrisk <mtk16@ext.canterbury.ac.nz>
  28 .\"     Added notes on capability requirements
  29 .\"
  30 .TH MSGGET 2 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual"
  31 .SH NAME
  32 msgget \- get a message queue identifier
  33 .SH SYNOPSIS
  34 .nf
  35 .B
  36 #include <sys/types.h>
  37 .B
  38 #include <sys/ipc.h>
  39 .B
  40 #include <sys/msg.h>
  41 .fi
  42 .sp
  43 .BI "int msgget(key_t " key ,
  44 .BI "int " msgflg );
  45 .SH DESCRIPTION
  46 The function returns the message queue identifier associated
  47 with the value of the
  48 .I key
  49 argument.
  50 A new message queue is created if
  51 .I key
  52 has the value
  53 .B IPC_PRIVATE
  54 or
  55 .I key
  56 isn't
  57 .BR IPC_PRIVATE ,
  58 no message queue with the given key
  59 .IR key
  60 exists, and
  61 .B IPC_CREAT
  62 is asserted in
  63 .I msgflg
  64 (i.e.,
  65 .IB msgflg & IPC_CREAT
  66 is nonzero).
  67 The presence in
  68 .I msgflg
  69 of the fields
  70 .B IPC_CREAT
  71 and
  72 .B IPC_EXCL
  73 plays the same role, with respect to the existence
  74 of the message queue, as the presence
  75 of
  76 .B O_CREAT
  77 and
  78 .B O_EXCL
  79 in the mode argument of the
  80 .BR open (2)
  81 system call: i.e. the
  82 .B msgget
  83 function fails if
  84 .I msgflg
  85 asserts both
  86 .B IPC_CREAT
  87 and
  88 .B IPC_EXCL
  89 and a message queue already exists for
  90 .IR key .
  91 .PP
  92 Upon creation, the lower 9 bits of the argument
  93 .I msgflg
  94 define the access permissions of the message queue.
  95 These permission bits have the same format and semantics
  96 as the access permissions parameter in
  97 .BR open (2)
  98 or
  99 .BR creat (2)
 100 system calls.  (The execute permissions are not used.)
 101 .PP
 102 If a new message queue is created,
 103 the system call initializes the system message queue data structure
 104 .B msqid_ds
 105 as follows:
 106 .IP
 107 .B msg_perm.cuid
 108 and
 109 .B msg_perm.uid
 110 are set to the effective user\-ID of the calling process.
 111 .IP
 112 .B msg_perm.cgid
 113 and
 114 .B msg_perm.gid
 115 are set to the effective group\-ID of the calling process.
 116 .IP
 117 The lowest order 9 bits of
 118 .B msg_perm.mode
 119 are set to the lowest order 9 bit of
 120 .IR msgflg .
 121 .IP
 122 .BR msg_qnum ,
 123 .BR msg_lspid ,
 124 .BR msg_lrpid ,
 125 .BR msg_stime
 126 and
 127 .B msg_rtime
 128 are set to 0.
 129 .IP
 130 .B msg_ctime
 131 is set to the current time.
 132 .IP
 133 .B msg_qbytes
 134 is set to the system limit
 135 .BR MSGMNB .
 136 .PP
 137 If the message queue already exists the access permissions are
 138 verified, and a check is made to see if it is marked for
 139 destruction.
 140 .SH "RETURN VALUE"
 141 If successful, the return value will be the message queue identifier (a
 142 nonnegative integer), otherwise
 143 .B \-1
 144 with
 145 .B errno
 146 indicating the error.
 147 .SH ERRORS
 148 On failure,
 149 .B errno
 150 is set to one of the following values:
 151 .TP 11
 152 .B EACCES
 153 A message queue exists for
 154 .IR key ,
 155 but the calling process does not have permission to access the queue,
 156 and does not have the
 157 .BR CAP_IPC_OWNER
 158 capability.
 159 .TP
 160 .B EEXIST
 161 A message queue exists for
 162 .B key
 163 and
 164 .I msgflg
 165 was asserting both
 166 .B IPC_CREAT
 167 and
 168 .BR IPC_EXCL .
 169 .TP
 170 .B ENOENT
 171 No message queue exists for
 172 .I key
 173 and
 174 .I msgflg
 175 wasn't asserting
 176 .BR IPC_CREAT .
 177 .TP
 178 .B ENOMEM
 179 A message queue has to be created but the system has not enough memory for
 180 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 NOTES
 188 .B IPC_PRIVATE
 189 isn't a flag field but a
 190 .B key_t
 191 type.
 192 If this special value is used for
 193 .IR key ,
 194 the system call ignores everything but the lowest order 9 bits of
 195 .I msgflg
 196 and creates a new message queue (on success).
 197 .PP
 198 The following is a system limit on message queue resources affecting a
 199 .B msgget
 200 call:
 201 .TP 11
 202 .B MSGMNI
 203 System wide maximum number of message queues: policy
 204 dependent.
 205 .SH BUGS
 206 The name choice IPC_PRIVATE was perhaps unfortunate, IPC_NEW
 207 would more clearly show its function.
 208 .SH "CONFORMING TO"
 209 SVr4, SVID.
 210 Until version 2.3.20 Linux would return EIDRM for a
 211 .B msgget
 212 on a message queue scheduled for deletion.
 213 .SH "SEE ALSO"
 214 .BR msgctl (2),
 215 .BR msgrcv (2),
 216 .BR msgsnd (2),
 217 .BR ftok (3),
 218 .BR ipc (5),
 219 .BR capabilities (7)