.\" .\" Copyright 2004 Michael B. Allen .\" .TH svsem 3m "Apr 29, 2005" "libmba-0.9.1" "MBA Library Functions" .SH NAME svsem \- POSIX-like semaphores implemented using SysV semaphores. .SH SYNOPSIS .nf .B #include .sp .sp .BI "int svsem_create(svsem_t *" sem ", int " value ", int " undo "); .br .BI "int svsem_destroy(svsem_t *" sem "); .br .BI "int svsem_open(svsem_t *" sem ", const char *" path ", int " oflag ", ... /* mode_t mode, int value */); .br .BI "int svsem_close(svsem_t *" sem "); .br .BI "int svsem_remove(svsem_t *" sem "); .br .BI "int svsem_pool_create(struct pool *" p ", .BI " unsigned int " max_size ", .BI " unsigned int " value ", .BI " int " undo ", .BI " struct allocator *" al "); .br .BI "int svsem_pool_destroy(struct pool *" p "); .br .sp .BI "int svsem_wait(svsem_t *" sem "); .br .BI "int svsem_trywait(svsem_t *" sem "); .br .BI "int svsem_post(svsem_t *" sem "); .br .BI "int svsem_post_multiple(svsem_t *" sem ", int " count "); .br .BI "int svsem_getvalue(svsem_t *" sem ", int *" value "); .br .BI "int svsem_setvalue(svsem_t *" sem ", int " value "); .br .fi .SH DESCRIPTION Semaphores provide a mechanism to coordinate multiple processes or threads accessing shared resources. The .BR "svsem" (3m) module provides a POSIX-like semaphore interface implemented using the more common System V semaphore interface. .sp The .BR "svsem" (3m) module is not available in the Win32 environment. .PP .TP .B create The .B svsem_create function will created a file using .BR "mkstemp" (3) with a template of .I /tmp/svsemXXXXXX to generate a semaphore key, create and initialize a semaphore .I sem and set it's initial value to .IR "value" . If .I undo is non-zero, the .I SEM_UNDO flag for .B semop calls will be used. The .I 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 .I undo flag must be zero if a process will call wait and post an un-equal number of times such as with counting semaphores. .sp .TP .B destroy The .B svsem_destroy function destroys the semaphore .I sem by removing the semaphore set identifier and unlinking the associated file. .TP .B open The .B svsem_open function creates a new named semaphore or opens an existing semaphore. The .I path parameter is a path (which must refer to an existing, accessible file) that identifies the target semaphore. The .I oflag paremeter can be any combination of 0, .IR "O_CREAT" , .IR "O_EXCL" , and .I O_UNDO or'd together although .I O_EXCL is only meaningful when used with .IR "O_CREAT" . If .I O_CREAT is specified two additional parameters are required; .sp .br a .I mode_t parameter specifying the open mode (e.g. 0600) and .br an .I int parameter specifying the initial value of the semaphore (e.g. 1 for a binary semaphore). .sp If .I O_CREAT is specified without .I 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 .I O_UNDO flag to specify that .I SEM_UNDO behavior should be used (recommended unless calls to wait/post are not symetric per process). .sp Note: It appears that trying to open an existing semaphore on Mac OS X will deadlock because Darwin is not initializing .I sem_otime properly. This requires futher investigation. .TP .B close The .B svsem_close function does nothing but release the memory attributed to .IR "sem" . .TP .B remove The .B svsem_remove function removes the semaphore identified by .IR "sem" . Any attempt to access this semaphore after it has been remove will result in all operations returning an error of .IR "EIDRM" . .TP .B pool_create The .B svsem_pool_create function will create a pool of semaphores. A file will be created using .BR "mkstemp" (3) with a template of .IR "/tmp/svsemXXXXXX" , a semaphore array of .I max_size will be created and all semaphores will be initialized to the specified .IR "value" . No initial .BR "svsem" (3m) objects are created. The .BR "pool" (3m) functions are used to manage the pool. The .B pool_get function will return a semaphore initialized to .I value (reused semaphores will be explicitly reset). The .B svsem_pool_destroy function must be used to destroy an .BR "svsem" (3m) pool. .TP .B pool_destroy The .B svsem_pool_destroy function releases memory associated with the pool, removes the pool semaphore array and unlinks the file backing the array. .TP .B wait The .B svsem_wait function tests the value of the semaphore identified by .I sem and does one of two things; .sp .br If the value is greater than 0, the value is decremented by 1 and the function returns immediately. .br If the value is 0 the calling thread will sleep until .B svsem_post is called on the semaphore at which point the value will be tested again. .sp .TP .B trywait The .B svsem_trywait function tests the value of the semaphore identified by .I sem and does one of two things; .sp .br If the value is greater than 0, the value is decremented by 1 and the function returns immediately. .br If the value is 0 the call will return -1 and set .I errno to .IR "EAGAIN" . .sp This mechanism can be used to test if a thread will wait. .TP .B post The .B svsem_post function increments the value of the semaphore identified by .I sem by 1 and wakes up a thread blocked in .B svsem_wait if there is one. .TP .B post_multiple The .B svsem_post_multiple function performs the equivalent of multiple distinct .B svsem_post operations. The .I count parameter specifies how many post operations are performed. .TP .B getvalue The .B svsem_getvalue function stores the value of the semaphore .I sem into .IR "value" . .TP .B setvalue The .B svsem_setvalue function sets the current value of the semaphore to the specified .IR "value" . .SH RETURNS .TP .B create If the operation is successful 0 is returned. Otherwise -1 is returned and .I errno is set appropriately. .TP .B destroy If the operation is successful 0 is returned. Otherwise -1 is returned and .I errno is set appropriately. Errors that occur attempting to .BR "unlink" (3m) the associated file are ignored. .TP .B open The .B svsem_open function returns 0 if the new semaphore was created successfully or .B NULL if an error occurs in which case .I errno will be set appropriately. If .I O_EXCL is specified and the semaphore already exists, .B NULL is returned and .I errno is set to .IR "EEXIST" . .TP .B close If the operation is successful 0 is returned. Otherwise -1 is returned and .I errno is set appropriately. .TP .B remove The .B svsem_remove function returns 0 if the operation was successful or -1 if an error occured in which case .I errno will be set appropriately. .TP .B pool_create If the operation is successful 0 is returned. Otherwise -1 is returned and .I errno is set appropriately. .TP .B pool_destroy If the operation is successful 0 is returned. Otherwise -1 is returned and .I errno is set appropriately. .TP .B wait If the operation is successful 0 is returned. Otherwise -1 is returned and .I errno is set appropriately. .TP .B trywait If the operation is successful 0 is returned. Otherwise -1 is returned and .I errno is set appropriately. .TP .B post If the operation is successful 0 is returned. Otherwise -1 is returned and .I errno is set appropriately. .TP .B post_multiple If the operation is successful 0 is returned. Otherwise -1 is returned and .I errno is set appropriately. .TP .B getvalue If the operation is successful 0 is returned. Otherwise -1 is returned and .I errno is set appropriately. .TP .B setvalue If the operation is successful 0 is returned. Otherwise -1 is returned and .I errno is set appropriately.