The Open Group Base Specifications Issue 7
IEEE Std 1003.1-2008, 2016 Edition
Copyright © 2001-2016 The IEEE and The Open Group

NAME

sem_init - initialize an unnamed semaphore

SYNOPSIS

#include <semaphore.h>

int sem_init(sem_t *
sem, int pshared, unsigned value);

DESCRIPTION

The sem_init() function shall initialize the unnamed semaphore referred to by sem. The value of the initialized semaphore shall be value. Following a successful call to sem_init(), the semaphore may be used in subsequent calls to sem_wait(), sem_timedwait(), sem_trywait(), sem_post(), and sem_destroy(). This semaphore shall remain usable until the semaphore is destroyed.

If the pshared argument has a non-zero value, then the semaphore is shared between processes; in this case, any process that can access the semaphore sem can use sem for performing sem_wait(), sem_timedwait(), sem_trywait(), sem_post(), and sem_destroy() operations.

If the pshared argument is zero, then the semaphore is shared between threads of the process; any thread in this process can use sem for performing sem_wait(), sem_timedwait(), sem_trywait(), sem_post(), and sem_destroy() operations.

See Synchronization Object Copies and Alternative Mappings for further requirements.

Attempting to initialize an already initialized semaphore results in undefined behavior.

RETURN VALUE

Upon successful completion, the sem_init() function shall initialize the semaphore in sem and return 0. Otherwise, it shall return -1 and set errno to indicate the error.

ERRORS

The sem_init() function shall fail if:

[EINVAL]
The value argument exceeds {SEM_VALUE_MAX}.
[ENOSPC]
A resource required to initialize the semaphore has been exhausted, or the limit on semaphores ( {SEM_NSEMS_MAX}) has been reached.
[EPERM]
The process lacks appropriate privileges to initialize the semaphore.

The following sections are informative.

EXAMPLES

None.

APPLICATION USAGE

None.

RATIONALE

None.

FUTURE DIRECTIONS

None.

SEE ALSO

sem_destroy, sem_post, sem_timedwait, sem_trywait

XBD <semaphore.h>

CHANGE HISTORY

First released in Issue 5. Included for alignment with the POSIX Realtime Extension.

Issue 6

The sem_init() function is marked as part of the Semaphores option.

The [ENOSYS] error condition has been removed as stubs need not be provided if an implementation does not support the Semaphores option.

The sem_timedwait() function is added to the SEE ALSO section for alignment with IEEE Std 1003.1d-1999.

IEEE Std 1003.1-2001/Cor 2-2004, item XSH/TC2/D6/116 is applied, updating the DESCRIPTION to add the sem_timedwait() function for alignment with IEEE Std 1003.1d-1999.

Issue 7

SD5-XSH-ERN-176 is applied.

The sem_init() function is moved from the Semaphores option to the Base.

POSIX.1-2008, Technical Corrigendum 1, XSH/TC1-2008/0526 [37] is applied.

POSIX.1-2008, Technical Corrigendum 2, XSH/TC2-2008/0318 [972] is applied.

End of informative text.

 

return to top of page

UNIX ® is a registered Trademark of The Open Group.
POSIX ® is a registered Trademark of The IEEE.
Copyright © 2001-2016 The IEEE and The Open Group, All Rights Reserved
[ Main Index | XBD | XSH | XCU | XRAT ]