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 When creating a new semaphore set,
 102 .BR semget ()
 103 initialises the set's associated data structure
 104 .I semid_ds
 105 (see
 106 .BR semctl (2))
 107 as follows:
 108 .IP
 109 .I sem_perm.cuid
 110 and
 111 .I sem_perm.uid
 112 are set to the effective user ID of the calling process.
 113 .IP
 114 .I sem_perm.cgid
 115 and
 116 .I sem_perm.gid
 117 are set to the effective group ID of the calling process.
 118 .IP
 119 The least significant 9 bits of
 120 .I sem_perm.mode
 121 are set to the least significant 9 bits of
 122 .IR semflg .
 123 .IP
 124 .I sem_nsems
 125 is set to the value of
 126 .IR nsems .
 127 .IP
 128 .I sem_otime
 129 is set to 0.
 130 .IP
 131 .I sem_ctime
 132 is set to the current time.
 133 .PP
 134 The argument
 135 .I nsems
 136 can be 0
 137 (a don't care)
 138 when a semaphore set is not being created.
 139 Otherwise
 140 .I nsems
 141 must be greater than 0
 142 and less than or equal to the maximum number of semaphores per semaphore set
 143 .RB ( SEMMSL ).
 144 .PP
 145 If the semaphore set already exists, the permissions are
 146 verified.
 147 .\" and a check is made to see if it is marked for destruction.
 148 .SH "RETURN VALUE"
 149 If successful, the return value will be the semaphore set identifier
 150 (a nonnegative integer), otherwise \-1
 151 is returned, with
 152 .I errno
 153 indicating the error.
 154 .SH ERRORS
 155 On failure
 156 .I errno
 157 will be set to one of the following:
 158 .TP 11
 159 .B EACCES
 160 A semaphore set exists for
 161 .IR key ,
 162 but the calling process does not have permission to access the set,
 163 and does not have the
 164 .BR CAP_IPC_OWNER
 165 capability.
 166 .TP
 167 .B EEXIST
 168 A semaphore set exists for
 169 .B key
 170 and
 171 .I semflg
 172 specified both
 173 .B IPC_CREAT
 174 and
 175 .BR IPC_EXCL .
 176 .\" .TP
 177 .\" .B EIDRM
 178 .\" The semaphore set is marked to be deleted.
 179 .TP
 180 .B EINVAL
 181 .IR nsems
 182 is less than 0 or greater than the limit on the number
 183 of semaphores per semaphore set
 184 .RB ( SEMMSL ),
 185 or a semaphore set corresponding to
 186 .I key
 187 already exists, and
 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 NOTES
 211 .B IPC_PRIVATE
 212 isn't a flag field but a
 213 .I key_t
 214 type.
 215 If this special value is used for
 216 .IR key ,
 217 the system call ignores everything but the least significant 9 bits of
 218 .I semflg
 219 and creates a new semaphore set (on success).
 220 .PP
 221 The following limits on semaphore set resources affect the
 222 .BR semget ()
 223 call:
 224 .TP 11
 225 .B SEMMNI
 226 System wide maximum number of semaphore sets: policy dependent
 227 (on Linux, this limit can be read and modified via the fourth field of
 228 .IR /proc/sys/kernel/sem ).
 229 .\" This /proc file is not available in Linux 2.2 and earlier -- MTK
 230 .TP
 231 .B SEMMSL
 232 Maximum number of semaphores per semid: implementation dependent
 233 (on Linux, this limit can be read and modified via the first field of
 234 .IR /proc/sys/kernel/sem ).
 235 .TP
 236 .B SEMMNS
 237 System wide maximum number of semaphores: policy dependent
 238 (on Linux, this limit can be read and modified via the second field of
 239 .IR /proc/sys/kernel/sem ).
 240 Values greater than
 241 .B SEMMSL * SEMMNI
 242 makes it irrelevant.
 243 .SH BUGS
 244 The name choice IPC_PRIVATE was perhaps unfortunate, IPC_NEW
 245 would more clearly show its function.
 246 .LP
 247 The semaphores in a set are not initialised by
 248 .BR semget ().
 249 .\" In fact they are initialised to zero on Linux, but POSIX.1-2001
 250 .\" does not specify this, and we can't portably rely on it.
 251 In order to initialise the semaphores,
 252 .BR semctl (2)
 253 must be used to perform a
 254 .B SETVAL
 255 or a
 256 .B SETALL
 257 operation on the semaphore set.
 258 (Where multiple peers do not know who will be the first to
 259 initialise the set, checking for a non-zero
 260 .I sem_otime
 261 in the associated data structure retrieved by a
 262 .BR semctl ()
 263 .B IPC_STAT
 264 operation can be used to avoid races.)
 265 .SH "CONFORMING TO"
 266 SVr4, SVID.
 267 SVr4 documents additional error conditions EFBIG, E2BIG, EAGAIN,
 268 ERANGE, EFAULT.
 269 .SH "SEE ALSO"
 270 .BR semctl (2),
 271 .BR semop (2),
 272 .BR ftok (3),
 273 .BR ipc (5),
 274 .BR capabilities (7)