share/man/man3/sigevent.3

   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 July 15, 2016
  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
  37 Some operations permit threads to request asychronous notification of events
  38 via a
  39 .Vt struct sigevent
  40 structure.
  41 This 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
  49 file 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
  53 callback function pointer
  54 .It Vt pthread_attr_t * Ta sigev_notify_attributes Ta
  55 callback thread attributes
  56 .El
  57 .Pp
  58 The
  59 .Va sigev_notify
  60 field specifies the notification method used when the event triggers:
  61 .Bl -tag -width ".Dv SIGEV_THREAD_ID"
  62 .It Dv SIGEV_NONE
  63 No notification is sent.
  64 .It Dv SIGEV_SIGNAL
  65 The signal
  66 .Va sigev_signo
  67 is queued as a real-time signal to the calling process.
  68 The value stored in
  69 .Va sigev_value
  70 will be present in the
  71 .Va si_value
  72 of the
  73 .Vt siginfo_t
  74 structure of the queued signal.
  75 .It Dv SIGEV_THREAD
  76 The notification function in
  77 .Va sigev_notify_function
  78 is called in a separate thread context.
  79 The thread is created with the attributes specified in
  80 .Va *sigev_notify_attributes .
  81 The value stored in
  82 .Va sigev_value
  83 is passed as the sole argument to
  84 .Va sigev_notify_function .
  85 If
  86 .Va sigev_notify_attributes
  87 is
  88 .Dv NULL ,
  89 the thread is created with default attributes.
  90 .It Dv SIGEV_KEVENT
  91 A new kevent is posted to the kqueue
  92 .Va sigev_notify_kqueue .
  93 The
  94 .Va udata
  95 member of the kevent structure contains the value stored in
  96 .Va sigev_value .
  97 The meaning of other fields in the kevent are specific to the type of triggered
  98 event.
  99 .It Dv SIGEV_THREAD_ID
 100 The signal
 101 .Va sigev_signo
 102 is queued to the thread whose LWP ID is
 103 .Va sigev_notify_thread_id .
 104 The value stored in
 105 .Va sigev_value
 106 will be present in the
 107 .Va si_value
 108 of the
 109 .Vt siginfo_t
 110 structure of the queued signal.
 111 .El
 112 .Sh NOTES
 113 Note that programs wishing to use
 114 .Dv SIGEV_THREAD
 115 notifications 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 STANDARDS
 123 The
 124 .Vt struct sigevent
 125 type conforms to
 126 .St -p1003.1-2004 .