| 1 |
.\" Copyright 2006-2020, Michael Kerrisk <[email protected]> |
| 2 |
.\" Copyright 2009, Petr Baudis <[email protected]> |
| 3 |
.\" Copyright, the authors of the Linux man-pages project |
| 4 |
.\" |
| 5 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 6 |
.\" |
| 7 |
.TH sigevent 3type 2026-02-08 "Linux man-pages 6.18" |
| 8 |
.SH NAME |
| 9 |
sigevent, sigval \- structure for notification from asynchronous routines |
| 10 |
.SH SYNOPSIS |
| 11 |
.EX |
| 12 |
.B #include <signal.h> |
| 13 |
.P |
| 14 |
.B struct sigevent { |
| 15 |
.BR " int sigev_notify;" " /* Notification type */" |
| 16 |
.BR " int sigev_signo;" " /* Signal number */" |
| 17 |
.BR " union sigval sigev_value;" " /* Data passed with notification */" |
| 18 |
\& |
| 19 |
.B " typeof(void (union sigval)) *sigev_notify_function;" |
| 20 |
.BR " " " /* Notification function" |
| 21 |
.BR " " " (SIGEV_THREAD) */" |
| 22 |
.B " pthread_attr_t *sigev_notify_attributes;" |
| 23 |
.BR " " " /* Notification attributes */" |
| 24 |
\& |
| 25 |
.BR " " "/* Linux only: */" |
| 26 |
.B " pid_t sigev_notify_thread_id;" |
| 27 |
.BR " " " /* ID of thread to signal" |
| 28 |
.BR " " " (SIGEV_THREAD_ID) */" |
| 29 |
.B }; |
| 30 |
.P |
| 31 |
.BR "union sigval {" " /* Data passed with notification */" |
| 32 |
.BR " int sival_int;" " /* Integer value */" |
| 33 |
.BR " void *sival_ptr;" " /* Pointer value */" |
| 34 |
.B }; |
| 35 |
.EE |
| 36 |
.SH DESCRIPTION |
| 37 |
.SS sigevent |
| 38 |
The |
| 39 |
.I sigevent |
| 40 |
structure is used by various APIs |
| 41 |
to describe the way a process is to be notified about an event |
| 42 |
(e.g., completion of an asynchronous request, expiration of a timer, |
| 43 |
or the arrival of a message). |
| 44 |
.P |
| 45 |
The definition shown in the SYNOPSIS is approximate: |
| 46 |
some of the fields in the |
| 47 |
.I sigevent |
| 48 |
structure may be defined as part of a union. |
| 49 |
Programs should employ only those fields relevant |
| 50 |
to the value specified in |
| 51 |
.IR sigev_notify . |
| 52 |
.P |
| 53 |
The |
| 54 |
.I sigev_notify |
| 55 |
field specifies how notification is to be performed. |
| 56 |
This field can have one of the following values: |
| 57 |
.TP |
| 58 |
.B SIGEV_NONE |
| 59 |
A "null" notification: don't do anything when the event occurs. |
| 60 |
.TP |
| 61 |
.B SIGEV_SIGNAL |
| 62 |
Notify the process by sending the signal specified in |
| 63 |
.IR sigev_signo . |
| 64 |
.IP |
| 65 |
If the signal is caught with a signal handler that was registered using the |
| 66 |
.BR sigaction (2) |
| 67 |
.B SA_SIGINFO |
| 68 |
flag, then the following fields are set in the |
| 69 |
.I siginfo_t |
| 70 |
structure that is passed as the second argument of the handler: |
| 71 |
.RS |
| 72 |
.TP 10 |
| 73 |
.I si_code |
| 74 |
This field is set to a value that depends on the API |
| 75 |
delivering the notification. |
| 76 |
.TP |
| 77 |
.I si_signo |
| 78 |
This field is set to the signal number (i.e., the same value as in |
| 79 |
.IR sigev_signo ). |
| 80 |
.TP |
| 81 |
.I si_value |
| 82 |
This field is set to the value specified in |
| 83 |
.IR sigev_value . |
| 84 |
.RE |
| 85 |
.IP |
| 86 |
Depending on the API, other fields may also be set in the |
| 87 |
.I siginfo_t |
| 88 |
structure. |
| 89 |
.IP |
| 90 |
The same information is also available if the signal is accepted using |
| 91 |
.BR sigwaitinfo (2). |
| 92 |
.TP |
| 93 |
.B SIGEV_THREAD |
| 94 |
Notify the process by invoking |
| 95 |
.I sigev_notify_function |
| 96 |
"as if" it were the start function of a new thread. |
| 97 |
(Among the implementation possibilities here are that |
| 98 |
each timer notification could result in the creation of a new thread, |
| 99 |
or that a single thread is created to receive all notifications.) |
| 100 |
The function is invoked with |
| 101 |
.I sigev_value |
| 102 |
as its sole argument. |
| 103 |
If |
| 104 |
.I sigev_notify_attributes |
| 105 |
is not NULL, it should point to a |
| 106 |
.I pthread_attr_t |
| 107 |
structure that defines attributes for the new thread (see |
| 108 |
.BR pthread_attr_init (3)). |
| 109 |
.TP |
| 110 |
.BR SIGEV_THREAD_ID " (Linux-specific)" |
| 111 |
.\" | SIGEV_SIGNAL vs not? |
| 112 |
Currently used only by POSIX timers; |
| 113 |
see |
| 114 |
.BR timer_create (2). |
| 115 |
.SS sigval |
| 116 |
Data passed with a signal. |
| 117 |
.SH STANDARDS |
| 118 |
POSIX.1-2024. |
| 119 |
.SH HISTORY |
| 120 |
POSIX.1-1996. |
| 121 |
.P |
| 122 |
.I <aio.h> |
| 123 |
and |
| 124 |
.I <time.h> |
| 125 |
define |
| 126 |
.I sigevent |
| 127 |
since POSIX.1-2008. |
| 128 |
.SH NOTES |
| 129 |
The following headers also provide |
| 130 |
.IR sigevent : |
| 131 |
.IR <aio.h> , |
| 132 |
.IR <mqueue.h> , |
| 133 |
and |
| 134 |
.IR <time.h> . |
| 135 |
.SH SEE ALSO |
| 136 |
.BR timer_create (2), |
| 137 |
.BR getaddrinfo_a (3), |
| 138 |
.BR lio_listio (3), |
| 139 |
.BR mq_notify (3), |
| 140 |
.BR pthread_sigqueue (3), |
| 141 |
.BR sigqueue (3), |
| 142 |
.BR aiocb (3type), |
| 143 |
.BR siginfo_t (3type) |