]>
Commit | Line | Data |
---|---|---|
bcc5e407 PB |
1 | .\" Copyright (C) 2006, 2010 Michael Kerrisk <mtk.manpages@gmail.com> |
2 | .\" Copyright (C) 2009 Petr Baudis <pasky@suse.cz> | |
3 | .\" | |
5fbde956 | 4 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
bcc5e407 | 5 | .\" |
1d767b55 | 6 | .TH SIGEVENT 7 2021-03-22 "GNU" "Linux Programmer's Manual" |
bcc5e407 | 7 | .SH NAME |
5b64c2d1 | 8 | sigevent \- structure for notification from asynchronous routines |
bcc5e407 PB |
9 | .SH SYNOPSIS |
10 | .nf | |
0b8f560a | 11 | #include <signal.h> |
dbfe9c70 | 12 | .PP |
65c0f427 MK |
13 | union sigval { /* Data passed with notification */ |
14 | int sival_int; /* Integer value */ | |
15 | void *sival_ptr; /* Pointer value */ | |
bcc5e407 | 16 | }; |
dbfe9c70 | 17 | .PP |
bcc5e407 | 18 | struct sigevent { |
65c0f427 MK |
19 | int sigev_notify; /* Notification method */ |
20 | int sigev_signo; /* Notification signal */ | |
21 | union sigval sigev_value; | |
22 | /* Data passed with notification */ | |
511bb71b | 23 | void (*sigev_notify_function)(union sigval); |
65c0f427 MK |
24 | /* Function used for thread |
25 | notification (SIGEV_THREAD) */ | |
26 | void *sigev_notify_attributes; | |
27 | /* Attributes for notification thread | |
28 | (SIGEV_THREAD) */ | |
29 | pid_t sigev_notify_thread_id; | |
30 | /* ID of thread to signal | |
31 | (SIGEV_THREAD_ID); Linux-specific */ | |
bcc5e407 PB |
32 | }; |
33 | .fi | |
34 | .SH DESCRIPTION | |
bcc5e407 PB |
35 | The |
36 | .I sigevent | |
37 | structure is used by various APIs | |
38 | to describe the way a process is to be notified about an event | |
39 | (e.g., completion of an asynchronous request, expiration of a timer, | |
40 | or the arrival of a message). | |
41 | .PP | |
42 | The definition shown in the SYNOPSIS is approximate: | |
43 | some of the fields in the | |
44 | .I sigevent | |
45 | structure may be defined as part of a union. | |
33a0ccb2 | 46 | Programs should employ only those fields relevant |
bcc5e407 PB |
47 | to the value specified in |
48 | .IR sigev_notify . | |
49 | .PP | |
50 | The | |
51 | .I sigev_notify | |
52 | field specifies how notification is to be performed. | |
53 | This field can have one of the following values: | |
0019177e | 54 | .TP |
1ae6b2c7 | 55 | .B SIGEV_NONE |
bcc5e407 PB |
56 | A "null" notification: don't do anything when the event occurs. |
57 | .TP | |
1ae6b2c7 | 58 | .B SIGEV_SIGNAL |
bcc5e407 PB |
59 | Notify the process by sending the signal specified in |
60 | .IR sigev_signo . | |
61 | .IP | |
62 | If the signal is caught with a signal handler that was registered using the | |
63 | .BR sigaction (2) | |
64 | .B SA_SIGINFO | |
65 | flag, then the following fields are set in the | |
66 | .I siginfo_t | |
67 | structure that is passed as the second argument of the handler: | |
0019177e | 68 | .RS |
bcc5e407 PB |
69 | .TP 10 |
70 | .I si_code | |
71 | This field is set to a value that depends on the API | |
72 | delivering the notification. | |
73 | .TP | |
74 | .I si_signo | |
f6b326eb | 75 | This field is set to the signal number (i.e., the same value as in |
bcc5e407 PB |
76 | .IR sigev_signo ). |
77 | .TP | |
78 | .I si_value | |
79 | This field is set to the value specified in | |
80 | .IR sigev_value . | |
81 | .RE | |
82 | .IP | |
83 | Depending on the API, other fields may also be set in the | |
84 | .I siginfo_t | |
85 | structure. | |
86 | .IP | |
87 | The same information is also available if the signal is accepted using | |
88 | .BR sigwaitinfo (2). | |
89 | .TP | |
1ae6b2c7 | 90 | .B SIGEV_THREAD |
bcc5e407 PB |
91 | Notify the process by invoking |
92 | .I sigev_notify_function | |
93 | "as if" it were the start function of a new thread. | |
94 | (Among the implementation possibilities here are that | |
95 | each timer notification could result in the creation of a new thread, | |
96 | or that a single thread is created to receive all notifications.) | |
97 | The function is invoked with | |
98 | .I sigev_value | |
99 | as its sole argument. | |
100 | If | |
101 | .I sigev_notify_attributes | |
102 | is not NULL, it should point to a | |
103 | .I pthread_attr_t | |
104 | structure that defines attributes for the new thread (see | |
105 | .BR pthread_attr_init (3)). | |
106 | .TP | |
107 | .BR SIGEV_THREAD_ID " (Linux-specific)" | |
108 | .\" | SIGEV_SIGNAL vs not? | |
109 | Currently used only by POSIX timers; see | |
110 | .BR timer_create (2). | |
47297adb | 111 | .SH SEE ALSO |
bcc5e407 PB |
112 | .BR timer_create (2), |
113 | .BR aio_fsync (3), | |
a9ba82d5 MK |
114 | .BR aio_read (3), |
115 | .BR aio_write (3), | |
0f848cbc | 116 | .BR getaddrinfo_a (3), |
3e5c319e | 117 | .BR lio_listio (3), |
bcc5e407 | 118 | .BR mq_notify (3), |
9889b88b | 119 | .BR aio (7), |
bcc5e407 | 120 | .BR pthreads (7) |