SEM_GETVALUE(3) Linux Programmer's Manual SEM_GETVALUE(3)NAME
sem_getvalue - get the value of a semaphore
SYNOPSIS
#include <semaphore.h>
int sem_getvalue(sem_t *sem, int *sval);
Link with -pthread.
DESCRIPTION
sem_getvalue() places the current value of the semaphore pointed to sem into the integer pointed to by sval.
If one or more processes or threads are blocked waiting to lock the semaphore with sem_wait(3), POSIX.1 permits two possibilities for the
value returned in sval: either 0 is returned; or a negative number whose absolute value is the count of the number of processes and threads
currently blocked in sem_wait(3). Linux adopts the former behavior.
RETURN VALUE
sem_getvalue() returns 0 on success; on error, -1 is returned and errno is set to indicate the error.
ERRORS
EINVAL sem is not a valid semaphore.
ATTRIBUTES
For an explanation of the terms used in this section, see attributes(7).
+---------------+---------------+---------+
|Interface | Attribute | Value |
+---------------+---------------+---------+
|sem_getvalue() | Thread safety | MT-Safe |
+---------------+---------------+---------+
CONFORMING TO
POSIX.1-2001, POSIX.1-2008.
NOTES
The value of the semaphore may already have changed by the time sem_getvalue() returns.
SEE ALSO sem_post(3), sem_wait(3), sem_overview(7)COLOPHON
This page is part of release 4.15 of the Linux man-pages project. A description of the project, information about reporting bugs, and the
latest version of this page, can be found at https://www.kernel.org/doc/man-pages/.
Linux 2017-09-15 SEM_GETVALUE(3)
Check Out this Related Man Page
SEMAPHORES(3) Library Functions Manual SEMAPHORES(3)NAME
sem_init, sem_wait, sem_trywait, sem_post, sem_getvalue, sem_destroy - operations on semaphores
SYNOPSIS
#include <semaphore.h>
int sem_init(sem_t *sem, int pshared, unsigned int value);
int sem_wait(sem_t * sem);
int sem_trywait(sem_t * sem);
int sem_post(sem_t * sem);
int sem_getvalue(sem_t * sem, int * sval);
int sem_destroy(sem_t * sem);
DESCRIPTION
This manual page documents POSIX 1003.1b semaphores, not to be confused with SystemV semaphores as described in ipc(5), semctl(2) and
semop(2).
Semaphores are counters for resources shared between threads. The basic operations on semaphores are: increment the counter atomically, and
wait until the counter is non-null and decrement it atomically.
sem_init initializes the semaphore object pointed to by sem. The count associated with the semaphore is set initially to value. The
pshared argument indicates whether the semaphore is local to the current process ( pshared is zero) or is to be shared between several pro-
cesses ( pshared is not zero). LinuxThreads currently does not support process-shared semaphores, thus sem_init always returns with error
ENOSYS if pshared is not zero.
sem_wait suspends the calling thread until the semaphore pointed to by sem has non-zero count. It then atomically decreases the semaphore
count.
sem_trywait is a non-blocking variant of sem_wait. If the semaphore pointed to by sem has non-zero count, the count is atomically
decreased and sem_trywait immediately returns 0. If the semaphore count is zero, sem_trywait immediately returns with error EAGAIN.
sem_post atomically increases the count of the semaphore pointed to by sem. This function never blocks and can safely be used in asynchro-
nous signal handlers.
sem_getvalue stores in the location pointed to by sval the current count of the semaphore sem.
sem_destroy destroys a semaphore object, freeing the resources it might hold. No threads should be waiting on the semaphore at the time
sem_destroy is called. In the LinuxThreads implementation, no resources are associated with semaphore objects, thus sem_destroy actually
does nothing except checking that no thread is waiting on the semaphore.
CANCELLATION
sem_wait is a cancellation point.
ASYNC-SIGNAL SAFETY
On processors supporting atomic compare-and-swap (Intel 486, Pentium and later, Alpha, PowerPC, MIPS II, Motorola 68k), the sem_post func-
tion is async-signal safe and can therefore be called from signal handlers. This is the only thread synchronization function provided by
POSIX threads that is async-signal safe.
On the Intel 386 and the Sparc, the current LinuxThreads implementation of sem_post is not async-signal safe by lack of the required atomic
operations.
RETURN VALUE
The sem_wait and sem_getvalue functions always return 0. All other semaphore functions return 0 on success and -1 on error, in addition to
writing an error code in errno.
ERRORS
The sem_init function sets errno to the following codes on error:
EINVAL value exceeds the maximal counter value SEM_VALUE_MAX
ENOSYS pshared is not zero
The sem_trywait function sets errno to the following error code on error:
EAGAIN the semaphore count is currently 0
The sem_post function sets errno to the following error code on error:
ERANGE after incrementation, the semaphore value would exceed SEM_VALUE_MAX (the semaphore count is left unchanged in this case)
The sem_destroy function sets errno to the following error code on error:
EBUSY some threads are currently blocked waiting on the semaphore.
AUTHOR
Xavier Leroy <Xavier.Leroy@inria.fr>
SEE ALSO pthread_mutex_init(3), pthread_cond_init(3), pthread_cancel(3), ipc(5).
LinuxThreads SEMAPHORES(3)