1FTRACE(1)                            Frysk                           FTRACE(1)
2
3
4

NAME

6       ftrace - trace system calls, function calls and signals
7

SYNOPSIS

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

DESCRIPTION

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
20       The working set of events ftrace should trace is defined by the
21       following arguments.
22
23   Process Selection Options
24       -p=PID
25           Attach to a process with given PID.
26
27       -f, -follow
28           Follow children: automatically attach to forks of traced process.
29
30   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
36       -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
41           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
46           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
51           See below for detailed description of SYMBOL rule syntax.
52
53   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
58       -sig=SIGNAL[,SIGNAL...]
59           Trace signals that match given SIGNAL ruleset. See below for
60           description of SIGNAL syntax.
61
62       -addr=RULE[,RULE...]
63           Trace addresses given by RULEs. See below for description of
64           address RULE syntax.
65
66   Other Options
67       -m
68           Print each file mapped to or unmapped from address space of the
69           traced process.
70
71       -pc
72           Show the value of instruction pointer at each reported event.
73
74       -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
80   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
85       -lite
86           Perform a light-weight stack backtrace containing only minimal
87           information. Equivalent to -print -.
88
89       -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
94       -print print-option,...
95           Specify the level of detail to include in a stack back-trace.
96           print-option can be any of:
97
98           debug-names: use debug information, such as DWARF, to determine the
99           name of functions
100
101           paths: include the full path to source files and libraries
102
103           inline: include in-line function in back-trace
104
105           locals: to include local variables from each frame
106
107           params: include the function parameters
108
109           To negate a print-option prefix it with "-".
110
111   Standard Frysk Options
112       -exe
113           The full path of the executable to read.
114
115       -noexe
116           Do not attempt to read the corresponding executable when loading a
117           core file.
118
119       -sysroot directory
120           The system root directory under which all executables, libraries,
121           and source are located.
122
123       -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

SYMBOL RULE SYNTAX

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
136       [-]pattern[/options]
137
138       Without the optional "-" all symbols that match the pattern are added
139       to the working set. With "-", matching symbols are removed.
140
141       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
146       When a "-" rule has an "/s" flag, the call should still be traced, but
147       stack trace shouldn't be generated.
148
149       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
152       [#soname#][filename.c#][(proc|line)#][plt:]symbol[@version]
153
154       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
163       filename.c component is matched against the name of a file where the
164       symbol is defined. NOTE: This is currently not implemented.
165
166       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
171       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
175       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
180       All components are presented in glob syntax. See glob(7) manual page
181       for more details. See below for examples.
182

SYSCALL AND SIGNAL RULE SYNTAX

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
191       The system call and signal rule syntax and semantics are the same as
192       the symbol rule syntax:
193
194       [-]pattern[/options]
195
196       Event selection pattern syntax is then as follows:
197
198       [event name|event number]
199
200       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
206       Signal can be given both with and without leading "sig" (e.g. "sigkill"
207       as well as "kill").
208

ADDRESS RULE SYNTAX

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
214       [-]pattern[/options]
215
216       Each pattern then looks like this:
217
218       [#soname#][0x]address
219
220       Addresses are always given in hexadecimal notation, even if initial 0x
221       is missing.
222
223       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
228       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
234       For example, this will trace two addresses from the main binary, and
235       stack trace one of them:
236
237       ftrace -addr=#MAIN#0x08052780/s,08049314 -- ls
238
239       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
242       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

EXAMPLES

247       Trace all system calls:
248
249       ftrace -sys= ls
250
251       Trace variants of stat system call and moreover a system call #3:
252
253       ftrace -sys='*stat*,3' ls
254
255       Various ways to tell ftrace that you want to stack trace on SIGUSR1:
256
257       ftrace -sig=USR1/s,usr1/s,SIGUSR1/s,sigusr1/s,10/s ~/sig
258
259       Trace all library calls:
260
261       ftrace -sym=plt:* ls
262
263       Trace all library calls to functions that contain substring "write" in
264       their names:
265
266       ftrace -sym=plt:*write* ls
267
268       Trace memory functions done from libraries, i.e. not from main
269       executable:
270
271       ftrace -sym='plt:*alloc,plt:free,-#MAIN#plt:*' ls
272
273       Stack trace on everything, except for memory allocation functions
274       (which should still be traced):
275
276       ftrace -sym='plt:*/s,-plt:*alloc/s,-plt:free/s' ls
277

SEE ALSO

279       frysk(7), glob(7)
280

BUGS

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
286           ~/prefix/bin/ftrace ~/prefix/lib64/frysk/funit --arch 32 frysk.proc.TestAbandon
287
288       to
289
290           ~/prefix/bin/ftrace -- ~/prefix/lib64/frysk/funit --arch 32 frysk.proc.TestAbandon
291
292       Report bugs to http://sourceware.org/frysk
293
294
295
296Frysk 0.4-83.fc36                 April 2008                         FTRACE(1)
Impressum