GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  SVSEM (3)

NAME

svsem - POSIX-like semaphores implemented using SysV semaphores.

CONTENTS

Synopsis
Description
Returns

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_tmode,intvalue*/);
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 any combination of 0, O_CREAT, O_EXCL, and O_UNDO or’d together although O_EXCL is only meaningful when used with O_CREAT. If O_CREAT is specified two additional parameters are required;

a mode_t parameter 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 O_UNDO flag to specify that SEM_UNDO behavior should be used (recommended unless calls to wait/post are not symetric per process).

Note: It appears that trying to open an existing semaphore on Mac OS X will deadlock because Darwin is not initializing sem_otime properly. This requires futher investigation.

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.
Search for    or go to Top of page |  Section 3 |  Main Index


libmba-0.9.1 SVSEM (3m) Apr 29, 2005

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.