svsem(3m)

NAME
svsem - POSIX-like semaphores implemented using SysV semaphores.

SYNOPSIS
#include <mba/svsem.h>

int svsem_create(svsem_t *sem, int value, int undo);
int svsem_destroy(svsem_t *sem);
int svsem_open(svsem_t *sem, const char *path, int oflag, ... /* mode_t mode, int value */);
int svsem_close(svsem_t *sem);
int svsem_remove(svsem_t *sem);
int svsem_pool_create(struct pool *p,
            unsigned int max_size,
            unsigned int value,
            int undo,
            struct allocator *al);
int svsem_pool_destroy(struct pool *p);

int svsem_wait(svsem_t *sem);
int svsem_trywait(svsem_t *sem);
int svsem_post(svsem_t *sem);
int svsem_post_multiple(svsem_t *sem, int count);
int svsem_getvalue(svsem_t *sem, int *value);
int svsem_setvalue(svsem_t *sem, int value);

DESCRIPTION
Semaphores provide a mechanism to coordinate multiple processes or threads accessing shared resources. The svsem(3m) module provides a POSIX-like semaphore interface implemented using the more common System V semaphore interface.

The svsem(3m) module is not available in the Win32 environment.

create
    The svsem_create function will created a file using mkstemp(3) with a template of /tmp/svsemXXXXXX to generate a semaphore key, create and initialize a semaphore sem and set it's initial value to value. If undo is non-zero, the SEM_UNDO flag for semop calls will be used. The undo parameter should be non-zero for semaphores for which wait and post will be called symmetrically in any process such as binary semaphores. The undo flag must be zero if a process will call wait and post an un-equal number of times such as with counting semaphores.

destroy
    The svsem_destroy function destroys the semaphore sem by removing the semaphore set identifier and unlinking the associated file.

open
    The svsem_open function creates a new named semaphore or opens an existing semaphore. The path parameter is a path (which must refer to an existing, accessible file) that identifies the target semaphore. The oflag paremeter can be 0, O_CREAT, or O_CREAT | O_EXCL. If O_CREAT is specified two additional parameters are required;

    a mode_t paramter specifying the open mode (e.g. 0600) and
    an int parameter specifying the initial value of the semaphore (e.g. 1 for a binary semaphore).

    If O_CREAT is specified without O_EXCL the semaphore is created and initialized with the specified value if it does not already exist. If the semaphore already exists it is simply opened. Use the SEM_UNDO flag OR'd with oflags to specify that undo behavior should be used (recommended unless calls to wait/post are not symetric per process).

close
    The svsem_close function does nothing but release the memory attributed to sem.

remove
    The svsem_remove function removes the semaphore identified by sem. Any attempt to access this semaphore after it has been remove will result in all operations returning an error of EIDRM.

pool_create
    The svsem_pool_create function will create a pool of semaphores. A file will be created using mkstemp(3) with a template of /tmp/svsemXXXXXX, a semaphore array of max_size will be created and all semaphores will be initialized to the specified value. No initial svsem(3m) objects are created. The pool(3m) functions are used to manage the pool. The pool_get function will return a semaphore initialized to value (reused semaphores will be explicitly reset). The svsem_pool_destroy function must be used to destroy an svsem(3m) pool.

pool_destroy
    The svsem_pool_destroy function releases memory associated with the pool, removes the pool semaphore array and unlinks the file backing the array.

wait
    The svsem_wait function tests the value of the semaphore identified by sem and does one of two things;

    If the value is greater than 0, the value is decremented by 1 and the function returns immediately.
    If the value is 0 the calling thread will sleep until svsem_post is called on the semaphore at which point the value will be tested again.

trywait
    The svsem_trywait function tests the value of the semaphore identified by sem and does one of two things;

    If the value is greater than 0, the value is decremented by 1 and the function returns immediately.
    If the value is 0 the call will return -1 and set errno to EAGAIN.

    This mechanism can be used to test if a thread will wait.

post
    The svsem_post function increments the value of the semaphore identified by sem by 1 and wakes up a thread blocked in svsem_wait if there is one.

post_multiple
    The svsem_post_multiple function performs the equivalent of multiple distinct svsem_post operations. The count parameter specifies how many post operations are performed.

getvalue
    The svsem_getvalue function stores the value of the semaphore sem into value.

setvalue
    The svsem_setvalue function sets the current value of the semaphore to the specified value.

RETURNS

create
    If the operation is successful 0 is returned. Otherwise -1 is returned and errno is set appropriately.

destroy
    If the operation is successful 0 is returned. Otherwise -1 is returned and errno is set appropriately. Errors that occur attempting to unlink(3m) the associated file are ignored.

open
    The svsem_open function returns 0 if the new semaphore was created successfully or NULL if an error occurs in which case errno will be set appropriately. If O_EXCL is specified and the semaphore already exists, NULL is returned and errno is set to EEXIST.

close
    If the operation is successful 0 is returned. Otherwise -1 is returned and errno is set appropriately.

remove
    The svsem_remove function returns 0 if the operation was successful or -1 if an error occured in which case errno will be set appropriately.

pool_create
    If the operation is successful 0 is returned. Otherwise -1 is returned and errno is set appropriately.

pool_destroy
    If the operation is successful 0 is returned. Otherwise -1 is returned and errno is set appropriately.

wait
    If the operation is successful 0 is returned. Otherwise -1 is returned and errno is set appropriately.

trywait
    If the operation is successful 0 is returned. Otherwise -1 is returned and errno is set appropriately.

post
    If the operation is successful 0 is returned. Otherwise -1 is returned and errno is set appropriately.

post_multiple
    If the operation is successful 0 is returned. Otherwise -1 is returned and errno is set appropriately.

getvalue
    If the operation is successful 0 is returned. Otherwise -1 is returned and errno is set appropriately.

setvalue
    If the operation is successful 0 is returned. Otherwise -1 is returned and errno is set appropriately.