sigaction.2: Improve description of various siginfo_t fields

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

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)