1FTRACE(1) Frysk FTRACE(1)
2
6 ftrace - trace system calls, function calls and signals
7
9 ftrace [-f] [-follow] [-dl] [-m] [-o=FILE] [-p=PID...] [-pc]
10 [-sys=SYSCALL[,SYSCALL...]] [-sig=SIG[,SIG...]]
11 [-sym=RULE[,RULE...]] [-addr=RULE[,RULE...]] [-stack] [--]
12 command [arguments...]
13
15 ftrace starts given command and according to tracing script given via
16 command-line arguments, it traces its system calls, symbol entry points
17 in general, and possibly other events as well. It uses the Frysk
18 framework to implement tracing.
19 The working set of events ftrace should trace is defined by the
21 following arguments.
22 Process Selection Options
24 -p=PID
25 Attach to a process with given PID.
26 -f, -follow
28 Follow children: automatically attach to forks of traced process.
29 Symbol Tracing
31 -dl
32 Trace inside dynamic linker. When this option is not present,
33 ftrace will function as if -#INTERP#* rule was present at the end
34 of each tracing script.
35 -sym=SYMBOL[,SYMBOL...]
37 Trace calls through the symbol entry points. Ftrace displays a
38 message each time a thread of execution hits entry point of one of
39 the traced functions, and then when (if) the function returns.
40 If SYMBOL references PLT slot, calls done through that PLT slot are
42 recorded. You then effectively trace calls done FROM given library
43 or executable, and generally can't say which library the call leads
44 TO.
45 When tracing ordinary symbol, catch all calls that end up at this
47 symbol. That includes the calls that don't go through PLT and as
48 such are not intended as inter-library calls, but rather
49 intra-library calls.
50 See below for detailed description of SYMBOL rule syntax.
52 Other Traceable Events
54 -sys=SYSCALL[,SYSCALL...]
55 Trace system calls that match given SYSCALL ruleset. See below for
56 description of SYSCALL syntax.
57 -sig=SIGNAL[,SIGNAL...]
59 Trace signals that match given SIGNAL ruleset. See below for
60 description of SIGNAL syntax.
61 -addr=RULE[,RULE...]
63 Trace addresses given by RULEs. See below for description of
64 address RULE syntax.
65 Other Options
67 -m
68 Print each file mapped to or unmapped from address space of the
69 traced process.
70 -pc
72 Show the value of instruction pointer at each reported event.
73 -stack
75 Stack trace when traced symbol is hit. Note that this option also
76 applies to traced system calls. If you need to cherry-pick which
77 event should stack trace, use # operator described in sections
78 below.
79 Stack Print Options
81 -number-of-frames count
82 Limit the back-trace to count frames. The default is to limit the
83 back-trace to 10 frames. Specify 0 or "all" to print all frames.
84 -lite
86 Perform a light-weight stack backtrace containing only minimal
87 information. Equivalent to -print -.
88 -rich
90 Perform a detailed stack back-trace that includes, where possible,
91 inlined function calls, parameter names and values, and
92 debug-names. Equivalent to -print inline,params,debug-names.
93 -print print-option,...
95 Specify the level of detail to include in a stack back-trace.
96 print-option can be any of:
97 debug-names: use debug information, such as DWARF, to determine the
99 name of functions
100 paths: include the full path to source files and libraries
102 inline: include in-line function in back-trace
104 locals: to include local variables from each frame
106 params: include the function parameters
108 To negate a print-option prefix it with "-".
110 Standard Frysk Options
112 -exe
113 The full path of the executable to read.
114 -noexe
116 Do not attempt to read the corresponding executable when loading a
117 core file.
118 -sysroot directory
120 The system root directory under which all executables, libraries,
121 and source are located.
122 -debug class=level...
124 Set internal debug-tracing of the specified Java class to level
125 (level can be NONE, INFO, WARNING, FINE, and FINEST). If the level
126 is absent, FINE is assumed; if the class is absent, the global
127 level is set.
128
130 To decide which PLT slots or entry points should be traced, following
131 process takes place. A set of symbols to trace ("working set") is
132 initially empty. Rules, if present, are then enumerated from left to
133 right, and set is modified depending on the rules. Rules are delimited
134 by a comma. Syntax of each rule is following:
135 [-]pattern[/options]
137 Without the optional "-" all symbols that match the pattern are added
139 to the working set. With "-", matching symbols are removed.
140 If "/" is present at the end of the rule, following letters are
142 interpreted as rule flags. Currently only one flag is available, "s".
143 When present, it means ftrace should show a stack trace when it hits a
144 symbol that matches this rule.
145 When a "-" rule has an "/s" flag, the call should still be traced, but
147 stack trace shouldn't be generated.
148 pattern defines which symbols or PLT slots from which libraries should
150 be added or removed from working set. Syntax of pattern is as follows:
151 [#soname#][filename.c#][(proc|line)#][plt:]symbol[@version]
153 soname component is matched against a soname of a library in which we
155 wish to trace the call. If the library has no associated soname (such
156 as is usual in case of main executable), the match is done against the
157 file name (without a path). Two special sonames are distinguished:
158 "MAIN", which always matches main executable; and "INTERP", which
159 always matches ELF interpreter (dynamic linker) of the main executable.
160 If the component is missing, then the rule is applicable in all
161 libraries and in main executable.
162 filename.c component is matched against the name of a file where the
164 symbol is defined. NOTE: This is currently not implemented.
165 proc component is matched against the name of block surrounding the
167 definition we wish to trace. If the block doesn't have a name, you can
168 instead refer to it with the line number that the block surrounds.
169 NOTE: This is currently not implemented.
170 symbol component is matched against the name of symbol under
172 consideration. If "plt:" prefix is present, the rule matches PLT entry
173 associated with the symbol instead of the symbol itself.
174 version component is matched against version associated with symbol. If
176 the symbol has no associated version, it is considered to be an empty
177 string. (It is possible to request symbol without a version with the
178 pattern "foo@".) NOTE: This is currently not implemented.
179 All components are presented in glob syntax. See glob(7) manual page
181 for more details. See below for examples.
182
184 Under the presence of the -sys (or -sig) option, ALL system calls (or
185 signals) are ALWAYS traced. This is a limitation of the ptrace layer.
186 The system call and signal rules however serve as a simple way of
187 filtering out the output that you are not interested in. In following
188 paragraphs, the word "event" will be used to mean "signal or syscall,
189 whatever applies".
190 The system call and signal rule syntax and semantics are the same as
192 the symbol rule syntax:
193 [-]pattern[/options]
195 Event selection pattern syntax is then as follows:
197 [event name|event number]
199 When the pattern is empty, it matches all events known to frysk. When
201 the pattern is simple number (e.g. "12"), then the pattern matches the
202 event with the given number. Otherwise the pattern is considered to be
203 case-insensitive glob, and matched against event names. Whole name has
204 to match for event to be a part of working set.
205 Signal can be given both with and without leading "sig" (e.g. "sigkill"
207 as well as "kill").
208
210 The process of establishing a working set of addresses that should be
211 traced is the same as for symbol rules, and the general syntax reflects
212 that. Each rule looks like this:
213 [-]pattern[/options]
215 Each pattern then looks like this:
217 [#soname#][0x]address
219 Addresses are always given in hexadecimal notation, even if initial 0x
221 is missing.
222 soname component is the same as in symbol tracing, i.e. it's matched
224 against a soname of a library in which we wish to trace the address.
225 Same rules apply regarding INTERP and MAIN meta-sonames. Refer to the
226 chapter "SYMBOL RULE SYNTAX" for detailed description.
227 Even though soname is optional, at least one soname has to be specified
229 at the beginning of the -addr command. That's because in general it
230 makes no sense to want to trace the same address in ALL object files at
231 once. The components that are soname-less are assumed to have a soname
232 of the previous component that has soname.
233 For example, this will trace two addresses from the main binary, and
235 stack trace one of them:
236 ftrace -addr=#MAIN#0x08052780/s,08049314 -- ls
238 If you need to trace the same address in several files, you can use the
240 fact that the soname pattern is a glob.
241 The addresses are assumed to be copied from readelf or objdump. ftrace
243 biases the value accordingly depending on where the module is actually
244 mapped.
245
247 Trace all system calls:
248 ftrace -sys= ls
250 Trace variants of stat system call and moreover a system call #3:
252 ftrace -sys='*stat*,3' ls
254 Various ways to tell ftrace that you want to stack trace on SIGUSR1:
256 ftrace -sig=USR1/s,usr1/s,SIGUSR1/s,sigusr1/s,10/s ~/sig
258 Trace all library calls:
260 ftrace -sym=plt:* ls
262 Trace all library calls to functions that contain substring "write" in
264 their names:
265 ftrace -sym=plt:*write* ls
267 Trace memory functions done from libraries, i.e. not from main
269 executable:
270 ftrace -sym='plt:*alloc,plt:free,-#MAIN#plt:*' ls
272 Stack trace on everything, except for memory allocation functions
274 (which should still be traced):
275 ftrace -sym='plt:*/s,-plt:*alloc/s,-plt:free/s' ls
277
279 frysk(7), glob(7)
280
282 The option parser is greedy when looking for options so running ftrace
283 on a program that uses options can be a problem, use -- to split
284 between ftrace and the program. So change from:
285 ~/prefix/bin/ftrace ~/prefix/lib64/frysk/funit --arch 32 frysk.proc.TestAbandon
287 to
289 ~/prefix/bin/ftrace -- ~/prefix/lib64/frysk/funit --arch 32 frysk.proc.TestAbandon
291 Report bugs to http://sourceware.org/frysk
293Frysk 0.4-77.fc34 April 2008 FTRACE(1)