VxWorks Reference Manual : Libraries
semPxLib - semaphore synchronization library (POSIX)
semPxLibInit( ) - initialize POSIX semaphore support
sem_init( ) - initialize an unnamed semaphore (POSIX)
sem_destroy( ) - destroy an unnamed semaphore (POSIX)
sem_open( ) - initialize/open a named semaphore (POSIX)
sem_close( ) - close a named semaphore (POSIX)
sem_unlink( ) - remove a named semaphore (POSIX)
sem_wait( ) - lock (take) a semaphore, blocking if not available (POSIX)
sem_trywait( ) - lock (take) a semaphore, returning error if unavailable (POSIX)
sem_post( ) - unlock (give) a semaphore (POSIX)
sem_getvalue( ) - get the value of a semaphore (POSIX)
This library implements the POSIX 1003.1b semaphore interface. For alternative semaphore routines designed expressly for VxWorks, see the manual page for semLib and other semaphore libraries mentioned there. POSIX semaphores are counting semaphores; as such they are most similar to the semCLib VxWorks-specific semaphores.
The main advantage of POSIX semaphores is portability (to the extent that alternative operating systems also provide these POSIX interfaces). However, VxWorks-specific semaphores provide the following features absent from the semaphores implemented in this library: priority inheritance, task-deletion safety, the ability for a single task to take a semaphore multiple times, ownership of mutual-exclusion semaphores, semaphore timeout, and the choice of queuing mechanism.
POSIX defines both named and unnamed semaphores; semPxLib includes separate routines for creating and deleting each kind. For other operations, applications use the same routines for both kinds of semaphore.
The POSIX standard uses the terms wait or lock where take is normally used in VxWorks, and the terms post or unlock where give is normally used in VxWorks. VxWorks documentation that is specific to the POSIX interfaces (such as the remainder of this manual entry, and the manual entries for subroutines in this library) uses the POSIX terminology, in order to make it easier to read in conjunction with other references on POSIX.
The sem_destroy( ) call terminates an unnamed semaphore and deallocates any associated memory; the combination of sem_close( ) and sem_unlink( ) has the same effect for named semaphores. Take care when deleting semaphores, particularly those used for mutual exclusion, to avoid deleting a semaphore out from under a task that has already locked that semaphore. Applications should adopt the protocol of only deleting semaphores that the deleting task has successfully locked. (Similarly, for named semaphores, applications should take care to only close semaphores that the closing task has opened.)
If there are tasks blocked waiting for the semaphore, sem_destroy( ) fails and sets errno to EBUSY.
semaphore.h
semPxLib, POSIX 1003.1b document, semLib, VxWorks Programmer's Guide: Basic OS
semPxLibInit( ) - initialize POSIX semaphore support
STATUS semPxLibInit (void)
This routine must be called before using POSIX semaphores.
OK, or ERROR if there is an error installing the semaphore library.
sem_init( ) - initialize an unnamed semaphore (POSIX)
int sem_init ( sem_t * sem, /* semaphore to be initialized */ int pshared, /* process sharing */ unsigned int value /* semaphore initialization value */ )
This routine is used to initialize the unnamed semaphore sem. The value of the initialized semaphore is value. Following a successful call to sem_init( ) the semaphore may be used in subsequent calls to sem_wait( ), sem_trywait( ), and sem_post( ). This semaphore remains usable until the semaphore is destroyed.
The pshared parameter currently has no effect.
Only sem itself may be used for synchronization.
0 (OK), or -1 (ERROR) if unsuccessful.
EINVAL
- value exceeds SEM_VALUE_MAX.
ENOSPC
- unable to initialize semaphore due to resource constraints.
semPxLib, sem_wait( ), sem_trywait( ), sem_post( )
sem_destroy( ) - destroy an unnamed semaphore (POSIX)
int sem_destroy ( sem_t * sem /* semaphore descriptor */ )
This routine is used to destroy the unnamed semaphore indicated by sem.
The sem_destroy( ) call can only destroy a semaphore created by sem_init( ). Calling sem_destroy( ) with a named semaphore will cause a EINVAL error. Subsequent use of the sem semaphore will cause an EINVAL error in the calling function.
If one or more tasks is blocked on the semaphore, the semaphore is not destroyed.
Take care when deleting semaphores, particularly those used for mutual exclusion, to avoid deleting a semaphore out from under a task that has already locked that semaphore. Applications should adopt the protocol of only deleting semaphores that the deleting task has successfully locked.
0 (OK), or -1 (ERROR) if unsuccessful.
EINVAL
- invalid semaphore descriptor.
EBUSY
- one or more tasks is blocked on the semaphore.
sem_open( ) - initialize/open a named semaphore (POSIX)
sem_t * sem_open ( const char * name, /* semaphore name */ int oflag /* semaphore creation flags */ )
This routine establishes a connection between a named semaphore and a task. Following a call to sem_open( ) with a semaphore name name, the task may reference the semaphore associated with name using the address returned by this call. This semaphore may be used in subsequent calls to sem_wait( ), sem_trywait( ), and sem_post( ). The semaphore remains usable until the semaphore is closed by a successful call to sem_close( ).
The oflag argument controls whether the semaphore is created or merely accessed by the call to sem_open( ). The following flag bits may be set in oflag:
- O_CREAT
- Use this flag to create a semaphore if it does not already exist. If O_CREAT is set and the semaphore already exists, O_CREAT has no effect except as noted below under O_EXCL. Otherwise, sem_open( ) creats a semaphore. O_CREAT requires a third and fourth argument: mode, which is of type mode_t, and value, which is of type unsigned int. mode has no effect in this implementation. The semaphore is created with an initial value of value. Valid initial values for semaphores must be less than or equal to SEM_VALUE_MAX.
- O_EXCL
- If O_EXCL and O_CREAT are set, sem_open( ) will fail if the semaphore name exists. If O_EXCL is set and O_CREAT is not set, the named semaphore is not created.
To determine whether a named semaphore already exists in the system, call sem_open( ) with the flags O_CREAT | O_EXCL. If the sem_open( ) call fails, the semaphore exists.
If a task makes multiple calls to sem_open( ) with the same value for name, then the same semaphore address is returned for each such call, provided that there have been no calls to sem_unlink( ) for this semaphore.
References to copies of the semaphore will produce undefined results.
The current implementation has the following limitations:
- A semaphore cannot be closed with calls to _exit( ) or exec( ).
- A semaphore cannot be implemented as a file.
- Semaphore names will not appear in the file system.
A pointer to sem_t, or -1 (ERROR) if unsuccessful.
EEXIST
- O_CREAT | O_EXCL are set and the semaphore already exists.
EINVAL
- value exceeds SEM_VALUE_MAX or the semaphore name is invalid.
ENAMETOOLONG
- the semaphore name is too long.
ENOENT
- the named semaphore does not exist and O_CREAT is not set.
ENOSPC
- the semaphore could not be initialized due to resource constraints.
semPxLib, sem_unlink( )
sem_close( ) - close a named semaphore (POSIX)
int sem_close ( sem_t * sem /* semaphore descriptor */ )
This routine is called to indicate that the calling task is finished with the specified named semaphore, sem. Do not call this routine with an unnamed semaphore (i.e., one created by sem_init( )); the effects are undefined. The sem_close( ) call deallocates any system resources allocated by the system for use by this task for this semaphore.
If the semaphore has not been removed with a call to sem_unlink( ), then sem_close( ) has no effect on the state of the semaphore. However, if the semaphore has been unlinked, the semaphore vanishes when the last task closes it.
Take care to avoid risking the deletion of a semaphore that another task has already locked. Applications should only close semaphores that the closing task has opened.
0 (OK), or -1 (ERROR) if unsuccessful.
EINVAL
- invalid semaphore descriptor.
semPxLib, sem_unlink( ), sem_open( ), sem_init( )
sem_unlink( ) - remove a named semaphore (POSIX)
int sem_unlink ( const char * name /* semaphore name */ )
This routine removes the string name from the semaphore name table, and marks the corresponding semaphore for destruction. An unlinked semaphore is destroyed when the last task closes it with sem_close( ). After a particular name is removed from the table, calls to sem_open( ) using the same name cannot connect to the same semaphore, even if other tasks are still using it. Instead, such calls refer to a new semaphore with the same name.
0 (OK), or -1 (ERROR) if unsuccessful.
ENAMETOOLONG
- semaphore name too long.
ENOENT
- named semaphore does not exist.
semPxLib, sem_open( ), sem_close( )
sem_wait( ) - lock (take) a semaphore, blocking if not available (POSIX)
int sem_wait ( sem_t * sem /* semaphore descriptor */ )
This routine locks the semaphore referenced by sem by performing the semaphore lock operation on that semaphore. If the semaphore value is currently zero, the calling task will not return from the call to sem_wait( ) until it either locks the semaphore or the call is interrupted by a signal.
On return, the state of the semaphore is locked and will remain locked until sem_post( ) is executed and returns successfully.
Deadlock detection is not implemented.
Note that the POSIX term lock corresponds to the term take used in other VxWorks documentation regarding semaphores.
0 (OK), or -1 (ERROR) if unsuccessful.
EINVAL
- invalid semaphore descriptor, or semaphore destroyed while task waiting.
semPxLib, sem_trywait( ), sem_post( )
sem_trywait( ) - lock (take) a semaphore, returning error if unavailable (POSIX)
int sem_trywait ( sem_t * sem /* semaphore descriptor */ )
This routine locks the semaphore referenced by sem only if the semaphore is currently not locked; that is, if the semaphore value is currently positive. Otherwise, it does not lock the semaphore. In either case, this call returns immediately without blocking.
Upon return, the state of the semaphore is always locked (either as a result of this call or by a previous sem_wait( ) or sem_trywait( )). The semaphore will remain locked until sem_post( ) is executed and returns successfully.
Deadlock detection is not implemented.
Note that the POSIX term lock corresponds to the term take used in other VxWorks semaphore documentation.
0 (OK), or -1 (ERROR) if unsuccessful.
EAGAIN
- semaphore is already locked.
EINVAL
- invalid semaphore descriptor.
semPxLib, sem_wait( ), sem_post( )
sem_post( ) - unlock (give) a semaphore (POSIX)
int sem_post ( sem_t * sem /* semaphore descriptor */ )
This routine unlocks the semaphore referenced by sem by performing the semaphore unlock operation on that semaphore.
If the semaphore value resulting from the operation is positive, then no tasks were blocked waiting for the semaphore to become unlocked; the semaphore value is simply incremented.
If the value of the semaphore resulting from this semaphore is zero, then one of the tasks blocked waiting for the semaphore will return successfully from its call to sem_wait( ).
The _POSIX_PRIORITY_SCHEDULING functionality is not yet supported.
Note that the POSIX terms unlock and post correspond to the term give used in other VxWorks semaphore documentation.
0 (OK), or -1 (ERROR) if unsuccessful.
EINVAL
- invalid semaphore descriptor.
semPxLib, sem_wait( ), sem_trywait( )
sem_getvalue( ) - get the value of a semaphore (POSIX)
int sem_getvalue ( sem_t * sem, /* semaphore descriptor */ int * sval /* buffer by which the value is returned */ )
This routine updates the location referenced by the sval argument to have the value of the semaphore referenced by sem without affecting the state of the semaphore. The updated value represents an actual semaphore value that occurred at some unspecified time during the call, but may not be the actual value of the semaphore when it is returned to the calling task.
If sem is locked, the value returned by sem_getvalue( ) will either be zero or a negative number whose absolute value represents the number of tasks waiting for the semaphore at some unspecified time during the call.
0 (OK), or -1 (ERROR) if unsuccessful.
EINVAL
- invalid semaphore descriptor.
semPxLib, sem_post( ), sem_trywait( ), sem_trywait( )