diff options
Diffstat (limited to 'man/man3type/sigevent.3type')
| -rw-r--r-- | man/man3type/sigevent.3type | 142 |
1 files changed, 142 insertions, 0 deletions
diff --git a/man/man3type/sigevent.3type b/man/man3type/sigevent.3type new file mode 100644 index 000000000..01ca76620 --- /dev/null +++ b/man/man3type/sigevent.3type @@ -0,0 +1,142 @@ +.\" Copyright (c) 2006, 2010, 2020, Michael Kerrisk <mtk.manpages@gmail.com> +.\" Copyright (C) 2009 Petr Baudis <pasky@suse.cz> +.\" Copyright (c) 2020-2023, Alejandro Colomar <alx@kernel.org> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sigevent 3type (date) "Linux man-pages (unreleased)" +.SH NAME +sigevent, sigval \- structure for notification from asynchronous routines +.SH SYNOPSIS +.EX +.B #include <signal.h> +.P +.B struct sigevent { +.BR " int sigev_notify;" " /* Notification type */" +.BR " int sigev_signo;" " /* Signal number */" +.BR " union sigval sigev_value;" " /* Data passed with notification */" +\& +.B " void (*sigev_notify_function)(union sigval);" +.BR " " " /* Notification function" +.BR " " " (SIGEV_THREAD) */" +.B " pthread_attr_t *sigev_notify_attributes;" +.BR " " " /* Notification attributes */" +\& +.BR " " "/* Linux only: */" +.B " pid_t sigev_notify_thread_id;" +.BR " " " /* ID of thread to signal" +.BR " " " (SIGEV_THREAD_ID) */" +.B }; +.P +.BR "union sigval {" " /* Data passed with notification */" +.BR " int sival_int;" " /* Integer value */" +.BR " void *sival_ptr;" " /* Pointer value */" +.B }; +.EE +.SH DESCRIPTION +.SS sigevent +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). +.P +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 . +.P +The +.I sigev_notify +field specifies how notification is to be performed. +This field can have one of the following values: +.TP +.B SIGEV_NONE +A "null" notification: don't do anything when the event occurs. +.TP +.B 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 +.B 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). +.SS sigval +Data passed with a signal. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.P +.I <aio.h> +and +.I <time.h> +define +.I sigevent +since POSIX.1-2008. +.SH NOTES +The following headers also provide +.IR sigevent : +.IR <aio.h> , +.IR <mqueue.h> , +and +.IR <time.h> . +.SH SEE ALSO +.BR timer_create (2), +.BR getaddrinfo_a (3), +.BR lio_listio (3), +.BR mq_notify (3), +.BR pthread_sigqueue (3), +.BR sigqueue (3), +.BR aiocb (3type), +.BR siginfo_t (3type) |