share/man/man3/sigevent.3

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