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