From 665f1e69cf91074aad189f8f084ef7c3869e7f68 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Fri, 11 Jun 2010 06:57:50 +0200 Subject: [PATCH] sigaction.2: Improve description of various siginfo_t fields Signed-off-by: Michael Kerrisk --- man2/sigaction.2 | 56 ++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 45 insertions(+), 11 deletions(-) diff --git a/man2/sigaction.2 b/man2/sigaction.2 index ae633a9aa..424bfe624 100644 --- a/man2/sigaction.2 +++ b/man2/sigaction.2 @@ -39,7 +39,8 @@ .\" 2004-12-09, mtk, added SI_TKILL + other minor changes .\" 2005-09-15, mtk, split sigpending(), sigprocmask(), sigsuspend() .\" out of this page into separate pages. -+.\" 2010-06-10 Andi Kleen, add hwpoison signal extensions +.\" 2010-06-11 Andi Kleen, add hwpoison signal extensions +.\" 2010-06-11 mtk, improvements to discussion of various siginfo_t fields. .\" .TH SIGACTION 2 2010-06-11 "Linux" "Linux Programmer's Manual" .SH NAME @@ -174,7 +175,7 @@ or resume (i.e., they receive This flag is only meaningful when establishing a handler for .BR SIGCHLD . .TP -.BR SA_NOCLDWAIT " (Since Linux 2.6)" +.BR SA_NOCLDWAIT " (since Linux 2.6)" .\" To be precise: Linux 2.5.60 -- MTK If .I signum @@ -270,9 +271,10 @@ siginfo_t { int si_timerid; /* Timer ID; POSIX.1b timers */ .\" In the kernel: si_tid void *si_addr; /* Memory location which caused fault */ - int si_band; /* Band event */ + long si_band; /* Band event (was \fIint\fP in + glibc 2.3.2 and earlier) */ int si_fd; /* File descriptor */ - short si_addr_lsb; /* Least signifcant bit of address + short si_addr_lsb; /* Least significant bit of address (since kernel 2.6.32) */ } .fi @@ -285,8 +287,10 @@ is generally unused on Linux.) The rest of the struct may be a union, so that one should only read the fields that are meaningful for the given signal: .IP * 2 -POSIX.1b signals and -.B SIGCHLD +Signals sent with +.BR kill (2) +and +.BR sigqueue (2) fill in .IR si_pid " and " si_uid . .IP * @@ -299,15 +303,35 @@ The field is an internal ID used by the kernel to identify the timer; it is not the same as the timer ID returned by .BR timer_create (2). +The +.I si_overrun +field is the timer overrun count; +this is the same information as is obtained by a call to +.BR timer_getoverrun (2). +These fields are nonstandard Linux extensions. .IP * .B SIGCHLD fills in -.IR si_status ", " si_utime " and " si_stime . +.IR si_pid ", " si_uid ", " si_status ", " si_utime " and " si_stime , +providing information about the child. +The +.I si_pid +field is the process ID of the child; +.I si_uid +is the child's real user ID. +The +.I si_status +field contains the exit status of the child (if +.I si_code +is +.BR CLD_EXITED ), +or the signal number that caused the process to change state. The .I si_utime and .I si_stime -fields do not include the times used by waited-for children (unlike +contain the user and system CPU time used by the child process; +these fields do not include the times used by waited-for children (unlike .BR getrusage (2) and .BR time (2)). @@ -318,7 +342,7 @@ In 2.6 kernels before 2.6.27, a bug meant that these fields reported time in units of the (configurable) system jiffy (see .BR time (7)). -\" FIXME . +.\" FIXME . .\" When si_utime and si_stime where originally implemented, the .\" measurement unit was HZ, which was the same as clock ticks .\" (sysconf(_SC_CLK_TCK)). In 2.6, HZ became configurable, and @@ -348,7 +372,7 @@ fill in .I si_addr with the address of the fault. Some suberrors of -.I SIGBUS, +.BR SIGBUS , in particular .B BUS_MCEERR_AO and @@ -365,9 +389,19 @@ contains and .I si_addr_lsb are Linux-specific extensions. -.B SIGPOLL +.IP * +.BR SIGPOLL / SIGIO fills in .IR si_band " and " si_fd . +The +.I si_band +event is a bit mask containing the same values as are filled in the +.I revents +field by +.BR poll (2). +The +.I si_fd +field indicates the file descriptor for which the I/O event occurred. .PP .I si_code is a value (not a bit mask)