man2/semget.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 .\" Modified Tue Oct 22 17:54:56 1996 by Eric S. Raymond <esr@thyrsus.com>
  26 .\" Modified 1 Jan 2002, Martin Schulze <joey@infodrom.org>
  27 .\" Modified 4 Jan 2002, Michael Kerrisk <mtk.manpages@gmail.com>
  28 .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  29 .\"     Added notes on capability requirements
  30 .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  31 .\"     Language and formatting clean-ups
  32 .\"     Added notes on /proc files
  33 .\"     Rewrote BUGS note about semget()'s failure to initialize
  34 .\"             semaphore values
  35 .\"
  36 .TH SEMGET 2 2019-08-02 "Linux" "Linux Programmer's Manual"
  37 .SH NAME
  38 semget \- get a System V semaphore set identifier
  39 .SH SYNOPSIS
  40 .nf
  41 .B #include <sys/types.h>
  42 .B #include <sys/ipc.h>
  43 .B #include <sys/sem.h>
  44 .fi
  45 .PP
  46 .BI "int semget(key_t " key ,
  47 .BI "int " nsems ,
  48 .BI "int " semflg );
  49 .SH DESCRIPTION
  50 The
  51 .BR semget ()
  52 system call returns the System\ V semaphore set identifier
  53 associated with the argument
  54 .IR key .
  55 It may be used either to obtain the identifier of a previously created
  56 semaphore set (when
  57 .I semflg
  58 is zero and
  59 .I key
  60 does not have the value
  61 .BR IPC_PRIVATE ),
  62 or to create a new set.
  63 .PP
  64 A new set of
  65 .I nsems
  66 semaphores is created if
  67 .I key
  68 has the value
  69 .B IPC_PRIVATE
  70 or if no existing semaphore set is associated with
  71 .I key
  72 and
  73 .B IPC_CREAT
  74 is specified in
  75 .IR semflg .
  76 .PP
  77 If
  78 .I semflg
  79 specifies both
  80 .B IPC_CREAT
  81 and
  82 .B IPC_EXCL
  83 and a semaphore set already exists for
  84 .IR key ,
  85 then
  86 .BR semget ()
  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 9 bits of the argument
  97 .I semflg
  98 define the permissions (for owner, group and others)
  99 for the semaphore set.
 100 These bits have the same format, and the same
 101 meaning, as the
 102 .I mode
 103 argument of
 104 .BR open (2)
 105 (though the execute permissions are
 106 not meaningful for semaphores, and write permissions mean permission
 107 to alter semaphore values).
 108 .PP
 109 When creating a new semaphore set,
 110 .BR semget ()
 111 initializes the set's associated data structure,
 112 .I semid_ds
 113 (see
 114 .BR semctl (2)),
 115 as follows:
 116 .IP
 117 .I sem_perm.cuid
 118 and
 119 .I sem_perm.uid
 120 are set to the effective user ID of the calling process.
 121 .IP
 122 .I sem_perm.cgid
 123 and
 124 .I sem_perm.gid
 125 are set to the effective group ID of the calling process.
 126 .IP
 127 The least significant 9 bits of
 128 .I sem_perm.mode
 129 are set to the least significant 9 bits of
 130 .IR semflg .
 131 .IP
 132 .I sem_nsems
 133 is set to the value of
 134 .IR nsems .
 135 .IP
 136 .I sem_otime
 137 is set to 0.
 138 .IP
 139 .I sem_ctime
 140 is set to the current time.
 141 .PP
 142 The argument
 143 .I nsems
 144 can be 0
 145 (a don't care)
 146 when a semaphore set is not being created.
 147 Otherwise,
 148 .I nsems
 149 must be greater than 0
 150 and less than or equal to the maximum number of semaphores per semaphore set
 151 .RB ( SEMMSL ).
 152 .PP
 153 If the semaphore set already exists, the permissions are
 154 verified.
 155 .\" and a check is made to see if it is marked for destruction.
 156 .SH RETURN VALUE
 157 If successful, the return value will be the semaphore set identifier
 158 (a nonnegative integer), otherwise, \-1
 159 is returned, with
 160 .I errno
 161 indicating the error.
 162 .SH ERRORS
 163 On failure,
 164 .I errno
 165 will be set to one of the following:
 166 .TP
 167 .B EACCES
 168 A semaphore set exists for
 169 .IR key ,
 170 but the calling process does not have permission to access the set,
 171 and does not have the
 172 .B CAP_IPC_OWNER
 173 capability in the user namespace that governs its IPC namespace.
 174 .TP
 175 .B EEXIST
 176 .B IPC_CREAT
 177 and
 178 .BR IPC_EXCL
 179 were specified in
 180 .IR semflg ,
 181 but a semaphore set already exists for
 182 .IR key .
 183 .\" .TP
 184 .\" .B EIDRM
 185 .\" The semaphore set is marked to be deleted.
 186 .TP
 187 .B EINVAL
 188 .I nsems
 189 is less than 0 or greater than the limit on the number
 190 of semaphores per semaphore set
 191 .RB ( SEMMSL ).
 192 .TP
 193 .B EINVAL
 194 A semaphore set corresponding to
 195 .I key
 196 already exists, but
 197 .I nsems
 198 is larger than the number of semaphores in that set.
 199 .TP
 200 .B ENOENT
 201 No semaphore set exists for
 202 .I key
 203 and
 204 .I semflg
 205 did not specify
 206 .BR IPC_CREAT .
 207 .TP
 208 .B ENOMEM
 209 A semaphore set has to be created but the system does not have
 210 enough memory for the new data structure.
 211 .TP
 212 .B ENOSPC
 213 A semaphore set has to be created but the system limit for the maximum
 214 number of semaphore sets
 215 .RB ( SEMMNI ),
 216 or the system wide maximum number of semaphores
 217 .RB ( SEMMNS ),
 218 would be exceeded.
 219 .SH CONFORMING TO
 220 SVr4, POSIX.1-2001.
 221 .\" SVr4 documents additional error conditions EFBIG, E2BIG, EAGAIN,
 222 .\" ERANGE, EFAULT.
 223 .SH NOTES
 224 The inclusion of
 225 .I <sys/types.h>
 226 and
 227 .I <sys/ipc.h>
 228 isn't required on Linux or by any version of POSIX.
 229 However,
 230 some old implementations required the inclusion of these header files,
 231 and the SVID also documented their inclusion.
 232 Applications intended to be portable to such old systems may need
 233 to include these header files.
 234 .\" Like Linux, the FreeBSD man pages still document
 235 .\" the inclusion of these header files.
 236 .PP
 237 .B IPC_PRIVATE
 238 isn't a flag field but a
 239 .I key_t
 240 type.
 241 If this special value is used for
 242 .IR key ,
 243 the system call ignores all but the least significant 9 bits of
 244 .I semflg
 245 and creates a new semaphore set (on success).
 246 .\"
 247 .SS Semaphore initialization
 248 The values of the semaphores in a newly created set are indeterminate.
 249 (POSIX.1-2001 and POSIX.1-2008 are explicit on this point,
 250 although POSIX.1-2008 notes that a future version of the standard
 251 may require an implementation to initialize the semaphores to 0.)
 252 Although Linux, like many other implementations,
 253 initializes the semaphore values to 0,
 254 a portable application cannot rely on this:
 255 it should explicitly initialize the semaphores to the desired values.
 256 .\" In truth, every one of the many implementations that I've tested sets
 257 .\" the values to zero, but I suppose there is/was some obscure
 258 .\" implementation out there that does not.
 259 .PP
 260 Initialization can be done using
 261 .BR semctl (2)
 262 .B SETVAL
 263 or
 264 .B SETALL
 265 operation.
 266 Where multiple peers do not know who will be the first to
 267 initialize the set, checking for a nonzero
 268 .I sem_otime
 269 in the associated data structure retrieved by a
 270 .BR semctl (2)
 271 .B IPC_STAT
 272 operation can be used to avoid races.
 273 .\"
 274 .SS Semaphore limits
 275 The following limits on semaphore set resources affect the
 276 .BR semget ()
 277 call:
 278 .TP
 279 .B SEMMNI
 280 System-wide limit on the number of semaphore sets.
 281 On Linux systems before version 3.19,
 282 the default value for this limit was 128.
 283 Since Linux 3.19,
 284 .\" commit e843e7d2c88b7db107a86bd2c7145dc715c058f4
 285 the default value is 32,000.
 286 On Linux, this limit can be read and modified via the fourth field of
 287 .IR /proc/sys/kernel/sem .
 288 .\" This /proc file is not available in Linux 2.2 and earlier -- MTK
 289 .TP
 290 .B SEMMSL
 291 Maximum number of semaphores per semaphore ID.
 292 On Linux systems before version 3.19,
 293 the default value for this limit was 250.
 294 Since Linux 3.19,
 295 .\" commit e843e7d2c88b7db107a86bd2c7145dc715c058f4
 296 the default value is 32,000.
 297 On Linux, this limit can be read and modified via the first field of
 298 .IR /proc/sys/kernel/sem .
 299 .TP
 300 .B SEMMNS
 301 System-wide limit on the number of semaphores: policy dependent
 302 (on Linux, this limit can be read and modified via the second field of
 303 .IR /proc/sys/kernel/sem ).
 304 Note that the number of semaphores system-wide
 305 is also limited by the product of
 306 .B SEMMSL
 307 and
 308 .BR SEMMNI .
 309 .SH BUGS
 310 The name choice
 311 .B IPC_PRIVATE
 312 was perhaps unfortunate,
 313 .B IPC_NEW
 314 would more clearly show its function.
 315 .SH SEE ALSO
 316 .BR semctl (2),
 317 .BR semop (2),
 318 .BR ftok (3),
 319 .BR capabilities (7),
 320 .BR sem_overview (7),
 321 .BR sysvipc (7)