Standards
| Standards / Extensions |
C or C++ |
Dependencies |
|---|
XPG4
XPG4.2
Single UNIX Specification, Version 3
|
both |
|
Format
#define _XOPEN_SOURCE
#include <sys/sem.h>
int semget(key_t key, int nsems, int semflg);
General description
The semget()
function returns the semaphore identifier associated with key.
A
semaphore identifier is created with a
semid_ds data
structure, see <sys/sem.h>, associated with
nsems semaphores
when any of the following is true:
- Argument key has a value of IPC_PRIVATE
- Argument key is not associated with
a semaphore ID and (semflg & IPC_CREAT)
is non zero.
Valid values for the field
semflg include
any combination of the following defined in <sys/ipc.h> and <sys/modes.h>:
- IPC_CREAT
- Creates a semaphore
if the key specified does not already have
an associated ID. IPC_CREATE is ignored when IPC_PRIVATE is
specified.
- IPC_EXCL
- Causes the semget()
function to fail if the key specified has
an associated ID. IPC_EXCL is ignored when IPC_CREAT is
not specified or IPC_PRIVATE is specified.
- __IPC_BINSEM
- Binary semaphore - semaphore must behave in a binary manner:
number of semaphore operations must be 1 and the semop must be 1 with
a semval of 0 or the semop must be -1 with a semval of 0 or 1. SEM_UNDO
is now allowed on a semop() with this option. The use of this flag
will cause improved performance if the PLO instruction is available
on the hardware.
See z/OS XL C/C++ Programming Guide for
further information on semaphore performance.
- __IPC_SHORTHOLD
- This flag states that it is known that the application will only
hold the resource being serialized for extremely short time intervals.
When this flag is combined with the __IPC_BINSEM flag, the default
first-in-first-out (FIFO) ordering of semaphore obtain requesters
will be bypassed, to allow short duration requesters to successfully
obtain the semaphore (and hopefully release it) within the interval
it normally takes to dispatch the next pending waiter for that semaphore.
- S_IRUSR
- Permits read access
when the effective user ID of the caller matches either sem_perm.cuid or sem_perm.uid.
- S_IWUSR
- Permits write
access when the effective user ID of the caller matches either sem_perm.cuid or sem_perm.uid.
- S_IRGRP
- Permits read access
when the effective group ID of the caller matches either sem_perm.cgid or sem_perm.gid.
- S_IWGRP
- Permits write
access when the effective group ID of the caller matches either sem_perm.cgid or sem_perm.gid.
- S_IROTH
- Permits others
read access
- S_IWOTH
- Permits others
write access
When a semaphore set associated with argument key already
exists, setting IPC_EXCL and IPC_CREAT in argument semflg will
force semget() to fail.
When a
semid_ds data
structure is created the following anonymous data structure is created
for each semaphore in the set:
| unsigned short
int |
semval |
Semaphore value |
| pid_t |
sempid |
Process ID of last
operation |
| unsigned sort int |
semcnt |
Number of processes
waiting for semval to become greater than current
value |
| unsigned short int |
semzcnt |
Number of processes
waiting for semval to become zero |
The following fields are initialized when a
semid_ds data
structure is created:
- The fields sem_perm.cuid and sem_perm.uid are
set equal to the effective user ID of the calling process.
- The fields sem_perm.cgid. and sem_perm.gid are
set equal to effective group ID of the calling process.
- The low-order 9 bits of sem_perm.mode are set
to the value in the low-order 9 bits of semflg.
- The field sem_nsems is set to the value of nsems.
- The field sem_otime is set to 0.
- The field sem_ctime is set to the current time.
- The anonymous data structure containing semval for
each semaphore is not initialized. semctl() commands SETVAL and SETALL should
be used to initialize each semaphore's semval value.
Usage notes
- Semaphores created with __IPC_BINSEM will show this bit and may
show the IPC_PLOINUSE bit in the S_MODE byte returned with w_getipc.
Returned value
If successful, semget()
returns a nonnegative semaphore identifier.
If unsuccessful,
semget() returns -1 and sets errno to one of the following values:
- Error Code
- Description
- EACCES
- A semaphore identifier exists for the argument key,
but access permission as specified by the low-order 9 bits of semflg could
not be granted.
- EEXIST
- A semaphore identifier exists for the argument key and
both IPC_CREAT and IPC_EXCL are specified in semflg.
- EINVAL
- The value of nsems is either less than
zero or greater than the system limit. A semaphore identifier associated
with key does not exist and the nsems is
zero. A semaphore identifier associated with key already
exists and the nsems value specified on
semget() when the semaphore identifier was created is less than the nsems value
on the current semget(). The semflg argument
specified flags not currently supported.
- ENOENT
- A semaphore identifier does not exist for the argument key and IPC_CREAT is
not specified.
- ENOSPC
- A system limit of number of semaphore identifiers has been reached.
When
semflg equals
0, the following applies:
- If a semaphore identifier has already been created with key earlier,
and the calling process of this semget() has read and/or write permissions
to it, then semget() returns the associated semaphore identifier.
- If a semaphore identifier has already been created with key earlier,
and the calling process of this semget() does not have read and/or
write permissions to it, then semget() returns-1 and sets errno to
EACCES.
- If a semaphore identifier has not been created with key earlier,
then semget() returns -1 and sets errno to ENOENT.