Semaphores services. More...

Collaboration diagram for Semaphores services.:

Functions
int	sem_init (sem_t *sm, int pshared, unsigned value)
	Initialize an unnamed semaphore. More...

int	sem_destroy (sem_t *sm)
	Destroy an unnamed semaphore. More...

sem_t *	sem_open (const char *name, int oflags,...)
	Open a named semaphore. More...

int	sem_close (sem_t *sm)
	Close a named semaphore. More...

int	sem_unlink (const char *name)
	Unlink a named semaphore. More...

int	sem_trywait (sem_t *sm)
	Attempt to lock a semaphore. More...

int	sem_wait (sem_t *sm)
	Lock a semaphore. More...

int	sem_timedwait (sem_t sm, const struct timespec abs_timeout)
	Attempt, during a bounded time, to lock a semaphore. More...

int	sem_post (sem_t *sm)
	Unlock a semaphore. More...

int	sem_getvalue (sem_t sm, int value)
	Get the value of a semaphore. More...

Detailed Description

Semaphores services.

Semaphores are counters for resources shared between threads. The basic operations on semaphores are: increment the counter atomically, and wait until the counter is non-null and decrement it atomically.

Semaphores have a maximum value past which they cannot be incremented. The macro SEM_VALUE_MAX is defined to be this maximum value.

Function Documentation

int sem_close ( sem_t * sm )

Close a named semaphore.

This service closes the semaphore sm. The semaphore is destroyed only when unlinked with a call to the sem_unlink() service and when each call to sem_open() matches a call to this service.

When a semaphore is destroyed, the memory it used is returned to the system heap, so that further references to this semaphore are not guaranteed to fail, as is the case for unnamed semaphores.

This service fails if sm is an unnamed semaphore.

Parameters

sm	the semaphore to be closed.

Return values

0	on success;
-1	with errno set if: EINVAL, the semaphore sm is invalid or is an unnamed semaphore.

See also: Specification.

int sem_destroy ( sem_t * sm )

Destroy an unnamed semaphore.

This service destroys the semaphore sm. Threads currently blocked on sm are unblocked and the service they called return -1 with errno set to EINVAL. The semaphore is then considered invalid by all semaphore services (they all fail with errno set to EINVAL) except sem_init().

This service fails if sm is a named semaphore.

Parameters

sm	the semaphore to be destroyed.

Return values

0	on success,
-1	with errno set if: EINVAL, the semaphore sm is invalid or a named semaphore; EPERM, the semaphore sm is not process-shared and does not belong to the current process.

See also: Specification.

int sem_getvalue	(	sem_t *	sm,
		int *	value
	)

Get the value of a semaphore.

This service stores at the address value, the current count of the semaphore sm. The state of the semaphore is unchanged.

If the semaphore is currently locked, the value stored is zero.

Parameters

sm	a semaphore;
value	address where the semaphore count will be stored on success.

Return values

0	on success;
-1	with errno set if: EINVAL, the semaphore is invalid or uninitialized; EPERM, the semaphore sm is not process-shared and does not belong to the current process.

See also: Specification.

int sem_init	(	sem_t *	sm,
		int	pshared,
		unsigned	value
	)

Initialize an unnamed semaphore.

This service initializes the semaphore sm, with the value value.

This service fails if sm is already initialized or is a named semaphore.

Parameters

sm	the semaphore to be initialized;
pshared	if zero, means that the new semaphore may only be used by threads in the same process as the thread calling sem_init(); if non zero, means that the new semaphore may be used by any thread that has access to the memory where the semaphore is allocated.
value	the semaphore initial value.

Return values

0	on success,
-1	with errno set if: EBUSY, the semaphore sm was already initialized; ENOSPC, insufficient memory exists in the system heap to initialize the semaphore, increase CONFIG_XENO_OPT_SYS_HEAPSZ; EINVAL, the value argument exceeds SEM_VALUE_MAX.

See also: Specification.

Referenced by rtdm_sem_init().

sem_t* sem_open	(	const char *	name,
		int	oflags,
			...
	)

Open a named semaphore.

This service establishes a connection between the semaphore named name and the calling context (kernel-space as a whole, or user-space process).

If no semaphore named name exists and oflags has the O_CREAT bit set, the semaphore is created by this function, using two more arguments:

a mode argument, of type mode_t, currently ignored;
a value argument, of type unsigned, specifying the initial value of the created semaphore.

If oflags has the two bits O_CREAT and O_EXCL set and the semaphore already exists, this service fails.

name may be any arbitrary string, in which slashes have no particular meaning. However, for portability, using a name which starts with a slash and contains no other slash is recommended.

If sem_open() is called from the same context (kernel-space as a whole, or user-space process) several times with the same value of name, the same address is returned.

Parameters

name	the name of the semaphore to be created;
oflags	flags.

Returns

the address of the named semaphore on success;

SEM_FAILED with errno set if:

ENAMETOOLONG, the length of the name argument exceeds 64 characters;
EEXIST, the bits O_CREAT and O_EXCL were set in oflags and the named semaphore already exists;
ENOENT, the bit O_CREAT is not set in oflags and the named semaphore does not exist;
ENOSPC, insufficient memory exists in the system heap to create the semaphore, increase CONFIG_XENO_OPT_SYS_HEAPSZ;
EINVAL, the value argument exceeds SEM_VALUE_MAX.

See also: Specification.

int sem_post ( sem_t * sm )

Unlock a semaphore.

This service unlocks the semaphore sm.

If no thread is currently blocked on this semaphore, its count is incremented, otherwise the highest priority thread is unblocked.

Parameters

sm	the semaphore to be unlocked.

Return values

0	on success;
-1	with errno set if: EINVAL, the specified semaphore is invalid or uninitialized; EPERM, the semaphore sm is not process-shared and does not belong to the current process; EAGAIN, the semaphore count is SEM_VALUE_MAX.

See also: Specification.

References xnpod_schedule(), and xnsynch_wakeup_one_sleeper().

int sem_timedwait	(	sem_t *	sm,
		const struct timespec *	abs_timeout
	)

Attempt, during a bounded time, to lock a semaphore.

This serivce is equivalent to sem_wait(), except that the caller is only blocked until the timeout abs_timeout expires.

Parameters

sm	the semaphore to be locked;
abs_timeout	the timeout, expressed as an absolute value of the CLOCK_REALTIME clock.

Return values

0 on success;

-1

with errno set if:

EPERM, the caller context is invalid;
EINVAL, the semaphore is invalid or uninitialized;
EINVAL, the specified timeout is invalid;
EPERM, the semaphore sm is not process-shared and does not belong to the current process;
EINTR, the caller was interrupted by a signal while blocked in this service;
ETIMEDOUT, the semaphore could not be locked and the specified timeout expired.

Valid contexts:

Xenomai kernel-space thread,
Xenomai user-space thread (switches to primary mode).

See also: Specification.

Referenced by rtdm_sem_timeddown().

int sem_trywait ( sem_t * sm )

Attempt to lock a semaphore.

This service is equivalent to sem_wait(), except that it returns immediately if the semaphore sm is currently locked, and that it is not a cancellation point.

Parameters

sm	the semaphore to be locked.

Return values

0	on success;
-1	with errno set if: EINVAL, the specified semaphore is invalid or uninitialized; EPERM, the semaphore sm is not process-shared and does not belong to the current process; EAGAIN, the specified semaphore is currently locked.

See also: Specification.

int sem_unlink ( const char * name )

Unlink a named semaphore.

This service unlinks the semaphore named name. This semaphore is not destroyed until all references obtained with sem_open() are closed by calling sem_close(). However, the unlinked semaphore may no longer be reached with the sem_open() service.

When a semaphore is destroyed, the memory it used is returned to the system heap, so that further references to this semaphore are not guaranteed to fail, as is the case for unnamed semaphores.

Parameters

name	the name of the semaphore to be unlinked.

Return values

0	on success;
-1	with errno set if: ENAMETOOLONG, the length of the name argument exceeds 64 characters; ENOENT, the named semaphore does not exist.

See also: Specification.

int sem_wait ( sem_t * sm )

Lock a semaphore.

This service locks the semaphore sm if it is currently unlocked (i.e. if its value is greater than 0). If the semaphore is currently locked, the calling thread is suspended until the semaphore is unlocked, or a signal is delivered to the calling thread.

This service is a cancellation point for Xenomai POSIX skin threads (created with the pthread_create() service). When such a thread is cancelled while blocked in a call to this service, the semaphore state is left unchanged before the cancellation cleanup handlers are called.

Parameters

sm	the semaphore to be locked.

Return values

0	on success;
-1	with errno set if: EPERM, the caller context is invalid; EINVAL, the semaphore is invalid or uninitialized; EPERM, the semaphore sm is not process-shared and does not belong to the current process; EINTR, the caller was interrupted by a signal while blocked in this service.

Valid contexts:

Xenomai kernel-space thread,
Xenomai user-space thread (switches to primary mode).

See also: Specification.

Functions

Detailed Description

Function Documentation