SIGEVENT(3)

SIGEVENT(3) | Library Functions Manual | SIGEVENT(3)

# NAME

`sigevent` —
signal event structure

# SYNOPSIS

`#include <sys/signal.h>`

# DESCRIPTION

The IEEE Std 1003.1-2004 (“POSIX.1”) standard extends traditional UNIX signal semantics by providing facilities for realtime signal generation and delivery.

Please note that this manual describes an interface that is not yet fully functional in NetBSD: neither realtime signals nor SIGEV_THREAD are currently supported.

Realtime functions that can generate realtime signals include:

1. Completion of asynchronous I/O; see aio(3).
2. Expiration of per-process timers; see timer_create(2).
3. Arrival of a message to an empty message queue; see mq_notify(3).

The `<sys/signal.h>` header, included by `<signal.h>`, defines a sigevent structure, which is the cornerstone in asynchronous delivery of realtime signals. This structure is defined as:

    struct sigevent {
    	int		  sigev_notify;
    	int		  sigev_signo;
    	union sigval	  sigev_value;
    	void		(*sigev_notify_function)(union sigval);
    	void		 *sigev_notify_attributes;
    };

The included union is further defined in `<siginfo.h>` as:

    typedef union sigval {
    	int	 sival_int;
    	void	*sival_ptr;
    } sigval_t;

The sigev_notify integer defines the action taken when a notification such as timer expiration occurs. The possiblue values are:

`SIGEV_NONE`
  This constant specifies a “null” handler: when a notification arrives, nothing happens.
`SIGEV_SIGNAL`
  The `SIGEV_SIGNAL` constant specifies that notifications are delivered by signals. When a notification arrives, the kernel sends the signal specified in sigev_signo.

  In the signal handler the ‘si_value’ of siginfo_t is set to the value specified by the sigev_value. In another words, the sigev_value member is an application-defined value to be passed to a particular signal handler at the time of signal delivery. Depending whether the specified value is an integer or a pointer, the delivered value can be either sigval_intr or sigval_ptr.

`SIGEV_THREAD`
  This constant specifies a thread-driven notification mechanism. When a notification occurs, the kernel creates a new thread that starts executing the function specified in the function pointer sigev_notify_function. The single argument passed to the function is specified in sigev_value.

  If sigev_notify_attributes is not `NULL`, the provided attribute specifies the behavior of the thread; see pthread_attr(3). (Note that although a pointer to void is specified for sigev_notify_attributes, the type is pthread_attr_t in practice.)

  The threads are created as detached, or in an unspecified way if pthread_attr_setdetachstate(3) is used with sigev_notify_attributes to set `PTHREAD_CREATE_JOINABLE`. It is not valid to call pthread_join(3) in either case. Hence, it is impossible to determine the lifetime of the created thread. This in turn means that it is neither possible to recover the memory nor the address of the memory possibly dedicated as thread stack via `pthread_attr_setstack`() or `pthread_attr_setstackaddr`().

# SEE ALSO

siginfo(2), timer_create(2), aio(3), mq(3)

# HISTORY

The sigevent structure first appeared in NetBSD 1.6.

June 24, 2010 | NetBSD 9.5