Debian Codegraph @

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

raw
1 .\" Copyright (c) 2006, 2010, 2020, Michael Kerrisk <[email protected]>
2 .\" Copyright (C) 2009 Petr Baudis <[email protected]>
3 .\" Copyright (c) 2020-2023, Alejandro Colomar <[email protected]>
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH sigevent 3type 2024-05-02 "Linux man-pages 6.9.1"
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 " void (*sigev_notify_function)(union sigval);"
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; see
113 .BR timer_create (2).
114 .SS sigval
115 Data passed with a signal.
116 .SH STANDARDS
117 POSIX.1-2008.
118 .SH HISTORY
119 POSIX.1-2001.
120 .P
121 .I <aio.h>
122 and
123 .I <time.h>
124 define
125 .I sigevent
126 since POSIX.1-2008.
127 .SH NOTES
128 The following headers also provide
129 .IR sigevent :
130 .IR <aio.h> ,
131 .IR <mqueue.h> ,
132 and
133 .IR <time.h> .
134 .SH SEE ALSO
135 .BR timer_create (2),
136 .BR getaddrinfo_a (3),
137 .BR lio_listio (3),
138 .BR mq_notify (3),
139 .BR pthread_sigqueue (3),
140 .BR sigqueue (3),
141 .BR aiocb (3type),
142 .BR siginfo_t (3type)