.\" $NetBSD: sigevent.3,v 1.2 2010/05/19 06:59:44 wiz Exp $
.\"
.\" Copyright (c) 2010 Jukka Ruohonen <jruohonen@iki.fi>
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd May 18, 2010
.Dt SIGEVENT 3
.Os
.Sh NAME
.Nm sigevent
.Nd signal event structure
.Sh SYNOPSIS
.In sys/signal.h
.Sh DESCRIPTION
The
.St -p1003.1-2004
standard extends traditional
.Tn UNIX
signal semantics by providing facilities
for realtime signal generation and delivery.
.\"
.\" XXX: Remove the paragraph once RT signals are supported.
.\"
Although
.Nx
does not yet support realtime signals,
the described interface is fully functional.
.Pp
Realtime functions that can generate realtime signals include:
.Bl -enum -offset 3n
.It
Completion of asynchronous
.Tn I/O ;
see
.Xr aio 3 .
.It
Expiration of per-process timers; see
.Xr timer_create 3 .
.It
Arrival of a message to an empty message queue; see
.Xr mq_notify 3 .
.El
.Pp
The
.In sys/signal.h
header, included by
.In signal.h ,
defines a
.Va sigevent
structure, which is the cornerstone in
asynchronous delivery of realtime signals.
This structure is defined as:
.Bd -literal -offset indent
struct sigevent {
	int		  sigev_notify;
	int		  sigev_signo;
	union sigval	  sigev_value;
	void		(*sigev_notify_function)(union sigval);
	void		 *sigev_notify_attributes;
};
.Ed
.Pp
The included union is further defined in
.In siginfo.h
as:
.Bd -literal -offset indent
typedef union sigval {
	int	 sival_int;
	void	*sival_ptr;
} sigval_t;
.Ed
.Pp
The
.Va sigev_notify
integer defines the action taken when
a notification such as timer expiration occurs.
The possiblue values are:
.Bl -tag -width "SIGEV_THREAD " -offset 2n
.It Dv SIGEV_NONE
This constant specifies a
.Dq null
handler; when a notification arrives, nothing happens.
.It Dv SIGEV_SIGNAL
The
.Dv SIGEV_SIGNAL
constant specifies that notifications are delivered by signals.
When a notification arrives, the kernel sends the signal specified in
.Va sigev_signo .
.Pp
In the signal handler the
.Sq si_value
of
.Va siginfo_t
is set to the value specified by the
.Va sigev_value .
In another words, the
.Va 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
.Va sigval_intr
or
.Va sigval_ptr .
.It Dv 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
.Va sigev_notify_function .
The single argument passed to the function is specified in
.Va sigev_value .
.Pp
If
.Va sigev_notify_attributes
is not
.Dv NULL ,
the provided attribute specifies the behavior of the thread; see
.Xr pthread_attr 3 .
(Note that although a pointer to void is specified for
.Va sigev_notify_attributes ,
the type is
.Va pthread_attr_t
in practice.)
.El
.\"
.\" .Sh EXAMPLES
.\"
.\" XXX: Add one.
.\"
.Sh SEE ALSO
.Xr siginfo 2 ,
.Xr aio 3 ,
.Xr mq_notify 3 ,
.Xr timer_create 3
.Sh HISTORY
The
.Va sigevent
structure first appeared in
.Nx 1.6 .
.\"
.\" XXX: Remove the paragraph once RT signals are supported.
.\"
.Sh BUGS
Realtime signals are not yet supported.