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.\" $FreeBSD$ 27.\" 28.Dd February 25, 2020 29.Dt SIGEVENT 3 30.Os 31.Sh NAME 32.Nm sigevent 33.Nd "asynchronous event notification" 34.Sh SYNOPSIS 35.In signal.h 36.Sh DESCRIPTION 37Some operations permit threads to request asychronous notification of events 38via a 39.Vt struct sigevent 40structure. 41This structure contains several fields that describe the requested notification: 42.Bl -column ".Vt void (*)(union sigval)" ".Va sigev_notify_kevent_flags" 43.It Sy Type Ta Sy Member Ta Sy Description 44.It Vt int Ta sigev_notify Ta notification method 45.It Vt int Ta sigev_signo Ta signal number 46.It Vt union sigval Ta sigev_value Ta signal value 47.It Vt int Ta sigev_notify_kqueue Ta 48.Xr kqueue 2 49file descriptor 50.It Vt unsigned short Ta sigev_notify_kevent_flags Ta kevent flags 51.It Vt lwpid_t Ta sigev_notify_thread_id Ta LWP ID 52.It Vt void (*)(union sigval) Ta sigev_notify_function Ta 53callback function pointer 54.It Vt pthread_attr_t * Ta sigev_notify_attributes Ta 55callback thread attributes 56.El 57.Pp 58The 59.Va sigev_notify 60field specifies the notification method used when the event triggers: 61.Bl -tag -width ".Dv SIGEV_THREAD_ID" 62.It Dv SIGEV_NONE 63No notification is sent. 64.It Dv SIGEV_SIGNAL 65The signal 66.Va sigev_signo 67is queued as a real-time signal to the calling process. 68The value stored in 69.Va sigev_value 70will be present in the 71.Va si_value 72of the 73.Vt siginfo_t 74structure of the queued signal. 75.It Dv SIGEV_THREAD 76The notification function in 77.Va sigev_notify_function 78is called in a separate thread context. 79The thread is created with the attributes specified in 80.Va *sigev_notify_attributes . 81The value stored in 82.Va sigev_value 83is passed as the sole argument to 84.Va sigev_notify_function . 85If 86.Va sigev_notify_attributes 87is 88.Dv NULL , 89the thread is created with default attributes. 90.It Dv SIGEV_KEVENT 91A new kevent is posted to the kqueue 92.Va sigev_notify_kqueue . 93The 94.Va udata 95member of the kevent structure contains the value stored in 96.Va sigev_value . 97The meaning of other fields in the kevent are specific to the type of triggered 98event. 99.It Dv SIGEV_THREAD_ID 100The signal 101.Va sigev_signo 102is queued to the thread whose LWP ID is 103.Va sigev_notify_thread_id . 104The value stored in 105.Va sigev_value 106will be present in the 107.Va si_value 108of the 109.Vt siginfo_t 110structure of the queued signal. 111.El 112.Sh NOTES 113Note that programs wishing to use 114.Dv SIGEV_THREAD 115notifications must link against the 116.Lb librt . 117.Sh SEE ALSO 118.Xr aio_read 2 , 119.Xr mq_notify 2 , 120.Xr timer_create 2 , 121.Xr siginfo 3 122.Sh HISTORY 123The 124.Va sigevent 125structure first appeared in 126.Fx 3.3 . 127.Sh STANDARDS 128The 129.Vt struct sigevent 130type conforms to 131.St -p1003.1-2004 . 132