| .\" Copyright (C) 2006, 2010 Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" Copyright (C) 2009 Petr Baudis <pasky@suse.cz> |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .TH SIGEVENT 7 2021-03-22 "GNU" "Linux Programmer's Manual" |
| .SH NAME |
| sigevent \- structure for notification from asynchronous routines |
| .SH SYNOPSIS |
| .nf |
| #include <signal.h> |
| .PP |
| union sigval { /* Data passed with notification */ |
| int sival_int; /* Integer value */ |
| void *sival_ptr; /* Pointer value */ |
| }; |
| .PP |
| struct sigevent { |
| int sigev_notify; /* Notification method */ |
| int sigev_signo; /* Notification signal */ |
| union sigval sigev_value; |
| /* Data passed with notification */ |
| void (*sigev_notify_function)(union sigval); |
| /* Function used for thread |
| notification (SIGEV_THREAD) */ |
| void *sigev_notify_attributes; |
| /* Attributes for notification thread |
| (SIGEV_THREAD) */ |
| pid_t sigev_notify_thread_id; |
| /* ID of thread to signal |
| (SIGEV_THREAD_ID); Linux-specific */ |
| }; |
| .fi |
| .SH DESCRIPTION |
| The |
| .I sigevent |
| structure is used by various APIs |
| to describe the way a process is to be notified about an event |
| (e.g., completion of an asynchronous request, expiration of a timer, |
| or the arrival of a message). |
| .PP |
| The definition shown in the SYNOPSIS is approximate: |
| some of the fields in the |
| .I sigevent |
| structure may be defined as part of a union. |
| Programs should employ only those fields relevant |
| to the value specified in |
| .IR sigev_notify . |
| .PP |
| The |
| .I sigev_notify |
| field specifies how notification is to be performed. |
| This field can have one of the following values: |
| .TP |
| .BR SIGEV_NONE |
| A "null" notification: don't do anything when the event occurs. |
| .TP |
| .BR SIGEV_SIGNAL |
| Notify the process by sending the signal specified in |
| .IR sigev_signo . |
| .IP |
| If the signal is caught with a signal handler that was registered using the |
| .BR sigaction (2) |
| .B SA_SIGINFO |
| flag, then the following fields are set in the |
| .I siginfo_t |
| structure that is passed as the second argument of the handler: |
| .RS |
| .TP 10 |
| .I si_code |
| This field is set to a value that depends on the API |
| delivering the notification. |
| .TP |
| .I si_signo |
| This field is set to the signal number (i.e., the same value as in |
| .IR sigev_signo ). |
| .TP |
| .I si_value |
| This field is set to the value specified in |
| .IR sigev_value . |
| .RE |
| .IP |
| Depending on the API, other fields may also be set in the |
| .I siginfo_t |
| structure. |
| .IP |
| The same information is also available if the signal is accepted using |
| .BR sigwaitinfo (2). |
| .TP |
| .BR SIGEV_THREAD |
| Notify the process by invoking |
| .I sigev_notify_function |
| "as if" it were the start function of a new thread. |
| (Among the implementation possibilities here are that |
| each timer notification could result in the creation of a new thread, |
| or that a single thread is created to receive all notifications.) |
| The function is invoked with |
| .I sigev_value |
| as its sole argument. |
| If |
| .I sigev_notify_attributes |
| is not NULL, it should point to a |
| .I pthread_attr_t |
| structure that defines attributes for the new thread (see |
| .BR pthread_attr_init (3)). |
| .TP |
| .BR SIGEV_THREAD_ID " (Linux-specific)" |
| .\" | SIGEV_SIGNAL vs not? |
| Currently used only by POSIX timers; see |
| .BR timer_create (2). |
| .SH SEE ALSO |
| .BR timer_create (2), |
| .BR aio_fsync (3), |
| .BR aio_read (3), |
| .BR aio_write (3), |
| .BR getaddrinfo_a (3), |
| .BR lio_listio (3), |
| .BR mq_notify (3), |
| .BR aio (7), |
| .BR pthreads (7) |