blob: 358d6aae8eb9fe7af5778cc1f221cb99a8dc2ed7 [file] [log] [blame]
Ian Wienand9a2ad352006-02-20 22:44:45 +01001.\" Copyright (c) 1997-2005 Juan Cespedes <cespedes@debian.org>
Juan Cespedes07461b61997-08-22 15:29:10 +02002.\" This file is covered by the GNU GPL
Juan Cespedesfea4a122009-05-28 16:53:43 +02003.TH ltrace 1
Ian Wienand9a2ad352006-02-20 22:44:45 +01004.SH NAME
Juan Cespedes07461b61997-08-22 15:29:10 +02005ltrace \- A library call tracer
6
Ian Wienand9a2ad352006-02-20 22:44:45 +01007.SH SYNOPSIS
Juan Cespedes07461b61997-08-22 15:29:10 +02008.B ltrace
Juan Cespedesc5c744a2009-07-23 18:22:58 +02009.I "[-CfhiLrStttV] [-a column] [-A maxelts] [-D level] [-e expr] [-l filename] [-n nr] [-o filename] [-p pid] ... [-s strsize] [-u username] [-X extern] [-x extern] ... [--align=column] [--debug=level] [--demangle] [--help] [--indent=nr] [--library=filename] [--output=filename] [--version] [command [arg ...]]"
Juan Cespedes07461b61997-08-22 15:29:10 +020010
Ian Wienand9a2ad352006-02-20 22:44:45 +010011.SH DESCRIPTION
Juan Cespedes07461b61997-08-22 15:29:10 +020012.B ltrace
13is a program that simply runs the specified
14.I command
15until it exits. It intercepts and records the dynamic library calls
16which are called by the executed process and the signals which are
17received by that process.
Juan Cespedesac3db291998-04-25 14:31:58 +020018It can also intercept and print the system calls executed by the program.
Ian Wienand9a2ad352006-02-20 22:44:45 +010019.PP
Juan Cespedes07461b61997-08-22 15:29:10 +020020Its use is very similar to
Juan Cespedes81690ef1998-03-13 19:31:29 +010021.BR strace(1) .
Juan Cespedes07461b61997-08-22 15:29:10 +020022
Ian Wienand9a2ad352006-02-20 22:44:45 +010023.SH OPTIONS
24.TP
Juan Cespedesd65efa32003-02-03 00:22:30 +010025.I \-a, \-\-align column
Justin Pryzby1b98b342006-06-16 03:15:18 +020026Align return values in a specific column (default column is 5/8 of screen width).
Ian Wienand9a2ad352006-02-20 22:44:45 +010027.TP
Steve Fink1150bc42006-08-07 06:04:43 +020028.I \-A maxelts
29Maximum number of array elements to print before suppressing the rest with an ellipsis ("...")
30.TP
Juan Cespedesd65efa32003-02-03 00:22:30 +010031.I \-c
32Count time and calls for each library call and report a summary on program exit.
Ian Wienand9a2ad352006-02-20 22:44:45 +010033.TP
Juan Cespedesac3db291998-04-25 14:31:58 +020034.I \-C, \-\-demangle
Ian Wienand9a2ad352006-02-20 22:44:45 +010035Decode (demangle) low-level symbol names into user-level names.
Justin Pryzbyfda2c6f2006-07-18 00:05:26 +020036Besides removing any initial underscore prefix used by the system,
Juan Cespedesac3db291998-04-25 14:31:58 +020037this makes C++ function names readable.
Ian Wienand9a2ad352006-02-20 22:44:45 +010038.TP
Juan Cespedesc5c744a2009-07-23 18:22:58 +020039.I \-D, \-\-debug level
Juan Cespedescd8976d2009-05-14 13:47:58 +020040Show debugging output of
41.B ltrace
42itself.
43.I level
44must be a sum of some of the following numbers:
45.RS
46.TP
Juan Cespedesc5c744a2009-07-23 18:22:58 +020047.B 01
48DEBUG_GENERAL. Shows helpful progress information
49.TP
50.B 010
Juan Cespedescd8976d2009-05-14 13:47:58 +020051DEBUG_EVENT. Shows every event received by a traced program
52.TP
Juan Cespedesc5c744a2009-07-23 18:22:58 +020053.B 020
Juan Cespedes85f7d762009-05-14 13:53:59 +020054DEBUG_PROCESS. Shows every action
55.B ltrace
Juan Cespedesc5c744a2009-07-23 18:22:58 +020056carries upon a traced process
57.TP
58.B 040
59DEBUG_FUNCTION. Shows every entry to internal functions
Juan Cespedescd8976d2009-05-14 13:47:58 +020060.RE
Ian Wienand9a2ad352006-02-20 22:44:45 +010061.TP
Juan Cespedesac3db291998-04-25 14:31:58 +020062.I \-e expr
63A qualifying expression which modifies which events to trace.
64The format of the expression is:
Ian Wienand9a2ad352006-02-20 22:44:45 +010065.br
Juan Cespedesac3db291998-04-25 14:31:58 +020066[!]value1[,value2]...
Ian Wienand9a2ad352006-02-20 22:44:45 +010067.br
Juan Cespedesac3db291998-04-25 14:31:58 +020068where the values are the functions to trace. Using an exclamation
69mark negates the set of values. For example
70.I \-e printf
71means to trace only the printf library call. By contrast,
72.I \-e !printf
73means to trace every library call except printf.
Ian Wienand9a2ad352006-02-20 22:44:45 +010074.IP
Juan Cespedesac3db291998-04-25 14:31:58 +020075Note that some shells use the exclamation point for history
76expansion; even inside quoted arguments. If so, you must escape
77the exclamation point with a backslash.
Ian Wienand9a2ad352006-02-20 22:44:45 +010078.TP
Juan Cespedesd65efa32003-02-03 00:22:30 +010079.I \-f
80Trace child processes as they are created by
Juan Cespedesc4e53a92009-05-06 20:36:42 +020081currently traced processes as a result of the fork(2)
Juan Cespedesd65efa32003-02-03 00:22:30 +010082or clone(2) system calls.
Juan Cespedesc4e53a92009-05-06 20:36:42 +020083The new process is attached immediately.
Ian Wienand9a2ad352006-02-20 22:44:45 +010084.TP
Steve Fink58c73a72006-07-17 23:18:35 +020085.I \-F
86Load an alternate config file. Normally, /etc/ltrace.conf and
87~/.ltrace.conf will be read (the latter only if it exists).
88Use this option to load the given file or files instead of
89those two default files.
90.TP
Juan Cespedesac3db291998-04-25 14:31:58 +020091.I \-h, \-\-help
92Show a summary of the options to ltrace and exit.
Ian Wienand9a2ad352006-02-20 22:44:45 +010093.TP
Juan Cespedesd65efa32003-02-03 00:22:30 +010094.I \-i
95Print the instruction pointer at the time of the library call.
Ian Wienand9a2ad352006-02-20 22:44:45 +010096.TP
Juan Cespedesd65efa32003-02-03 00:22:30 +010097.I \-l, \-\-library filename
98Display only the symbols included in the library
99.I filename.
Juan Cespedesaee09312007-08-31 18:49:48 +0200100Up to 30 library names can be specified with several instances
Juan Cespedesd65efa32003-02-03 00:22:30 +0100101of this option.
Ian Wienand9a2ad352006-02-20 22:44:45 +0100102.TP
Juan Cespedesd65efa32003-02-03 00:22:30 +0100103.I \-L
104DON'T display library calls (use it with the
105.I \-S
106option).
Ian Wienand9a2ad352006-02-20 22:44:45 +0100107.TP
Juan Cespedesd65efa32003-02-03 00:22:30 +0100108.I \-n, \-\-indent nr
109Indent trace output by
110.I nr
111number of spaces for each new nested call. Using this option makes
112the program flow visualization easy to follow.
Ian Wienand9a2ad352006-02-20 22:44:45 +0100113.TP
Juan Cespedesd65efa32003-02-03 00:22:30 +0100114.I \-o, \-\-output filename
115Write the trace output to the file
116.I filename
117rather than to stderr.
Ian Wienand9a2ad352006-02-20 22:44:45 +0100118.TP
Juan Cespedesd65efa32003-02-03 00:22:30 +0100119.I \-p pid
120Attach to the process with the process ID
121.I pid
122and begin tracing.
Ian Wienand9a2ad352006-02-20 22:44:45 +0100123.TP
Juan Cespedesd65efa32003-02-03 00:22:30 +0100124.I \-r
125Print a relative timestamp with each line of the trace.
126This records the time difference between the beginning of
127successive lines.
Ian Wienand9a2ad352006-02-20 22:44:45 +0100128.TP
Juan Cespedesd65efa32003-02-03 00:22:30 +0100129.I \-s strsize
130Specify the maximum string size to print (the default is 32).
Ian Wienand9a2ad352006-02-20 22:44:45 +0100131.TP
Juan Cespedesd65efa32003-02-03 00:22:30 +0100132.I \-S
133Display system calls as well as library calls
Ian Wienand9a2ad352006-02-20 22:44:45 +0100134.TP
Juan Cespedesd65efa32003-02-03 00:22:30 +0100135.I \-t
136Prefix each line of the trace with the time of day.
Ian Wienand9a2ad352006-02-20 22:44:45 +0100137.TP
Juan Cespedesd65efa32003-02-03 00:22:30 +0100138.I \-tt
139If given twice, the time printed will include the microseconds.
Ian Wienand9a2ad352006-02-20 22:44:45 +0100140.TP
Juan Cespedesd65efa32003-02-03 00:22:30 +0100141.I \-ttt
142If given thrice, the time printed will include the microseconds and
143the leading portion will be printed as the number of seconds since the
144epoch.
Ian Wienand9a2ad352006-02-20 22:44:45 +0100145.TP
Juan Cespedesd65efa32003-02-03 00:22:30 +0100146.I \-T
147Show the time spent inside each call. This records the time difference
148between the beginning and the end of each call.
Ian Wienand9a2ad352006-02-20 22:44:45 +0100149.TP
Juan Cespedesd65efa32003-02-03 00:22:30 +0100150.I \-u username
151Run command with the userid, groupid and supplementary groups of
Ian Wienand9a2ad352006-02-20 22:44:45 +0100152.IR username .
Juan Cespedesd65efa32003-02-03 00:22:30 +0100153This option is only useful when running as root and enables the
154correct execution of setuid and/or setgid binaries.
Ian Wienand9a2ad352006-02-20 22:44:45 +0100155.TP
156.I \-X extern
157Some architectures need to know where to set a breakpoint that will be hit
158after the dynamic linker has run. If this flag is used, then the breakpoint
159is set at
160.IR extern ,
Paul Gilliambe320772006-04-24 22:06:23 +0200161which must be an external function. By default, '_start' is used.
162NOTE: this flag is only available on the architectures that need it.
Ian Wienand9a2ad352006-02-20 22:44:45 +0100163.TP
164.I \-x extern
165Trace the external function
166.IR extern .
167This option may be repeated.
168.TP
Juan Cespedesac3db291998-04-25 14:31:58 +0200169.I \-V, \-\-version
170Show the version number of ltrace and exit.
Juan Cespedes07461b61997-08-22 15:29:10 +0200171
Ian Wienand9a2ad352006-02-20 22:44:45 +0100172.SH BUGS
Juan Cespedesac3db291998-04-25 14:31:58 +0200173It has most of the bugs stated in
174.BR strace(1) .
Ian Wienand9a2ad352006-02-20 22:44:45 +0100175.LP
176Manual page and documentation are not very up-to-date.
177.LP
178Option -f sometimes fails to trace some children.
179.LP
Juan Cespedes5c3fe062004-06-14 18:08:37 +0200180It only works on Linux and in a small subset of architectures.
Ian Wienand9a2ad352006-02-20 22:44:45 +0100181.LP
Juan Cespedesb1dd77d2002-03-03 00:22:06 +0100182Only ELF32 binaries are supported.
Ian Wienand4128b9d2006-02-20 22:54:19 +0100183.LP
184Calls to dlopen()ed libraries will not be traced.
Ian Wienand9a2ad352006-02-20 22:44:45 +0100185.PP
Steve Fink7ab8df12006-08-07 04:06:16 +0200186If you would like to report a bug, send a message to the mailing list
187(ltrace-devel@lists.alioth.debian.org), or use the
Ian Wienandbf312a12006-02-20 23:28:35 +0100188.BR reportbug(1)
Juan Cespedesac3db291998-04-25 14:31:58 +0200189program if you are under the Debian GNU/Linux distribution.
Juan Cespedes07461b61997-08-22 15:29:10 +0200190
Ian Wienand9a2ad352006-02-20 22:44:45 +0100191.SH FILES
192.TP
Juan Cespedes5e01f651998-03-08 22:31:44 +0100193.I /etc/ltrace.conf
194System configuration file
Ian Wienand9a2ad352006-02-20 22:44:45 +0100195.TP
Juan Cespedes5e01f651998-03-08 22:31:44 +0100196.I ~/.ltrace.conf
197Personal config file, overrides
198.I /etc/ltrace.conf
199
Ian Wienand9a2ad352006-02-20 22:44:45 +0100200.SH AUTHOR
Juan Cespedes64e793b1997-09-11 23:22:36 +0200201Juan Cespedes <cespedes@debian.org>
Juan Cespedes07461b61997-08-22 15:29:10 +0200202
203.SH "SEE ALSO"
204.BR strace(1) ,
205.BR ptrace(2)
206