1.\" $NetBSD: sigevent.3,v 1.8 2010/06/24 04:21:58 jruoho Exp $ 2.\" 3.\" Copyright (c) 2010 Jukka Ruohonen <jruohonen@iki.fi> 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 15.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 16.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 17.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 18.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 19.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 20.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 21.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 22.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 23.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 24.\" POSSIBILITY OF SUCH DAMAGE. 25.\" 26.Dd June 24, 2010 27.Dt SIGEVENT 3 28.Os 29.Sh NAME 30.Nm sigevent 31.Nd signal event structure 32.Sh SYNOPSIS 33.In sys/signal.h 34.Sh DESCRIPTION 35The 36.St -p1003.1-2004 37standard extends traditional 38.Tn UNIX 39signal semantics by providing facilities 40for realtime signal generation and delivery. 41.Pp 42.\" 43.\" XXX: Remove once these are fixed. 44.\" 45.Bf -symbolic 46Please note that this manual describes an interface that 47is not yet fully functional in 48.Nx : 49neither realtime signals nor SIGEV_THREAD 50are currently supported. 51.Ef 52.Pp 53Realtime functions that can generate realtime signals include: 54.Bl -enum -offset 3n 55.It 56Completion of asynchronous 57.Tn I/O ; 58see 59.Xr aio 3 . 60.It 61Expiration of per-process timers; see 62.Xr timer_create 2 . 63.It 64Arrival of a message to an empty message queue; see 65.Xr mq_notify 3 . 66.El 67.Pp 68The 69.In sys/signal.h 70header, included by 71.In signal.h , 72defines a 73.Va sigevent 74structure, which is the cornerstone in 75asynchronous delivery of realtime signals. 76This structure is defined as: 77.Bd -literal -offset indent 78struct sigevent { 79 int sigev_notify; 80 int sigev_signo; 81 union sigval sigev_value; 82 void (*sigev_notify_function)(union sigval); 83 void *sigev_notify_attributes; 84}; 85.Ed 86.Pp 87The included union is further defined in 88.In siginfo.h 89as: 90.Bd -literal -offset indent 91typedef union sigval { 92 int sival_int; 93 void *sival_ptr; 94} sigval_t; 95.Ed 96.Pp 97The 98.Va sigev_notify 99integer defines the action taken when 100a notification such as timer expiration occurs. 101The possiblue values are: 102.Bl -tag -width "SIGEV_THREAD " -offset 2n 103.It Dv SIGEV_NONE 104This constant specifies a 105.Dq null 106handler: when a notification arrives, nothing happens. 107.It Dv SIGEV_SIGNAL 108The 109.Dv SIGEV_SIGNAL 110constant specifies that notifications are delivered by signals. 111When a notification arrives, the kernel sends the signal specified in 112.Va sigev_signo . 113.Pp 114In the signal handler the 115.Sq si_value 116of 117.Va siginfo_t 118is set to the value specified by the 119.Va sigev_value . 120In another words, the 121.Va sigev_value 122member is an application-defined value to be passed to 123a particular signal handler at the time of signal delivery. 124Depending whether the specified value is an integer or a pointer, the 125delivered value can be either 126.Va sigval_intr 127or 128.Va sigval_ptr . 129.It Dv SIGEV_THREAD 130This constant specifies a thread-driven notification mechanism. 131When a notification occurs, the kernel creates a new thread that starts 132executing the function specified in the function pointer 133.Va sigev_notify_function . 134The single argument passed to the function is specified in 135.Va sigev_value . 136.Pp 137If 138.Va sigev_notify_attributes 139is not 140.Dv NULL , 141the provided attribute specifies the behavior of the thread; see 142.Xr pthread_attr 3 . 143(Note that although a pointer to void is specified for 144.Va sigev_notify_attributes , 145the type is 146.Va pthread_attr_t 147in practice.) 148.Pp 149The threads are created as detached, 150or in an unspecified way if 151.Xr pthread_attr_setdetachstate 3 152is used with 153.Va sigev_notify_attributes 154to set 155.Dv PTHREAD_CREATE_JOINABLE . 156It is not valid to call 157.Xr pthread_join 3 158in either case. 159Hence, it is impossible to determine the lifetime of the created thread. 160This in turn means that it is neither possible to recover the memory nor 161the address of the memory possibly dedicated as thread stack via 162.Fn pthread_attr_setstack 163or 164.Fn pthread_attr_setstackaddr . 165.El 166.\" 167.\" .Sh EXAMPLES 168.\" 169.\" XXX: Add one. 170.\" 171.Sh SEE ALSO 172.Xr siginfo 2 , 173.Xr timer_create 2 , 174.Xr aio 3 , 175.Xr mq 3 176.Sh HISTORY 177The 178.Va sigevent 179structure first appeared in 180.Nx 1.6 . 181