[PATCHv2 2/2] man: document the :signal option to -e fault

[Seraphime Kirkovski]

Signed-off-by: Seraphime Kirkovski <kirkseraph at gmail.com>
---

Not sure exactly how to put in the NEWS file. Feel free to change
or remove the hunk if you dislike it.

This should take in account your edits.

 NEWS     |  3 +++
 strace.1 | 24 ++++++++++++++++++++++--
 2 files changed, 25 insertions(+), 2 deletions(-)

diff --git a/NEWS b/NEWS
index 379aea5..0c742a6 100644
--- a/NEWS
+++ b/NEWS
@@ -1,6 +1,9 @@
 Noteworthy changes in release ?.?? (????-??-??)
 ===============================================
 
+ * Improvements
+   * Implemented signal delivery on syscall entry as an extension to -e fault.
+
 Noteworthy changes in release 4.15 (2016-12-14)
 ===============================================
 
diff --git a/strace.1 b/strace.1
index 24dd7d3..0039073 100644
--- a/strace.1
+++ b/strace.1
@@ -472,7 +472,7 @@ Note that this is independent from the normal tracing of the
 system call which is controlled by the option
 .BR -e "\ " trace = write .
 .TP
-\fB\-e\ fault\fR=\,\fIset\/\fR[:\fBerror\fR=\,\fIerrno\/\fR][:\fBwhen\fR=\,\fIexpr\/\fR]
+\fB\-e\ fault\fR=\,\fIset\/\fR[:\fBerror\fR=\,\fIerrno\/\fR][:\fBsignal\fR=\,\fIsig\/\fR][:\fBwhen\fR=\,\fIexpr\/\fR]
 Perform a syscall fault injection for the specified set of syscalls.
 When a fault is injected into a syscall invocation, the syscall number
 is replaced by -1 which corresponds to an invalid syscall.
@@ -486,8 +486,28 @@ the default error code returned by the kernel, which is traditionally
 .B ENOSYS
 for invalid syscall numbers on most architectures.
 
+If a signal is specified using either a symbolic value like
+.B SIGSEGV
+or a numeric value within 1..\fBSIGRTMAX\fR range,
+that signal is delivered on entering every syscall specified in
+.IR set
+
+If \,\fIsig\fR is specified without \,\fIerrno\fR, then only a signal
+.I sig
+is delivered without a syscall fault injection.
+Conversely, :\fBerror\fR=\,\fIerrno\/\fR option without
+:\fBsignal\fR=\,\fIsig\/\fR option injects a fault without delivering a signal.
+
+If both :\fBerror\fR=\,\fIerrno\/\fR and :\fBsignal\fR=\,\fIsig\/\fR
+options are specified, then both a fault is injected with the specified
+error code
+.I errno
+and a signal
+.I sig
+is delivered.
+
 Unless a :\fBwhen\fR=\,\fIexpr\fR subexpression is specified,
-a fault is injected into every invocation of each syscall from the
+an injection is being made into every invocation of each syscall from the
 .IR set .
 
 The format of the subexpression is one of the following:
-- 
2.10.2