POSIX semaphores

sema_t sem_t

POSIX-specific semaphore type.

int sem_init(semaphore.h::sem_t * sem, int pshared, unsigned value)

Initialize an unnamed semaphore.

See also

The Open Group Base Specifications Issue 7, sem_init()

The semaphore.h::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 semaphore.h::sem_init(), the semaphore may be used in subsequent calls to semaphore.h::sem_wait(), semaphore.h::sem_timedwait(), semaphore.h::sem_trywait(), semaphore.h::sem_post(), and semaphore.h::sem_destroy(). This semaphore shall remain usable until the semaphore is destroyed.

Parameters

sem:Semaphore to initialize.
pshared:**(unused, since RIOT only has threads)** Semaphore is shared between processes not threads.
value:Value to set.

Return values

  • 0 on success.
  • -1, on error and errno set to indicate the error.
int sem_destroy(semaphore.h::sem_t * sem)

destroy an unnamed semaphore

See also

The Open Group Base Specifications Issue 7, sem_destroy()

The semaphore.h::sem_destroy() function shall destroy the unnamed semaphore indicated by sem. Only a semaphore that was created using semaphore.h::sem_init() may be destroyed using semaphore.h::sem_destroy(); the effect of calling semaphore.h::sem_destroy() with a named semaphore is undefined. The effect of subsequent use of the semaphore sem is undefined until sem is reinitialized by another call to semaphore.h::sem_init().

It is safe to destroy an initialized semaphore upon which no threads are currently blocked. The effect of destroying a semaphore upon which other threads are currently blocked is undefined.

Parameters

sem:A semaphore.

Return values

  • 0 on success.
  • -1, on error and errno set to indicate the error.
int sem_post(semaphore.h::sem_t * sem)

Unlock a semaphore.

See also

The Open Group Base Specifications Issue 7, sem_post()

The semaphore.h::sem_post() function shall unlock the semaphore referenced by sem by performing a semaphore unlock operation on that semaphore.

If the semaphore value resulting from this operation is positive, then no threads were blocked waiting for the semaphore to become unlocked; the semaphore value is simply incremented.

If the value of the semaphore resulting from this operation is zero, then one of the threads blocked waiting for the semaphore shall be allowed to return successfully from its call to semaphore.h::sem_wait().

Parameters

sem:A semaphore

Return values

  • 0 on success.
  • -1, on error and errno set to indicate the error.
int sem_wait(semaphore.h::sem_t * sem)

Lock a semaphore.

See also

The Open Group Base Specifications Issue 7, sem_wait()

The semaphore.h::sem_wait() function shall lock the semaphore referenced by sem by performing a semaphore lock operation on that semaphore. If the semaphore value is currently zero, then the calling thread shall not return from the call to semaphore.h::sem_wait() until it either locks the semaphore or the call is interrupted by a signal.

Parameters

sem:A semaphore.

Return values

  • 0 on success.
  • -1, on error and errno set to indicate the error.
semaphore.h::sem_t * sem_open(const char * name, int oflag, ...)

Open a named semaphore name with open flags oflag.

See also

The Open Group Base Specifications Issue 7, sem_open()

named semaphore are currently not supported

Parameters

name:Name to set.
oflag:Flags to set.

Return values

int sem_close(semaphore.h::sem_t * sem)

Close descriptor for named semaphore sem.

See also

The Open Group Base Specifications Issue 7, sem_close()

named semaphore are currently not supported

Parameters

sem:Semaphore to close.

Return values

  • Always -1, since it is not implemented currently.
int sem_unlink(const char * name)

Remove named semaphore name.

See also

The Open Group Base Specifications Issue 7, sem_unlink()

named semaphore are currently not supported

Parameters

name:Name to unlink.

Return values

  • Always -1, since it is not implemented currently.
int sem_timedwait(semaphore.h::sem_t * sem, const struct timespec * abstime)

Similar to `sem_wait’ but wait only until abstime.

See also

The Open Group Base Specifications Issue 7, sem_timedwait()

The semaphore.h::sem_timedwait() function shall lock the semaphore referenced by sem as in the semaphore.h::sem_wait() function. However, if the semaphore cannot be locked without waiting for another process or thread to unlock the semaphore by performing a semaphore.h::sem_post() function, this wait shall be terminated when the specified timeout expires.

Parameters

sem:Semaphore to wait on.
abstime:Absolute time (that is when the clock on which temouts are based equals this value) the timeout for the wait shall expire. If the value specified has already passed the timeout expires immediately.

Return values

  • 0 on success.
  • -1, on error and errno set to indicate the error.
int sem_trywait(semaphore.h::sem_t * sem)

Test whether sem is posted.

See also

The Open Group Base Specifications Issue 7, sem_trywait()

Parameters

sem:Semaphore to try to wait on

Return values

  • 0 on success.
  • -1, on error and errno set to indicate the error.
int sem_getvalue(semaphore.h::sem_t * sem, int * sval)

Get current value of sem and store it in sval.

See also

The Open Group Base Specifications Issue 7, sem_getvalue()

Parameters

sem:Semaphore to get the value from.
sval:Place where value goes to.

Return values

  • 0 on success.
  • -1, on error and errno set to indicate the error.
SEM_FAILED

Value returned if `sem_open’ failed. 

1
((sem_t *) 0)