Debian Codegraph @

upstream/debian-unstable/man3/sigevent.3type

raw
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)