diff --git a/man7/sigevent.7 b/man7/sigevent.7 new file mode 100644 index 000000000..14f109cbd --- /dev/null +++ b/man7/sigevent.7 @@ -0,0 +1,136 @@ +.\" Copyright (C) 2006, 2010 Michael Kerrisk +.\" Copyright (C) 2009 Petr Baudis +.\" +.\" 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. +.\" +.TH SIGEVENT 7 2010-09-19 "GNU" "Linux Programmer's Manual" +.SH NAME +struct sigevent \- structure for notification from asynchronous routines +.SH SYNOPSIS +.nf + +union sigval { /* Data passed with notification */ + int sival_int; /* Integer value */ + void *sival_ptr; /* Pointer value */ +}; + +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) */ +}; +.fi +.SH DESCRIPTION +.PP +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 only employ 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 8 +.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 8 +.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 CONFORMING TO +POSIX.1-2001. +.SH "SEE ALSO" +.BR timer_create (2), +.BR aio_fsync (3), +.\" .BR lio_listio (3), +.\" FIXME This page will be added later .BR getaddrinfo_a (3), +.BR mq_notify (3), +.BR pthreads (7)