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