strace.1.in: describe time format specification

Commits v5.3~74 and v5.3~73 have introduced an extended syntax
for time interval sizes specification, but the relevant descriotion
was lacking.  Fix it by adding the relevant section to the man page
and reference to it in the descriptions of the respective options.

* strace.1.in (.SH OPTIONS): Rewrite descriptions of -O,
-e inject=delay_enter, and -e inject=delay_exit values, refer to section
"Time specification format description".
(.SS "Time specification format description"): New section.

Complements: v5.3~74 "delay: use parse_ts for parsing delay value"
Complements: v5.3~73 "count: use parse_ts for parsing overhead value"

diff --git a/strace.1.in b/strace.1.in
index af5dcd6b031d67f10c4879126f27a9bbde428cd2..7a5a4d56602f11b8018936a4ef8a434a58727513 100644 (file)
--- a/strace.1.in
+++ b/strace.1.in
@@ -798,8 +798,7 @@ but also print regular output while processes are running.
 .TP
 .BI "\-O " overhead
 Set the overhead for tracing system calls to
-.I overhead
-microseconds.
+.IR overhead .
 This is useful for overriding the default heuristic for guessing
 how much time is spent in mere measuring when timing system calls using
 the
@@ -810,6 +809,11 @@ program run without tracing (using
 and comparing the accumulated
 system call time to the total produced using
 .BR \-c .
+.IP
+The format of
+.I overhead
+specification is described in section
+.IR "Time specification format description".
 .TP
 .BI "\-S " sortby
 Sort the output of the histogram printed by the
@@ -829,7 +833,7 @@ Summarise the time difference between the beginning and end of
 each system call.  The default is to summarise the system time.
 .SS Tampering
 .TP 12
-\fB\-e\ inject\fR=\,\fIset\/\fR[:\fBerror\fR=\,\fIerrno\/\fR|:\fBretval\fR=\,\fIvalue\/\fR][:\fBsignal\fR=\,\fIsig\/\fR][:\fBsyscall\fR=\fIsyscall\fR][:\fBdelay_enter\fR=\,\fIusecs\/\fR][:\fBdelay_exit\fR=\,\fIusecs\/\fR][:\fBwhen\fR=\,\fIexpr\/\fR]
+\fB\-e\ inject\fR=\,\fIset\/\fR[:\fBerror\fR=\,\fIerrno\/\fR|:\fBretval\fR=\,\fIvalue\/\fR][:\fBsignal\fR=\,\fIsig\/\fR][:\fBsyscall\fR=\fIsyscall\fR][:\fBdelay_enter\fR=\,\fIdelay\/\fR][:\fBdelay_exit\fR=\,\fIdelay\/\fR][:\fBwhen\fR=\,\fIexpr\/\fR]
 Perform syscall tampering for the specified set of syscalls.
 .IP
 At least one of
@@ -866,11 +870,15 @@ or a numeric value within 1..\fBSIGRTMAX\fR range,
 that signal is delivered on entering every syscall specified by the
 .IR set .
 .IP
-If :\fBdelay_enter\fR=\,\fIusecs\/\fR or :\fBdelay_exit\fR=\,\fIusecs\/\fR
+If :\fBdelay_enter\fR=\,\fIdelay\/\fR or :\fBdelay_exit\fR=\,\fIdelay\/\fR
 options are specified, delay injection is performed: the tracee is delayed
-by at least
-.IR usecs
-microseconds on entering or exiting the syscall.
+by time period specified by
+.IR delay
+on entering or exiting the syscall, respectively.
+The format of
+.I delay
+specification is described in section
+.IR "Time specification format description".
 .IP
 If :\fBsignal\fR=\,\fIsig\/\fR option is specified without
 :\fBerror\fR=\,\fIerrno\/\fR, :\fBretval\fR=\,\fIvalue\/\fR or
@@ -880,8 +888,8 @@ then only a signal
 is delivered without a syscall fault or delay injection.
 Conversely, :\fBerror\fR=\,\fIerrno\/\fR or
 :\fBretval\fR=\,\fIvalue\/\fR option without
-:\fBdelay_enter\fR=\,\fIusecs\/\fR,
-:\fBdelay_exit\fR=\,\fIusecs\/\fR or
+:\fBdelay_enter\fR=\,\fIdelay\/\fR,
+:\fBdelay_exit\fR=\,\fIdelay\/\fR or
 :\fBsignal\fR=\,\fIsig\/\fR options injects a fault without delivering a signal
 or injecting a delay, etc.
 .IP
@@ -1007,6 +1015,26 @@ Print the help summary.
 .B \-\-version
 Print the version number of
 .BR strace .
+.SS "Time specification format description"
+.PP
+Time values can be specified as a decimal floating point number
+(in a format accepted by
+.BR strtod (3)),
+optionally followed by one of the following suffices that specify
+the unit of time:
+.B s
+(seconds),
+.B ms
+(milliseconds),
+.B us
+(microseconds), or
+.B ns
+(nanoseconds).
+If no suffix is specified, the value is interpreted as microseconds.
+.PP
+The described format is used for
+.BR \-O ", " "\-e inject" = delay_enter ", and " "\-e inject" = delay_exit
+options.
 .SH DIAGNOSTICS
 When
 .I command