Petr Machata | 11f23ba | 2012-10-25 03:39:59 +0200 | [diff] [blame] | 1 | .\" -*-nroff-*- |
Petr Machata | 94773bf | 2014-01-14 16:01:35 +0100 | [diff] [blame] | 2 | .\" Copyright (c) 2012, 2013, 2014 Petr Machata, Red Hat Inc. |
Ian Wienand | 9a2ad35 | 2006-02-20 22:44:45 +0100 | [diff] [blame] | 3 | .\" Copyright (c) 1997-2005 Juan Cespedes <cespedes@debian.org> |
Petr Machata | 11f23ba | 2012-10-25 03:39:59 +0200 | [diff] [blame] | 4 | .\" |
| 5 | .\" This program is free software; you can redistribute it and/or |
| 6 | .\" modify it under the terms of the GNU General Public License as |
| 7 | .\" published by the Free Software Foundation; either version 2 of the |
| 8 | .\" License, or (at your option) any later version. |
| 9 | .\" |
| 10 | .\" This program is distributed in the hope that it will be useful, but |
| 11 | .\" WITHOUT ANY WARRANTY; without even the implied warranty of |
| 12 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| 13 | .\" General Public License for more details. |
| 14 | .\" |
| 15 | .\" You should have received a copy of the GNU General Public License |
| 16 | .\" along with this program; if not, write to the Free Software |
| 17 | .\" Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA |
| 18 | .\" 02110-1301 USA |
| 19 | .\" |
Petr Machata | 4b3bda4 | 2013-01-11 23:32:17 +0100 | [diff] [blame] | 20 | .TH LTRACE "1" "January 2013" "" "User Commands" |
Ian Wienand | 9a2ad35 | 2006-02-20 22:44:45 +0100 | [diff] [blame] | 21 | .SH NAME |
Juan Cespedes | 07461b6 | 1997-08-22 15:29:10 +0200 | [diff] [blame] | 22 | ltrace \- A library call tracer |
| 23 | |
Ian Wienand | 9a2ad35 | 2006-02-20 22:44:45 +0100 | [diff] [blame] | 24 | .SH SYNOPSIS |
Petr Machata | 4b3bda4 | 2013-01-11 23:32:17 +0100 | [diff] [blame] | 25 | .\" |
| 26 | .\" --------------------------------------------------------------------------- |
| 27 | .\" |
| 28 | .PP |
Juan Cespedes | 07461b6 | 1997-08-22 15:29:10 +0200 | [diff] [blame] | 29 | .B ltrace |
Petr Machata | 4b3bda4 | 2013-01-11 23:32:17 +0100 | [diff] [blame] | 30 | .\" |
| 31 | .\" What events to trace: |
| 32 | .\" |
| 33 | [\-e \fIfilter\fR|\-L] [\-l|\-\-library=\fIlibrary_pattern\fR] |
| 34 | [\-x \fIfilter\fR] [\-S] [\-b|\-\-no-signals] |
| 35 | .\" |
| 36 | .\" What to display with each event: |
| 37 | .\" |
| 38 | [\-i] [\-w|\-\-where=\fInr\fR] [\-r|\-t|\-tt|\-ttt] [\-T] |
| 39 | .\" |
| 40 | .\" Output formatting: |
| 41 | .\" |
Petr Machata | 5da68e9 | 2014-02-28 12:37:15 +0100 | [diff] [blame] | 42 | [[\-F|\-\-config] \fIpathlist\fR] |
Petr Machata | 4b3bda4 | 2013-01-11 23:32:17 +0100 | [diff] [blame] | 43 | [\-A \fImaxelts\fR] [\-s \fIstrsize\fR] [\-C|\-\-demangle] |
| 44 | [\-a|\-\-align \fIcolumn\fR] [\-n|\-\-indent \fInr\fR] |
| 45 | [\-o|\-\-output \fIfilename\fR] |
| 46 | .\" |
| 47 | .\" Various: |
| 48 | .\" |
| 49 | [\-D|\-\-debug \fImask\fR] [\-u \fIusername\fR] |
| 50 | .\" |
| 51 | .\" What processes to trace: |
| 52 | .\" |
| 53 | [\-f] [\-p \fIpid\fR] [[\-\-] \fIcommand [arg ...]\fR] |
| 54 | .\" |
| 55 | .\" --------------------------------------------------------------------------- |
| 56 | .\" |
| 57 | .PP |
Juan Cespedes | f194715 | 2014-01-05 17:24:50 +0100 | [diff] [blame] | 58 | .BR ltrace " \-c" |
Petr Machata | 4b3bda4 | 2013-01-11 23:32:17 +0100 | [diff] [blame] | 59 | .\" |
| 60 | .\" What events to trace: |
| 61 | .\" |
| 62 | [\-e \fIfilter\fR|\-L] [\-l|\-\-library=\fIlibrary_pattern\fR] |
| 63 | [\-x \fIfilter\fR] [\-S] |
| 64 | .\" |
| 65 | .\" Output formatting: |
| 66 | .\" |
| 67 | [\-o|\-\-output \fIfilename\fR] |
| 68 | .\" |
| 69 | .\" What processes to trace: |
| 70 | .\" |
| 71 | [\-f] [\-p \fIpid\fR] [[\-\-] \fIcommand [arg ...]\fR] |
| 72 | .\" |
| 73 | .\" --------------------------------------------------------------------------- |
| 74 | .\" |
| 75 | .PP |
| 76 | .BR ltrace " \-V|\-\-version" |
| 77 | .PP |
| 78 | .BR ltrace " \-h|\-\-help" |
Juan Cespedes | 07461b6 | 1997-08-22 15:29:10 +0200 | [diff] [blame] | 79 | |
Ian Wienand | 9a2ad35 | 2006-02-20 22:44:45 +0100 | [diff] [blame] | 80 | .SH DESCRIPTION |
Juan Cespedes | 07461b6 | 1997-08-22 15:29:10 +0200 | [diff] [blame] | 81 | .B ltrace |
| 82 | is a program that simply runs the specified |
| 83 | .I command |
| 84 | until it exits. It intercepts and records the dynamic library calls |
| 85 | which are called by the executed process and the signals which are |
| 86 | received by that process. |
Juan Cespedes | ac3db29 | 1998-04-25 14:31:58 +0200 | [diff] [blame] | 87 | It can also intercept and print the system calls executed by the program. |
Ian Wienand | 9a2ad35 | 2006-02-20 22:44:45 +0100 | [diff] [blame] | 88 | .PP |
Juan Cespedes | 07461b6 | 1997-08-22 15:29:10 +0200 | [diff] [blame] | 89 | Its use is very similar to |
Juan Cespedes | 81690ef | 1998-03-13 19:31:29 +0100 | [diff] [blame] | 90 | .BR strace(1) . |
Juan Cespedes | 07461b6 | 1997-08-22 15:29:10 +0200 | [diff] [blame] | 91 | |
Petr Machata | 5649900 | 2013-09-19 23:44:54 +0200 | [diff] [blame] | 92 | .B ltrace |
| 93 | shows parameters of invoked functions and system calls. To determine |
| 94 | what arguments each function has, it needs external declaration of |
| 95 | function prototypes. Those are stored in files called \fIprototype |
| 96 | libraries\fR--see ltrace.conf(5) for details on the syntax of these |
| 97 | files. See the section \fBPROTOTYPE LIBRARY DISCOVERY\fR to learn how |
| 98 | \fBltrace\fR finds prototype libraries. |
| 99 | |
Ian Wienand | 9a2ad35 | 2006-02-20 22:44:45 +0100 | [diff] [blame] | 100 | .SH OPTIONS |
Petr Machata | 4b3bda4 | 2013-01-11 23:32:17 +0100 | [diff] [blame] | 101 | .PP |
| 102 | .IP "\-a, \-\-align \fIcolumn" |
Joe Damato | fa2aefc | 2010-10-30 19:56:50 -0700 | [diff] [blame] | 103 | Align return values in a specific |
| 104 | .IR column |
| 105 | (default column is 5/8 of screen width). |
Petr Machata | 4b3bda4 | 2013-01-11 23:32:17 +0100 | [diff] [blame] | 106 | .IP "\-A \fImaxelts" |
Petr Machata | 8c98e40 | 2012-11-19 01:30:31 +0100 | [diff] [blame] | 107 | Maximum number of array elements to print before suppressing the rest |
| 108 | with an ellipsis ("..."). This also limits number of recursive |
| 109 | structure expansions. |
Petr Machata | 4b3bda4 | 2013-01-11 23:32:17 +0100 | [diff] [blame] | 110 | .IP "\-b, \-\-no-signals" |
Juan Cespedes | f194715 | 2014-01-05 17:24:50 +0100 | [diff] [blame] | 111 | Disable printing of signals received by the traced process. |
Petr Machata | 4b3bda4 | 2013-01-11 23:32:17 +0100 | [diff] [blame] | 112 | .IP \-c |
| 113 | Count time and calls for each library call and report a summary on |
| 114 | program exit. |
| 115 | .IP "\-C, \-\-demangle" |
Ian Wienand | 9a2ad35 | 2006-02-20 22:44:45 +0100 | [diff] [blame] | 116 | Decode (demangle) low-level symbol names into user-level names. |
Justin Pryzby | fda2c6f | 2006-07-18 00:05:26 +0200 | [diff] [blame] | 117 | Besides removing any initial underscore prefix used by the system, |
Juan Cespedes | ac3db29 | 1998-04-25 14:31:58 +0200 | [diff] [blame] | 118 | this makes C++ function names readable. |
Petr Machata | 4b3bda4 | 2013-01-11 23:32:17 +0100 | [diff] [blame] | 119 | .IP "\-D, \-\-debug \fRmask\fI" |
| 120 | Show debugging output of \fBltrace\fR itself. \fImask\fR is a number |
Petr Machata | 94773bf | 2014-01-14 16:01:35 +0100 | [diff] [blame] | 121 | describing which debug messages should be displayed. Use the option |
| 122 | \-Dh to see what can be used, but note that currently the only |
| 123 | reliable debugmask is 77, which shows all debug messages. |
Petr Machata | 4b3bda4 | 2013-01-11 23:32:17 +0100 | [diff] [blame] | 124 | .IP "\-e \fIfilter" |
Petr Machata | 4e1c066 | 2012-04-24 00:50:07 +0200 | [diff] [blame] | 125 | A qualifying expression which modifies which library calls to trace. |
| 126 | The format of the filter expression is described in the section |
| 127 | \fBFILTER EXPRESSIONS\fR. If more than one \-e option appears on the |
| 128 | command line, the library calls that match any of them are traced. If |
| 129 | no \-e is given, \fB@MAIN\fR is assumed as a default. |
Petr Machata | 4b3bda4 | 2013-01-11 23:32:17 +0100 | [diff] [blame] | 130 | .IP \-f |
Juan Cespedes | d65efa3 | 2003-02-03 00:22:30 +0100 | [diff] [blame] | 131 | Trace child processes as they are created by |
Juan Cespedes | c4e53a9 | 2009-05-06 20:36:42 +0200 | [diff] [blame] | 132 | currently traced processes as a result of the fork(2) |
Juan Cespedes | d65efa3 | 2003-02-03 00:22:30 +0100 | [diff] [blame] | 133 | or clone(2) system calls. |
Juan Cespedes | c4e53a9 | 2009-05-06 20:36:42 +0200 | [diff] [blame] | 134 | The new process is attached immediately. |
Petr Machata | 5da68e9 | 2014-02-28 12:37:15 +0100 | [diff] [blame] | 135 | .IP "\-F, \-\-config \fIpathlist" |
Petr Machata | 5649900 | 2013-09-19 23:44:54 +0200 | [diff] [blame] | 136 | Contains a colon-separated list of paths. If a path refers to a |
| 137 | directory, that directory is considered when prototype libraries are |
| 138 | searched (see the section \fBPROTOTYPE LIBRARY DISCOVERY\fR). If it refers to |
| 139 | a file, that file is imported implicitly to all loaded prototype |
| 140 | libraries. |
Petr Machata | 4b3bda4 | 2013-01-11 23:32:17 +0100 | [diff] [blame] | 141 | .IP "\-h, \-\-help" |
Juan Cespedes | ac3db29 | 1998-04-25 14:31:58 +0200 | [diff] [blame] | 142 | Show a summary of the options to ltrace and exit. |
Petr Machata | 4b3bda4 | 2013-01-11 23:32:17 +0100 | [diff] [blame] | 143 | .IP \-i |
Juan Cespedes | d65efa3 | 2003-02-03 00:22:30 +0100 | [diff] [blame] | 144 | Print the instruction pointer at the time of the library call. |
Petr Machata | 4b3bda4 | 2013-01-11 23:32:17 +0100 | [diff] [blame] | 145 | .IP "\-l, \-\-library \fIlibrary_pattern" |
Petr Machata | 9265da4 | 2012-11-02 02:56:08 +0100 | [diff] [blame] | 146 | Display only calls to functions implemented by libraries that match |
Petr Machata | 51e74ac | 2012-09-27 23:43:25 +0200 | [diff] [blame] | 147 | .I library_pattern. |
| 148 | Multiple library patters can be specified with several instances of |
| 149 | this option. Syntax of library_pattern is described in section |
| 150 | \fBFILTER EXPRESSIONS\fR. |
Petr Machata | 90d5ec5 | 2012-11-02 02:58:16 +0100 | [diff] [blame] | 151 | |
| 152 | Note that while this option selects calls that might be directed to |
| 153 | the selected libraries, there's no actual guarantee that the call |
| 154 | won't be directed elsewhere due to e.g. LD_PRELOAD or simply |
| 155 | dependency ordering. If you want to make sure that symbols in given |
| 156 | library are actually called, use \fB-x @\fIlibrary_pattern\fR instead. |
Petr Machata | 4b3bda4 | 2013-01-11 23:32:17 +0100 | [diff] [blame] | 157 | .IP \-L |
Juan Cespedes | f194715 | 2014-01-05 17:24:50 +0100 | [diff] [blame] | 158 | When no \-e option is given, don't assume the default action of |
Petr Machata | 94773bf | 2014-01-14 16:01:35 +0100 | [diff] [blame] | 159 | \fB@MAIN\fR. In practice this means that library calls will not be |
| 160 | traced. |
Petr Machata | 4b3bda4 | 2013-01-11 23:32:17 +0100 | [diff] [blame] | 161 | .IP "\-n, \-\-indent \fInr" |
| 162 | Indent trace output by \fInr\fR spaces for each level of call |
| 163 | nesting. Using this option makes the program flow visualization easy |
| 164 | to follow. This indents uselessly also functions that never return, |
| 165 | such as service functions for throwing exceptions in the C++ runtime. |
| 166 | .IP "\-o, \-\-output \fIfilename" |
| 167 | Write the trace output to the file \fIfilename\fR rather than to |
| 168 | stderr. |
| 169 | .IP "\-p \fIpid" |
| 170 | Attach to the process with the process ID \fIpid\fR and begin tracing. |
| 171 | This option can be used together with passing a command to execute. |
| 172 | It is possible to attach to several processes by passing more than one |
| 173 | option \-p. |
| 174 | .IP \-r |
| 175 | Print a relative timestamp with each line of the trace. This records |
| 176 | the time difference between the beginning of successive lines. |
| 177 | .IP "\-s \fIstrsize" |
Juan Cespedes | d65efa3 | 2003-02-03 00:22:30 +0100 | [diff] [blame] | 178 | Specify the maximum string size to print (the default is 32). |
Petr Machata | 4b3bda4 | 2013-01-11 23:32:17 +0100 | [diff] [blame] | 179 | .IP \-S |
Juan Cespedes | d65efa3 | 2003-02-03 00:22:30 +0100 | [diff] [blame] | 180 | Display system calls as well as library calls |
Petr Machata | 4b3bda4 | 2013-01-11 23:32:17 +0100 | [diff] [blame] | 181 | .IP \-t |
Juan Cespedes | d65efa3 | 2003-02-03 00:22:30 +0100 | [diff] [blame] | 182 | Prefix each line of the trace with the time of day. |
Petr Machata | 4b3bda4 | 2013-01-11 23:32:17 +0100 | [diff] [blame] | 183 | .IP \-tt |
Juan Cespedes | d65efa3 | 2003-02-03 00:22:30 +0100 | [diff] [blame] | 184 | If given twice, the time printed will include the microseconds. |
Petr Machata | 4b3bda4 | 2013-01-11 23:32:17 +0100 | [diff] [blame] | 185 | .IP \-ttt |
Juan Cespedes | d65efa3 | 2003-02-03 00:22:30 +0100 | [diff] [blame] | 186 | If given thrice, the time printed will include the microseconds and |
| 187 | the leading portion will be printed as the number of seconds since the |
| 188 | epoch. |
Petr Machata | 4b3bda4 | 2013-01-11 23:32:17 +0100 | [diff] [blame] | 189 | .IP \-T |
Juan Cespedes | d65efa3 | 2003-02-03 00:22:30 +0100 | [diff] [blame] | 190 | Show the time spent inside each call. This records the time difference |
| 191 | between the beginning and the end of each call. |
Petr Machata | 4b3bda4 | 2013-01-11 23:32:17 +0100 | [diff] [blame] | 192 | .IP "\-u \fIusername" |
Juan Cespedes | d65efa3 | 2003-02-03 00:22:30 +0100 | [diff] [blame] | 193 | Run command with the userid, groupid and supplementary groups of |
Ian Wienand | 9a2ad35 | 2006-02-20 22:44:45 +0100 | [diff] [blame] | 194 | .IR username . |
Juan Cespedes | d65efa3 | 2003-02-03 00:22:30 +0100 | [diff] [blame] | 195 | This option is only useful when running as root and enables the |
| 196 | correct execution of setuid and/or setgid binaries. |
Juan Cespedes | f194715 | 2014-01-05 17:24:50 +0100 | [diff] [blame] | 197 | .IP "\-w, \-\-where \fInr" |
Petr Machata | 4b3bda4 | 2013-01-11 23:32:17 +0100 | [diff] [blame] | 198 | Show backtrace of \fInr\fR stack frames for each traced function. This |
Mark Wielaard | dfefa9f | 2014-01-07 21:00:44 +0100 | [diff] [blame] | 199 | option enabled only if elfutils or libunwind support was enabled at compile |
| 200 | time. |
Petr Machata | 4b3bda4 | 2013-01-11 23:32:17 +0100 | [diff] [blame] | 201 | .IP "\-x \fIfilter" |
Petr Machata | 4e1c066 | 2012-04-24 00:50:07 +0200 | [diff] [blame] | 202 | A qualifying expression which modifies which symbol table entry points |
| 203 | to trace. The format of the filter expression is described in the |
| 204 | section \fBFILTER EXPRESSIONS\fR. If more than one \-x option appears |
| 205 | on the command line, the symbols that match any of them are traced. |
| 206 | No entry points are traced if no \-x is given. |
Petr Machata | 4b3bda4 | 2013-01-11 23:32:17 +0100 | [diff] [blame] | 207 | .IP "\-V, \-\-version" |
Juan Cespedes | ac3db29 | 1998-04-25 14:31:58 +0200 | [diff] [blame] | 208 | Show the version number of ltrace and exit. |
Juan Cespedes | 07461b6 | 1997-08-22 15:29:10 +0200 | [diff] [blame] | 209 | |
Petr Machata | 4e1c066 | 2012-04-24 00:50:07 +0200 | [diff] [blame] | 210 | .SH FILTER EXPRESSIONS |
| 211 | |
| 212 | Filter expression is a chain of glob- or regexp-based rules that are |
| 213 | used to pick symbols for tracing from libraries that the process uses. |
| 214 | Most of it is intuitive, so as an example, the following would trace |
| 215 | calls to malloc and free, except those done by libc: |
| 216 | |
| 217 | -e malloc+free-@libc.so* |
| 218 | |
| 219 | This reads: trace malloc and free, but don't trace anything that comes |
| 220 | from libc. Semi-formally, the syntax of the above example looks |
| 221 | approximately like this: |
| 222 | |
Petr Machata | 964a680 | 2012-06-29 14:27:08 +0200 | [diff] [blame] | 223 | {[+-][\fIsymbol_pattern\fR][@\fIlibrary_pattern\fR]} |
Petr Machata | 4e1c066 | 2012-04-24 00:50:07 +0200 | [diff] [blame] | 224 | |
Petr Machata | 964a680 | 2012-06-29 14:27:08 +0200 | [diff] [blame] | 225 | \fISymbol_pattern\fR is used to match symbol names, |
| 226 | \fIlibrary_pattern\fR to match library SONAMEs. Both are implicitly |
| 227 | globs, but can be regular expressions as well (see below). The glob |
| 228 | syntax supports meta-characters \fB*\fR and \fB?\fR and character |
| 229 | classes, similarly to what basic bash globs support. \fB^\fR and |
| 230 | \fB$\fR are recognized to mean, respectively, start and end of given |
| 231 | name. |
Petr Machata | 4e1c066 | 2012-04-24 00:50:07 +0200 | [diff] [blame] | 232 | |
Petr Machata | 964a680 | 2012-06-29 14:27:08 +0200 | [diff] [blame] | 233 | Both \fIsymbol_pattern\fR and \fIlibrary_pattern\fR have to match the |
| 234 | whole name. If you want to match only part of the name, surround it |
Petr Machata | 4e1c066 | 2012-04-24 00:50:07 +0200 | [diff] [blame] | 235 | with one or two *'s as appropriate. The exception is if the pattern |
| 236 | is not mentioned at all, in which case it's as if the corresponding |
| 237 | pattern were \fB*\fR. (So \fBmalloc\fR is really \fBmalloc@*\fR and |
| 238 | \fB@libc.*\fR is really \fB*@libc.*\fR.) |
| 239 | |
| 240 | In libraries that don't have an explicit SONAME, basename is taken for |
| 241 | SONAME. That holds for main binary as well: \fB/bin/echo\fR has an |
| 242 | implicit SONAME of \fBecho\fR. In addition to that, special library |
| 243 | pattern \fBMAIN\fR always matches symbols in the main binary and never |
| 244 | a library with actual SONAME \fBMAIN\fR (use e.g. \fB^MAIN\fR or |
| 245 | \fB[M]AIN\fR for that). |
| 246 | |
| 247 | If the symbol or library pattern is surrounded in slashes (/like |
| 248 | this/), then it is considered a regular expression instead. As a |
| 249 | shorthand, instead of writing \fB/x/@/y/\fR, you can write |
| 250 | \fB/x@y/\fR. |
| 251 | |
| 252 | If the library pattern starts with a slash, it is not a SONAME |
| 253 | expression, but a path expression, and is matched against the library |
| 254 | path name. |
| 255 | |
| 256 | The first rule may lack a sign, in which case \fB+\fR is assumed. If, |
| 257 | on the other hand, the first rule has a \fB-\fR sign, it is as if |
Petr Machata | 4b3bda4 | 2013-01-11 23:32:17 +0100 | [diff] [blame] | 258 | there was another rule \fB@\fR in front of it, which has the effect of |
| 259 | tracing complement of given rule. |
Petr Machata | 4e1c066 | 2012-04-24 00:50:07 +0200 | [diff] [blame] | 260 | |
| 261 | The above rules are used to construct the set of traced symbols. Each |
| 262 | candidate symbol is passed through the chain of above rules. |
Petr Machata | 964a680 | 2012-06-29 14:27:08 +0200 | [diff] [blame] | 263 | Initially, the symbol is \fIunmarked\fR. If it matches a \fB+\fR |
| 264 | rule, it becomes \fImarked\fR, if it matches a \fB-\fR rule, it |
| 265 | becomes \fIunmarked\fR again. If, after applying all rules, the |
| 266 | symbol is \fImarked\fR, it will be traced. |
Petr Machata | 4e1c066 | 2012-04-24 00:50:07 +0200 | [diff] [blame] | 267 | |
Petr Machata | 5649900 | 2013-09-19 23:44:54 +0200 | [diff] [blame] | 268 | .SH PROTOTYPE LIBRARY DISCOVERY |
| 269 | |
| 270 | When a library is mapped into the address space of a traced process, |
| 271 | ltrace needs to know what the prototypes are of functions that this |
| 272 | library implements. For purposes of ltrace, prototype really is a bit |
| 273 | more than just type signature: it's also formatting of individual |
| 274 | parameters and of return value. These prototypes are stored in files |
| 275 | called prototype libraries. |
| 276 | |
| 277 | After a library is mapped, ltrace finds out what its SONAME is. It |
| 278 | then looks for a file named SONAME.conf--e.g. protolib for libc.so.6 |
| 279 | would be in a file called libc.so.6.conf. When such file is found |
| 280 | (more about where ltrace looks for these files is below), ltrace reads |
| 281 | all prototypes stored therein. When a symbol table entry point (such |
Juan Cespedes | f194715 | 2014-01-05 17:24:50 +0100 | [diff] [blame] | 282 | as those traced by \-x) is hit, the prototype is looked up in a |
| 283 | prototype library corresponding to the library where the hit occurred. |
| 284 | When a library call (such as those traced by \-e and \-l) is hit, the |
Petr Machata | 5649900 | 2013-09-19 23:44:54 +0200 | [diff] [blame] | 285 | prototype is looked up in all prototype libraries loaded for given |
| 286 | process. That is necessary, because a library call is traced in a PLT |
| 287 | table of a caller library, but the prototype is described at callee |
| 288 | library. |
| 289 | |
| 290 | If a library has no SONAME, basename of library file is considered |
| 291 | instead. For the main program binary, basename is considered as well |
Petr Machata | 98a7dce | 2013-10-23 17:37:47 +0200 | [diff] [blame] | 292 | (e.g. protolib for /bin/echo would be called echo.conf). If a name |
| 293 | corresponding to soname (e.g. libc.so.6.conf) is not found, and the |
| 294 | module under consideration is a shared library, ltrace also tries |
| 295 | partial matches. Ltrace snips one period after another, retrying the |
| 296 | search, until either a protolib is found, or X.so is all that's left. |
| 297 | Thus libc.so.conf would be considered, but libc.conf not. |
Petr Machata | 5649900 | 2013-09-19 23:44:54 +0200 | [diff] [blame] | 298 | |
| 299 | When looking for a prototype library, ltrace potentially looks into |
| 300 | several directories. On Linux, those are $XDG_CONFIG_HOME/ltrace, |
Petr Machata | aa3db6b | 2013-10-23 00:52:13 +0200 | [diff] [blame] | 301 | $HOME/.ltrace, \fIX\fR/ltrace for each \fIX\fR in $XDG_CONFIG_DIRS and |
| 302 | /usr/share/ltrace. If the environment variable XDG_CONFIG_HOME is not |
| 303 | defined, ltrace looks into $HOME/.config/ltrace instead. |
Petr Machata | 5649900 | 2013-09-19 23:44:54 +0200 | [diff] [blame] | 304 | |
| 305 | There's also a mechanism for loading legacy config files. If |
| 306 | $HOME/.ltrace.conf exists it is imported to every loaded prototype |
| 307 | library. Similarly for /etc/ltrace.conf. If both exist, both are |
| 308 | imported, and $HOME/.ltrace.conf is consulted before /etc/ltrace.conf. |
| 309 | |
Juan Cespedes | f194715 | 2014-01-05 17:24:50 +0100 | [diff] [blame] | 310 | If \-F contains any directories, those are searched in precedence to |
Petr Machata | 5649900 | 2013-09-19 23:44:54 +0200 | [diff] [blame] | 311 | the above system directories, in the same order in which they are |
Juan Cespedes | f194715 | 2014-01-05 17:24:50 +0100 | [diff] [blame] | 312 | mentioned in \-F. Any files passed in \-F are imported similarly to |
Petr Machata | 5649900 | 2013-09-19 23:44:54 +0200 | [diff] [blame] | 313 | above legacy config files, before them. |
| 314 | |
| 315 | See ltrace.conf(5) for details on the syntax of ltrace prototype |
| 316 | library files. |
| 317 | |
Ian Wienand | 9a2ad35 | 2006-02-20 22:44:45 +0100 | [diff] [blame] | 318 | .SH BUGS |
Juan Cespedes | ac3db29 | 1998-04-25 14:31:58 +0200 | [diff] [blame] | 319 | It has most of the bugs stated in |
| 320 | .BR strace(1) . |
Ian Wienand | 9a2ad35 | 2006-02-20 22:44:45 +0100 | [diff] [blame] | 321 | .LP |
Juan Cespedes | 6aafe55 | 2014-01-09 12:18:46 +0100 | [diff] [blame] | 322 | It only works on Linux and in some architectures. |
Ian Wienand | 9a2ad35 | 2006-02-20 22:44:45 +0100 | [diff] [blame] | 323 | .LP |
Ian Wienand | 9a2ad35 | 2006-02-20 22:44:45 +0100 | [diff] [blame] | 324 | .PP |
Steve Fink | 7ab8df1 | 2006-08-07 04:06:16 +0200 | [diff] [blame] | 325 | If you would like to report a bug, send a message to the mailing list |
| 326 | (ltrace-devel@lists.alioth.debian.org), or use the |
Ian Wienand | bf312a1 | 2006-02-20 23:28:35 +0100 | [diff] [blame] | 327 | .BR reportbug(1) |
Juan Cespedes | ac3db29 | 1998-04-25 14:31:58 +0200 | [diff] [blame] | 328 | program if you are under the Debian GNU/Linux distribution. |
Juan Cespedes | 07461b6 | 1997-08-22 15:29:10 +0200 | [diff] [blame] | 329 | |
Ian Wienand | 9a2ad35 | 2006-02-20 22:44:45 +0100 | [diff] [blame] | 330 | .SH FILES |
| 331 | .TP |
Juan Cespedes | 5e01f65 | 1998-03-08 22:31:44 +0100 | [diff] [blame] | 332 | .I /etc/ltrace.conf |
| 333 | System configuration file |
Ian Wienand | 9a2ad35 | 2006-02-20 22:44:45 +0100 | [diff] [blame] | 334 | .TP |
Juan Cespedes | 5e01f65 | 1998-03-08 22:31:44 +0100 | [diff] [blame] | 335 | .I ~/.ltrace.conf |
| 336 | Personal config file, overrides |
| 337 | .I /etc/ltrace.conf |
| 338 | |
Ian Wienand | 9a2ad35 | 2006-02-20 22:44:45 +0100 | [diff] [blame] | 339 | .SH AUTHOR |
Juan Cespedes | 64e793b | 1997-09-11 23:22:36 +0200 | [diff] [blame] | 340 | Juan Cespedes <cespedes@debian.org> |
Petr Machata | 4e1c066 | 2012-04-24 00:50:07 +0200 | [diff] [blame] | 341 | .br |
| 342 | Petr Machata <pmachata@redhat.com> |
Juan Cespedes | 07461b6 | 1997-08-22 15:29:10 +0200 | [diff] [blame] | 343 | |
| 344 | .SH "SEE ALSO" |
Petr Machata | 11f23ba | 2012-10-25 03:39:59 +0200 | [diff] [blame] | 345 | .BR ltrace.conf(5), |
Juan Cespedes | 07461b6 | 1997-08-22 15:29:10 +0200 | [diff] [blame] | 346 | .BR strace(1) , |
| 347 | .BR ptrace(2) |