Signals management services. More...

Collaboration diagram for Signals services.:

Functions
int	sigemptyset (sigset_t *set)
	Initialize and empty a signal set. More...

int	sigfillset (sigset_t *set)
	Initialize and fill a signal set. More...

int	sigaddset (sigset_t *set, int sig)
	Add a signal to a signal set. More...

int	sigdelset (sigset_t *set, int sig)
	Delete a signal from a signal set. More...

int	sigismember (const sigset_t *set, int sig)
	Test for a signal in a signal set. More...

int	sigaction (int sig, const struct sigaction act, struct sigaction oact)
	Examine and change a signal action. More...

int	pthread_kill (pthread_t thread, int sig)
	Send a signal to a thread. More...

int	pthread_sigqueue_np (pthread_t thread, int sig, union sigval value)
	Queue a signal to a thread. More...

int	sigpending (sigset_t *set)
	Examine pending signals. More...

int	pthread_sigmask (int how, const sigset_t set, sigset_t oset)
	Examine and change the set of signals blocked by a thread. More...

int	sigwait (const sigset_t set, int sig)
	Wait for signals. More...

int	sigwaitinfo (const sigset_t __restrict__ set, siginfo_t __restrict__ info)
	Wait for signals. More...

int	sigtimedwait (const sigset_t __restrict__ set, siginfo_t __restrict__ info, const struct timespec *__restrict__ timeout)
	Wait during a bounded time for signals. More...

Detailed Description

Signals management services.

Signals are asynchronous notifications delivered to a process or thread. Such notifications occur as the result of an exceptional event or at the request of another process.

The services documented here are reserved to Xenomai kernel-space threads, user-space threads switch to secondary mode when handling signals, and use Linux regular signals services.

Xenomai POSIX skin signals are implemented as real-time signals, meaning that they are queued when posted several times to a thread before the first notification is handled, and that each signal carry additional data in a siginfo_t object. In order to ensure consistence with user-space signals, valid signals number range from 1 to SIGRTMAX, signals from SIGRTMIN to SIGRTMAX being higher priority than signals from 1 to SIGRTMIN-1. As a special case, signal 0 may be used with services pthread_kill() and pthread_sigqueue_np() to check if a thread exists, but entails no other action.

The action to be taken upon reception of a signal depends on the thread signal mask, (see pthread_sigmask()), and on the settings described by a sigaction structure (see sigaction()).

Function Documentation

int pthread_kill	(	pthread_t	thread,
		int	sig
	)

Send a signal to a thread.

This service send the signal sig to the Xenomai POSIX skin thread thread (created with pthread_create()). If sig is zero, this service check for existence of the thread thread, but no signal is sent.

Parameters

thread	thread identifier;
sig	signal number.

Returns

0 on success;

an error number if:

EINVAL, sig is an invalid signal number;
EAGAIN, the maximum number of pending signals has been exceeded;
ESRCH, thread is an invalid thread identifier.

See also: Specification.

Examples:: rtcan_rtt.c.

References XNBREAK, xnpod_resume_thread(), xnpod_schedule(), xnpod_suspend_thread(), xnpod_unblock_thread(), and XNSUSP.

int pthread_sigmask	(	int	how,
		const sigset_t *	set,
		sigset_t *	oset
	)

Examine and change the set of signals blocked by a thread.

The signal mask of a thread is the set of signals that are blocked by this thread.

If oset is not NULL, this service stores, at the address oset the current signal mask of the calling thread.

If set is not NULL, this service sets the signal mask of the calling thread according to the value of how, as follow:

if how is SIG_BLOCK, the signals in set are added to the calling thread signal mask;
if how is SIG_SETMASK, the calling thread signal mask is set to set;
if how is SIG_UNBLOCK, the signals in set are removed from the calling thread signal mask.

If some signals are unblocked by this service, they are handled before this service returns.

Parameters

how	if set is not null, a value indicating how to interpret set;
set	if not null, a signal set that will be used to modify the calling thread signal mask;
oset	if not null, address where the previous value of the calling thread signal mask will be stored on success.

Returns

0 on success;

an error number if:

EPERM, the calling context is invalid;
EINVAL, how is not SIG_BLOCK, SIG_UNBLOCK or SIG_SETMASK.

Valid contexts:

Xenomai POSIX skin kernel-space thread.

See also: Specification.

References xnpod_schedule().

int pthread_sigqueue_np	(	pthread_t	thread,
		int	sig,
		union sigval	value
	)

Queue a signal to a thread.

This service send the signal sig to the Xenomai POSIX skin thread thread (created with pthread_create()), with the value value. If sig is zero, this service check for existence of the thread thread, but no signal is sent.

This service is equivalent to the POSIX service sigqueue(), except that the signal is directed to a thread instead of being directed to a process.

Parameters

thread	thread identifier,
sig	signal number,
value	additional datum passed to thread with the signal sig.

Returns

0 on success;

an error number if:

EINVAL, sig is an invalid signal number;
EAGAIN, the maximum number of pending signals has been exceeded;
ESRCH, thread is an invalid thread identifier.

See also: sigqueue() specification.

References xnpod_schedule().

int sigaction	(	int	sig,
		const struct sigaction *	act,
		struct sigaction *	oact
	)

Examine and change a signal action.

The sigaction structure descibes the actions to be taken upon signal delivery. A sigaction structure is associated with every signal, for the kernel-space as a whole.

If oact is not NULL, this service returns at the address oact, the current value of the sigaction structure associated with the signal sig.

If act is not NULL, this service set to the value pointed to by act, the sigaction structure associated with the signal sig.

The structure sigaction has the following members:

sa_flags, is a bitwise OR of the flags;
- SA_RESETHAND, meaning that the signal handler will be reset to SIG_GFL and SA_SIGINFO cleared upon reception of a signal,
- SA_NODEFER, meaning that the signal handler will be called with the signal sig not masked when handling the signal sig,
- SA_SIGINFO, meaning that the member sa_sigaction of the sigaction structure will be used as a signal handler instead of sa_handler
sa_mask, of type sigset_t, is the value to which the thread signals mask will be set during execution of the signal handler (sig is automatically added to this set if SA_NODEFER is not set in sa_flags);
sa_handler, of type void (*)(int) is the signal handler which will be called upon signal delivery if SA_SIGINFO is not set in sa_flags, or one of SIG_IGN or SIG_DFL, meaning that the signal will be respectively ignored or handled with the default handler;
sa_sigaction, of type void (*)(int, siginfo_t *, void *) is the signal handler which will be called upon signal delivery if SA_SIGINFO is set in sa_flags.

When using sa_handler as a signal handler, it is passed the number of the received signal, when using sa_sigaction, two additional arguments are passed:

a pointer to a siginfo_t object, containing additional information about the received signal;
a void pointer, always null in this implementation.

The following members of the siginfo_t structure are filled by this implementation:

si_signo, the signal number;
si_code, the provenance of the signal, one of:
- SI_QUEUE, the signal was queued with pthread_sigqueue_np(),
- SI_USER, the signal was queued with pthread_kill(),
- SI_TIMER, the signal was queued by a timer (see timer_settime()),
- SI_MESQ, the signal was queued by a message queue (see mq_notify());
si_value, an additional datum, of type union sigval.

Parameters

sig	a signal number;
act	if not null, description of the action to be taken upon notification of the signal sig;
oact	if not null, address where the previous description of the signal action is stored on success.

Return values

0	on sucess;
-1	with errno set if: EINVAL, sig is an invalid signal number; ENOTSUP, the sa_flags member of act contains other flags than SA_RESETHAND, SA_NODEFER and SA_SIGINFO;

See also: Specification.

int sigaddset	(	sigset_t *	set,
		int	sig
	)

Add a signal to a signal set.

This service adds the signal number sig to the signal set pointed to by set.

Parameters

set	address of a signal set;
sig	signal to be added to set.

Return values

0	on success;
-1	with errno set if: EINVAL, sig is not a valid signal number.

See also: Specification.

int sigdelset	(	sigset_t *	set,
		int	sig
	)

Delete a signal from a signal set.

This service remove the signal number sig from the signal set pointed to by set.

Parameters

set	address of a signal set;
sig	signal to be removed from set.

Return values

0	on success;
-1	with errno set if: EINVAL, sig is not a valid signal number.

See also: Specification.

int sigemptyset ( sigset_t * set )

Initialize and empty a signal set.

This service initializes ane empties the signal set pointed to by set.

Parameters

set	address of a the signal set to be initialized.

Return values

0

See also: Specification.

int sigfillset ( sigset_t * set )

Initialize and fill a signal set.

This service initializes ane fills the signal set pointed to by set.

Parameters

set	address of a the signal set to be filled.

Return values

0

See also: Specification.

int sigismember	(	const sigset_t *	set,
		int	sig
	)

Test for a signal in a signal set.

This service tests whether the signal number sig is member of the signal set pointed to by set.

Parameters

set	address of a signal set;
sig	tested signal number.

Return values

0	on success;
-1	with errno set if: EINVAL, sig is not a valid signal number.

See also: Specification.

int sigpending ( sigset_t * set )

Examine pending signals.

This service stores, at the address set, the set of signals that are currently blocked and have been received by the calling thread.

Parameters

set	address where the set of blocked and received signals are stored on success.

Return values

0	on success;
-1	with errno set if: EPERM, the calling context is invalid.

Valid contexts:

Xenomai POSIX skin kernel-space thread.

See also: Specification.

int sigtimedwait	(	const sigset_t *__restrict__	set,
		siginfo_t *__restrict__	info,
		const struct timespec *__restrict__	timeout
	)

Wait during a bounded time for signals.

This service is equivalent to the sigwaitinfo() service, except that the calling thread is only blocked until the timeout specified by timeout expires.

Parameters

set	set of signals to wait for;
info	address where the received siginfo_t object will be stored on success;
timeout	the timeout, expressed as a time interval.

Return values

0	on success;
-1	with errno set if: EINVAL, the specified timeout is invalid; EPERM, the caller context is invalid; EINVAL, a signal in set is not currently blocked; EAGAIN, no signal was received and the specified timeout expired.

Valid contexts:

Xenomai POSIX skin kernel-space thread.

See also: Specification.

int sigwait	(	const sigset_t *	set,
		int *	sig
	)

Wait for signals.

This service blocks a Xenomai kernel-space POSIX skin thread until a signal of the set set is received. If a signal in set is not currently blocked by the calling thread, this service returns immediately with an error. The signal received is stored at the address sig.

If a signal of the set set was already pending, it is cleared and this service returns immediately.

Signals are received in priority order, i.e. from SIGRTMIN to SIGRTMAX, then from 1 to SIGRTMIN-1.

Parameters

set	set of signals to wait for;
sig	address where the received signal will be stored on success.

Returns

0 on success;

an error number if:

EPERM, the caller context is invalid;
EINVAL, a signal in set is not currently blocked.

Valid contexts:

Xenomai POSIX skin kernel-space thread.

See also: Specification.

int sigwaitinfo	(	const sigset_t *__restrict__	set,
		siginfo_t *__restrict__	info
	)

Wait for signals.

This service is equivalent to the sigwait() service, except that it returns, at the address info, the siginfo_t object associated with the received signal instead of only returning the signal number.

Parameters

set	set of signals to wait for;
info	address where the received siginfo_t object will be stored on success.

Return values

0	on success;
-1	with errno set if: EPERM, the caller context is invalid; EINVAL, a signal in set is not currently blocked.

Valid contexts:

Xenomai POSIX skin kernel-space thread.

See also: Specification.

Functions

Detailed Description

Function Documentation