original/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 2014-05-21 "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 .sp
  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 A new set of
  56 .I nsems
  57 semaphores is created if
  58 .I key
  59 has the value
  60 .B IPC_PRIVATE
  61 or if no existing semaphore set is associated with
  62 .I key
  63 and
  64 .B IPC_CREAT
  65 is specified in
  66 .IR semflg .
  67 .PP
  68 If
  69 .I semflg
  70 specifies both
  71 .B IPC_CREAT
  72 and
  73 .B IPC_EXCL
  74 and a semaphore set already exists for
  75 .IR key ,
  76 then
  77 .BR semget ()
  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 9 bits of the argument
  88 .I semflg
  89 define the permissions (for owner, group and others)
  90 for the semaphore set.
  91 These bits have the same format, and the same
  92 meaning, as the
  93 .I mode
  94 argument of
  95 .BR open (2)
  96 (though the execute permissions are
  97 not meaningful for semaphores, and write permissions mean permission
  98 to alter semaphore values).
  99 .PP
 100 When creating a new semaphore set,
 101 .BR semget ()
 102 initializes the set's associated data structure,
 103 .I semid_ds
 104 (see
 105 .BR semctl (2)),
 106 as follows:
 107 .IP
 108 .I sem_perm.cuid
 109 and
 110 .I sem_perm.uid
 111 are set to the effective user ID of the calling process.
 112 .IP
 113 .I sem_perm.cgid
 114 and
 115 .I sem_perm.gid
 116 are set to the effective group ID of the calling process.
 117 .IP
 118 The least significant 9 bits of
 119 .I sem_perm.mode
 120 are set to the least significant 9 bits of
 121 .IR semflg .
 122 .IP
 123 .I sem_nsems
 124 is set to the value of
 125 .IR nsems .
 126 .IP
 127 .I sem_otime
 128 is set to 0.
 129 .IP
 130 .I sem_ctime
 131 is set to the current time.
 132 .PP
 133 The argument
 134 .I nsems
 135 can be 0
 136 (a don't care)
 137 when a semaphore set is not being created.
 138 Otherwise,
 139 .I nsems
 140 must be greater than 0
 141 and less than or equal to the maximum number of semaphores per semaphore set
 142 .RB ( SEMMSL ).
 143 .PP
 144 If the semaphore set already exists, the permissions are
 145 verified.
 146 .\" and a check is made to see if it is marked for destruction.
 147 .SH RETURN VALUE
 148 If successful, the return value will be the semaphore set identifier
 149 (a nonnegative integer), otherwise, \-1
 150 is returned, with
 151 .I errno
 152 indicating the error.
 153 .SH ERRORS
 154 On failure,
 155 .I errno
 156 will be set to one of the following:
 157 .TP
 158 .B EACCES
 159 A semaphore set exists for
 160 .IR key ,
 161 but the calling process does not have permission to access the set,
 162 and does not have the
 163 .B CAP_IPC_OWNER
 164 capability.
 165 .TP
 166 .B EEXIST
 167 .B IPC_CREAT
 168 and
 169 .BR IPC_EXCL
 170 were specified in
 171 .IR semflg ,
 172 but a semaphore set already exists for
 173 .IR key .
 174 .\" .TP
 175 .\" .B EIDRM
 176 .\" The semaphore set is marked to be deleted.
 177 .TP
 178 .B EINVAL
 179 .I nsems
 180 is less than 0 or greater than the limit on the number
 181 of semaphores per semaphore set
 182 .RB ( SEMMSL ).
 183 .TP
 184 .B EINVAL
 185 A semaphore set corresponding to
 186 .I key
 187 already exists, but
 188 .I nsems
 189 is larger than the number of semaphores in that set.
 190 .TP
 191 .B ENOENT
 192 No semaphore set exists for
 193 .I key
 194 and
 195 .I semflg
 196 did not specify
 197 .BR IPC_CREAT .
 198 .TP
 199 .B ENOMEM
 200 A semaphore set has to be created but the system does not have
 201 enough memory for the new data structure.
 202 .TP
 203 .B ENOSPC
 204 A semaphore set has to be created but the system limit for the maximum
 205 number of semaphore sets
 206 .RB ( SEMMNI ),
 207 or the system wide maximum number of semaphores
 208 .RB ( SEMMNS ),
 209 would be exceeded.
 210 .SH CONFORMING TO
 211 SVr4, POSIX.1-2001.
 212 .\" SVr4 documents additional error conditions EFBIG, E2BIG, EAGAIN,
 213 .\" ERANGE, EFAULT.
 214 .SH NOTES
 215 The inclusion of
 216 .I <sys/types.h>
 217 and
 218 .I <sys/ipc.h>
 219 isn't required on Linux or by any version of POSIX.
 220 However,
 221 some old implementations required the inclusion of these header files,
 222 and the SVID also documented their inclusion.
 223 Applications intended to be portable to such old systems may need
 224 to include these header files.
 225 .\" Like Linux, the FreeBSD man pages still document
 226 .\" the inclusion of these header files.
 227
 228 .B IPC_PRIVATE
 229 isn't a flag field but a
 230 .I key_t
 231 type.
 232 If this special value is used for
 233 .IR key ,
 234 the system call ignores all but the least significant 9 bits of
 235 .I semflg
 236 and creates a new semaphore set (on success).
 237 .\"
 238 .SS Semaphore initialization
 239 The values of the semaphores in a newly created set are indeterminate.
 240 (POSIX.1-2001 and POSIX.1-2008 are explicit on this point,
 241 although POSIX.1-2008 notes that a future version of the standard
 242 may require an implementation to initialize the semaphores to 0.)
 243 Although Linux, like many other implementations,
 244 initializes the semaphore values to 0,
 245 a portable application cannot rely on this:
 246 it should explicitly initialize the semaphores to the desired values.
 247 .\" In truth, every one of the many implementations that I've tested sets
 248 .\" the values to zero, but I suppose there is/was some obscure
 249 .\" implementation out there that does not.
 250
 251 Initialization can be done using
 252 .BR semctl (2)
 253 .B SETVAL
 254 or
 255 .B SETALL
 256 operation.
 257 Where multiple peers do not know who will be the first to
 258 initialize the set, checking for a nonzero
 259 .I sem_otime
 260 in the associated data structure retrieved by a
 261 .BR semctl (2)
 262 .B IPC_STAT
 263 operation can be used to avoid races.
 264 .\"
 265 .SS Semaphore limits
 266 The following limits on semaphore set resources affect the
 267 .BR semget ()
 268 call:
 269 .TP
 270 .B SEMMNI
 271 System-wide limit on the number of semaphore sets: policy dependent
 272 (on Linux, this limit can be read and modified via the fourth field of
 273 .IR /proc/sys/kernel/sem ).
 274 .\" This /proc file is not available in Linux 2.2 and earlier -- MTK
 275 .TP
 276 .B SEMMSL
 277 Maximum number of semaphores per semaphore ID: implementation dependent
 278 (on Linux, this limit can be read and modified via the first field of
 279 .IR /proc/sys/kernel/sem ).
 280 .TP
 281 .B SEMMNS
 282 System-wide limit on the number of semaphores: policy dependent
 283 (on Linux, this limit can be read and modified via the second field of
 284 .IR /proc/sys/kernel/sem ).
 285 Note that the number of semaphores system-wide
 286 is also limited by the product of
 287 .B SEMMSL
 288 and
 289 .BR SEMMNI .
 290 .SH BUGS
 291 The name choice
 292 .B IPC_PRIVATE
 293 was perhaps unfortunate,
 294 .B IPC_NEW
 295 would more clearly show its function.
 296 .SH SEE ALSO
 297 .BR semctl (2),
 298 .BR semop (2),
 299 .BR ftok (3),
 300 .BR capabilities (7),
 301 .BR sem_overview (7),
 302 .BR svipc (7)
 303 .SH COLOPHON
 304 This page is part of release 3.79 of the Linux
 305 .I man-pages
 306 project.
 307 A description of the project,
 308 information about reporting bugs,
 309 and the latest version of this page,
 310 can be found at
 311 \%http://www.kernel.org/doc/man\-pages/.