Browse Source

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"
Eugene Syromyatnikov 1 month ago
parent
commit
27d4ecdf5e
1 changed files with 37 additions and 9 deletions
  1. 37
    9
      strace.1.in

+ 37
- 9
strace.1.in View File

@@ -798,8 +798,7 @@ but also print regular output while processes are running.
798 798
 .TP
799 799
 .BI "\-O " overhead
800 800
 Set the overhead for tracing system calls to
801
-.I overhead
802
-microseconds.
801
+.IR overhead .
803 802
 This is useful for overriding the default heuristic for guessing
804 803
 how much time is spent in mere measuring when timing system calls using
805 804
 the
@@ -810,6 +809,11 @@ program run without tracing (using
810 809
 and comparing the accumulated
811 810
 system call time to the total produced using
812 811
 .BR \-c .
812
+.IP
813
+The format of
814
+.I overhead
815
+specification is described in section
816
+.IR "Time specification format description".
813 817
 .TP
814 818
 .BI "\-S " sortby
815 819
 Sort the output of the histogram printed by the
@@ -829,7 +833,7 @@ Summarise the time difference between the beginning and end of
829 833
 each system call.  The default is to summarise the system time.
830 834
 .SS Tampering
831 835
 .TP 12
832
-\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]
836
+\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]
833 837
 Perform syscall tampering for the specified set of syscalls.
834 838
 .IP
835 839
 At least one of
@@ -866,11 +870,15 @@ or a numeric value within 1..\fBSIGRTMAX\fR range,
866 870
 that signal is delivered on entering every syscall specified by the
867 871
 .IR set .
868 872
 .IP
869
-If :\fBdelay_enter\fR=\,\fIusecs\/\fR or :\fBdelay_exit\fR=\,\fIusecs\/\fR
873
+If :\fBdelay_enter\fR=\,\fIdelay\/\fR or :\fBdelay_exit\fR=\,\fIdelay\/\fR
870 874
 options are specified, delay injection is performed: the tracee is delayed
871
-by at least
872
-.IR usecs
873
-microseconds on entering or exiting the syscall.
875
+by time period specified by
876
+.IR delay
877
+on entering or exiting the syscall, respectively.
878
+The format of
879
+.I delay
880
+specification is described in section
881
+.IR "Time specification format description".
874 882
 .IP
875 883
 If :\fBsignal\fR=\,\fIsig\/\fR option is specified without
876 884
 :\fBerror\fR=\,\fIerrno\/\fR, :\fBretval\fR=\,\fIvalue\/\fR or
@@ -880,8 +888,8 @@ then only a signal
880 888
 is delivered without a syscall fault or delay injection.
881 889
 Conversely, :\fBerror\fR=\,\fIerrno\/\fR or
882 890
 :\fBretval\fR=\,\fIvalue\/\fR option without
883
-:\fBdelay_enter\fR=\,\fIusecs\/\fR,
884
-:\fBdelay_exit\fR=\,\fIusecs\/\fR or
891
+:\fBdelay_enter\fR=\,\fIdelay\/\fR,
892
+:\fBdelay_exit\fR=\,\fIdelay\/\fR or
885 893
 :\fBsignal\fR=\,\fIsig\/\fR options injects a fault without delivering a signal
886 894
 or injecting a delay, etc.
887 895
 .IP
@@ -1007,6 +1015,26 @@ Print the help summary.
1007 1015
 .B \-\-version
1008 1016
 Print the version number of
1009 1017
 .BR strace .
1018
+.SS "Time specification format description"
1019
+.PP
1020
+Time values can be specified as a decimal floating point number
1021
+(in a format accepted by
1022
+.BR strtod (3)),
1023
+optionally followed by one of the following suffices that specify
1024
+the unit of time:
1025
+.B s
1026
+(seconds),
1027
+.B ms
1028
+(milliseconds),
1029
+.B us
1030
+(microseconds), or
1031
+.B ns
1032
+(nanoseconds).
1033
+If no suffix is specified, the value is interpreted as microseconds.
1034
+.PP
1035
+The described format is used for
1036
+.BR \-O ", " "\-e inject" = delay_enter ", and " "\-e inject" = delay_exit
1037
+options.
1010 1038
 .SH DIAGNOSTICS
1011 1039
 When
1012 1040
 .I command

Loading…
Cancel
Save