.\" $NetBSD: sigevent.3,v 1.8 2010/06/24 04:21:58 jruoho 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 June 24, 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.
.Pp
.\"
.\" XXX: Remove once these are fixed.
.\"
.Bf -symbolic
Please note that this manual describes an interface that
is not yet fully functional in
.Nx :
neither realtime signals nor SIGEV_THREAD
are currently supported.
.Ef
.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 2 .
.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.)
.Pp
The threads are created as detached,
or in an unspecified way if
.Xr pthread_attr_setdetachstate 3
is used with
.Va sigev_notify_attributes
to set
.Dv PTHREAD_CREATE_JOINABLE .
It is not valid to call
.Xr 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
.Fn pthread_attr_setstack
or
.Fn pthread_attr_setstackaddr .
.El
.\"
.\" .Sh EXAMPLES
.\"
.\" XXX: Add one.
.\"
.Sh SEE ALSO
.Xr siginfo 2 ,
.Xr timer_create 2 ,
.Xr aio 3 ,
.Xr mq 3
.Sh HISTORY
The
.Va sigevent
structure first appeared in
.Nx 1.6 .