1.\" -*- nroff -*- 2.\" 3.\" Copyright (c) 2016 John H. Baldwin <jhb@FreeBSD.org> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.\" $FreeBSD$ 28.\" 29.Dd July 15, 2016 30.Dt SIGEVENT 3 31.Os 32.Sh NAME 33.Nm sigevent 34.Nd "asynchronous event notification" 35.Sh SYNOPSIS 36.In signal.h 37.Sh DESCRIPTION 38Some operations permit threads to request asychronous notification of events 39via a 40.Vt struct sigevent 41structure. 42This structure contains several fields that describe the requested notification: 43.Bl -column ".Vt void (*)(union sigval)" ".Va sigev_notify_kevent_flags" 44.It Sy Type Ta Sy Member Ta Sy Description 45.It Vt int Ta sigev_notify Ta notification method 46.It Vt int Ta sigev_signo Ta signal number 47.It Vt union sigval Ta sigev_value Ta signal value 48.It Vt int Ta sigev_notify_kqueue Ta 49.Xr kqueue 2 50file descriptor 51.It Vt unsigned short Ta sigev_notify_kevent_flags Ta kevent flags 52.It Vt lwpid_t Ta sigev_notify_thread_id Ta LWP ID 53.It Vt void (*)(union sigval) Ta sigev_notify_function Ta 54callback function pointer 55.It Vt pthread_attr_t * Ta sigev_notify_attributes Ta 56callback thread attributes 57.El 58.Pp 59The 60.Va sigev_notify 61field specifies the notification method used when the event triggers: 62.Bl -tag -width ".Dv SIGEV_THREAD_ID" 63.It Dv SIGEV_NONE 64No notification is sent. 65.It Dv SIGEV_SIGNAL 66The signal 67.Va sigev_signo 68is queued as a real-time signal to the calling process. 69The value stored in 70.Va sigev_value 71will be present in the 72.Va si_value 73of the 74.Vt siginfo_t 75structure of the queued signal. 76.It Dv SIGEV_THREAD 77The notification function in 78.Va sigev_notify_function 79is called in a separate thread context. 80The thread is created with the attributes specified in 81.Va *sigev_notify_attributes . 82The value stored in 83.Va sigev_value 84is passed as the sole argument to 85.Va sigev_notify_function . 86If 87.Va sigev_notify_attributes 88is 89.Dv NULL , 90the thread is created with default attributes. 91.It Dv SIGEV_KEVENT 92A new kevent is posted to the kqueue 93.Va sigev_notify_kqueue . 94The 95.Va udata 96member of the kevent structure contains the value stored in 97.Va sigev_value . 98The meaning of other fields in the kevent are specific to the type of triggered 99event. 100.It Dv SIGEV_THREAD_ID 101The signal 102.Va sigev_signo 103is queued to the thread whose LWP ID is 104.Va sigev_notify_thread_id . 105The value stored in 106.Va sigev_value 107will be present in the 108.Va si_value 109of the 110.Vt siginfo_t 111structure of the queued signal. 112.El 113.Sh NOTES 114Note that programs wishing to use 115.Dv SIGEV_THREAD 116notifications must link against the 117.Lb librt . 118.Sh SEE ALSO 119.Xr aio_read 2 , 120.Xr mq_notify 2 , 121.Xr timer_create 2 , 122.Xr siginfo 3 123.Sh STANDARDS 124The 125.Vt struct sigevent 126type conforms to 127.St -p1003.1-2004 . 128