Document signal injection

* strace.1: Describe :signal=SIG option of the fault injection syntax.
* NEWS: Mention signal injection.

Signed-off-by: Seraphime Kirkovski <kirkseraph@gmail.com>
Signed-off-by: Dmitry V. Levin <ldv@altlinux.org>

diff --git a/NEWS b/NEWS
index 379aea5a44ed36f2b994ed2ffaeffcf6946f7d22..eb13630853ea89df69b89d458de756eb174e7028 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -1,6 +1,9 @@
 Noteworthy changes in release ?.?? (????-??-??)
 ===============================================
 
+* Improvements
+  * Implemented signal injection as an extension to syscall fault injection.
+
 Noteworthy changes in release 4.15 (2016-12-14)
 ===============================================
 

diff --git a/strace.1 b/strace.1
index 24dd7d3bb013b0acebd44a3afd904c92bec711b0..0356c2d1b9c0fa2893f78481a7946f80525b8c9d 100644 (file)
--- 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,29 @@ 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 by the
+.IR set .
+
+If :\fBsignal\fR=\,\fIsig\/\fR option is specified without
+:\fBerror\fR=\,\fIerrno\/\fR option, 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: