| blob | 87214993d76e4b562466cde3656d83635e598fb5 |
1 '\" te
2 .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH APPTRACE 1 "Nov 29, 2004"
7 .SH NAME
8 apptrace \- trace application function calls to Solaris shared libraries
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBapptrace\fR [\fB-f\fR] [\fB-F\fR [!] \fItracefromlist\fR] [\fB-T\fR [!] \fItracetolist\fR]
13 [\fB-o\fR \fIoutputfile\fR] [ [\fB-tv\fR] [!] \fIcall\fR ,...] \fIcommand\fR
14 [\fIcommand\fR \fIarguments\fR]
15 .fi
17 .SH DESCRIPTION
18 .sp
19 .LP
20 The \fBapptrace\fR utility runs the executable program specified by
21 \fIcommand\fR and traces all function calls that the program\fIcommand\fR makes
22 to the Solaris shared libraries. For each function call that is traceable,
23 \fBapptrace\fR reports the name of the library interface called, the values of
24 the arguments passed, and the return value.
25 .sp
26 .LP
27 By default, \fBapptrace\fR traces calls directly from the executable object to
28 any of the shared objects it depends on. Indirect calls (that is, calls made
29 between shared objects that the executable depends upon) are not reported by
30 default.
31 .sp
32 .LP
33 Calls from or to additional shared objects may be traced using the \fB-F\fR or
34 \fB-T\fR options (see below).
35 .sp
36 .LP
37 The default reporting format is a single line per call, with no formatted
38 printing of arguments passed by reference or of data structures.
39 .sp
40 .LP
41 Formatted printing providing additional argument details is obtained using the
42 \fB-v\fR option (see below).
43 .sp
44 .LP
45 By default, every interface provided by a shared object is traced if called.
46 However, the set of interfaces to be traced can be restricted, using the
47 \fB-t\fR and/or \fB-v\fR options.
48 .sp
49 .LP
50 Since it is generally possible to trace calls between any of the dynamic
51 objects linked at runtime (the executable object and any of the shared objects
52 depended upon), the report of each traced call gives the name of the object
53 from which the call was made.
54 .sp
55 .LP
56 \fBapptrace\fR traces all of the procedure calls that occur between dynamic
57 objects via the procedure linkage table, so only those procedure calls which
58 are bound via the table will be traced. See the \fILinker and Libraries
59 Guide\fR.
60 .SH OPTIONS
61 .sp
62 .LP
63 The following options are supported:
64 .sp
65 .ne 2
66 .na
67 \fB\fB-f\fR \fR
68 .ad
69 .RS 24n
70 Follows all children created by \fBfork\fR(2). This option will also cause the
71 process id to be printed at the beginning of each line.
72 .RE
74 .sp
75 .ne 2
76 .na
77 \fB\fB-F\fR \fB[!]\fR\fItracefromlist\fR \fR
78 .ad
79 .RS 24n
80 Traces calls from a comma-separated list of shared objects. Only calls from
81 these shared objects will be traced. The default is to trace calls from the
82 main executable only. Only the basename of the shared object is required. For
83 example, \fIlibc\fR will match \fI/usr/lib/libc.so.1\fR. Additionally, shell
84 style wildcard characters are supported as described in \fBfnmatch\fR(5). A
85 list preceded by a ``!'' defines a list of objects from which calls should not
86 be traced. If the tracing of calls from \fIcommand\fR is required, then
87 \fIcommand\fR must be a member of \fItracefromlist\fR.
88 .RE
90 .sp
91 .ne 2
92 .na
93 \fB\fB-o\fR \fIoutputfile\fR \fR
94 .ad
95 .RS 24n
96 \fBapptrace\fR output will be directed to the \fIoutputfile\fR. By default,
97 \fBapptrace\fR output is placed on the stderr stream of the process being
98 traced.
99 .RE
101 .sp
102 .ne 2
103 .na
104 \fB\fB-t\fR [\fB!\fR]\fIcall,\|.\|.\|.\fR\fR
105 .ad
106 .RS 24n
107 Traces or excludes function calls. Those calls specified in the comma-separated
108 list \fIcall\fR are traced. If the list begins with a !, the specified function
109 calls are excluded from the trace output. The default is \fB-t\fR \fB*\fR. The
110 use of shell style wildcards is allowed.
111 .RE
113 .sp
114 .ne 2
115 .na
116 \fB\fB-T\fR \fB[!]\fR\fItracetolist\fR \fR
117 .ad
118 .RS 24n
119 Traces calls to a comma-separated list of shared objects. The default is to
120 trace calls to all shared objects. As above, the basename is all that is
121 required and wildcarding is allowed. A list preceded by a ``!'' denotes a list
122 of objects to which calls should not be traced.
123 .RE
125 .sp
126 .ne 2
127 .na
128 \fB\fB-v\fR [\fB!\fR]\fIcall,\|.\|.\|.\fR\fR
129 .ad
130 .RS 24n
131 Provides verbose, formatted output of the arguments and return values of the
132 function calls specified (as above in the \fB-t\fR option). Unlike
133 \fBtruss\fR(1), calls named by the \fB-v\fR option do not have to be named by
134 the \fB-t\fR option. For example, \fBapptrace\fR \fB-v\fR \fBopen\fR is
135 equivalent to \fBtruss\fR \fB-t\fR \fBopen\fR \fB-v\fR \fBopen\fR.
136 .RE
138 .SH EXAMPLES
139 .LP
140 \fBExample 1 \fRTracing the date command
141 .sp
142 .in +2
143 .nf
144 % \fBapptrace date\fR
145 -> date -> libc.so.1:atexit(0xff3bf9ac, 0x22000, 0x0) ** NR
146 -> date -> libc.so.1:atexit(0x11550, 0xfefeef80, 0xab268) ** NR
147 -> date -> libc.so.1:setlocale(0x6, 0x11560, 0x0) ** NR
148 -> date -> libc.so.1:textdomain(0x11564, 0xfefce156, 0xff160200) ** NR
149 -> date -> libc.so.1:int getopt(int = 0x1,
150 const char * * = 0xffbffa5c,
151 const char * = 0x11574 "a:u")
152 <- date -> libc.so.1:getopt() = 0xffffffff
153 -> date -> libc.so.1:time_t time(time_t * = 0x225c0)
154 <- date -> libc.so.1:time() = 0x41ab6e82
155 -> date -> libc.so.1:char * nl_langinfo(nl_item = 0x3a)
156 <- date -> libc.so.1:nl_langinfo() = 0xfefd3e10
157 -> date -> libc.so.1:struct tm * localtime(const time_t * = 0x225c0)
158 <- date -> libc.so.1:localtime() = 0xff160240
159 -> date -> libc_psr.so.1:memcpy(0xffbff9cc, 0xff160240, 0x24) ** NR
160 -> date -> libc.so.1:size_t strftime(char * = 0x225c4 "",
161 size_t = 0x400,
162 const char * = 0xfefd3e10 "%a %b %e %T %Z %Y",
163 const struct tm * = 0xffbff9cc)
164 <- date -> libc.so.1:strftime() = 0x1c
165 -> date -> libc.so.1:int puts(const char * = 0x225c4
166 "Mon Nov 29 10:46:26 PST 2004")
167 Mon Nov 29 10:46:26 PST 2004
168 <- date -> libc.so.1:puts() = 0x1d
169 -> date -> libc.so.1:exit(0x0, 0x22400, 0x0) ** NR
170 .fi
171 .in -2
172 .sp
174 .LP
175 \fBExample 2 \fRTracing a specific set of interfaces with verbosity set
176 .sp
177 .in +2
178 .nf
179 % \fBapptrace -v localtime,strftime,puts date\fR
180 -> date -> libc.so.1:struct tm * localtime(const time_t * = 0x225c0)
181 arg0 = (const time_t *) 0x225c0
182 return = (struct tm *) 0xff160280 (struct tm) {
183 tm_sec: (int) 0x4
184 tm_min: (int) 0x34
185 tm_hour: (int) 0xa
186 tm_mday: (int) 0x1d
187 tm_mon: (int) 0xa
188 tm_year: (int) 0x68
189 tm_wday: (int) 0x1
190 tm_yday: (int) 0x14d
191 tm_isdst: (int) 0
192 }
193 <- date -> libc.so.1:localtime() = 0xff160280
194 -> date -> libc.so.1:size_t strftime(char * = 0x225c4 "",
195 size_t = 0x400,
196 const char * = 0xfefd3e10 "%a %b %e %T %Z %Y",
197 const struct tm * = 0xffbff99c)
198 arg0 = (char *) 0x225c4 ""
199 arg1 = (size_t) 0x400
200 arg2 = (const char *) 0xfefd3e10 "%a %b %e %T %Z %Y"
201 arg3 = (const struct tm *) 0xffbff99c (struct tm) {
202 tm_sec: (int) 0x4
203 tm_min: (int) 0x34
204 tm_hour: (int) 0xa
205 tm_mday: (int) 0x1d
206 tm_mon: (int) 0xa
207 tm_year: (int) 0x68
208 tm_wday: (int) 0x1
209 tm_yday: (int) 0x14d
210 tm_isdst: (int) 0
211 }
212 return = (size_t) 0x1c
213 <- date -> libc.so.1:strftime() = 0x1c
214 -> date -> libc.so.1:int puts(const char * = 0x225c4
215 "Mon Nov 29 10:52:04 PST 2004")
216 arg0 = (const char *) 0x225c4 "Mon Nov 29 10:52:04 PST 2004"
217 Mon Nov 29 10:52:04 PST 2004
218 return = (int) 0x1d
219 <- date -> libc.so.1:puts() = 0x1d
220 .fi
221 .in -2
222 .sp
224 .sp
225 .LP
226 ** NR - The return value of a function call will not be traced.
227 .SH FILES
228 .sp
229 .LP
230 Basic runtime support for \fBapptrace\fR is provided by the link auditing
231 feature of the Solaris runtime linker (\fBld.so.1\fR(1)) and the \fBapptrace\fR
232 command's use of this facility relies on an auditing object
233 (\fBapptrace.so.1\fR) kept in \fB/usr/lib/abi\fR.
234 .SH LIMITATIONS
235 .sp
236 .LP
237 In general, \fBapptrace\fR cannot trace calls to functions accepting variable
238 argument lists. There has been some clever coding in several specific cases to
239 work around this limitation, most notably in the \fBprintf\fR and \fBscanf\fR
240 families.
241 .sp
242 .LP
243 The \fBapptrace\fR utility can not trace the return value of a function call
244 whose return type is a \fBstruct\fR or \fBunion\fR.
245 .sp
246 .LP
247 Functions that attempt to probe the stack or otherwise extract information
248 about the caller cannot be traced. Some examples are \fB[gs]etcontext()\fR,
249 \fB[sig]longjmp()\fR, \fB[sig]setjmp()\fR, and \fBvfork()\fR.
250 .sp
251 .LP
252 Functions such as \fBexit\fR(2) that do not return will not be traced for their
253 return values.
254 .sp
255 .LP
256 For security reasons, only those processes with appropriate privileges can use
257 \fBapptrace\fR to trace \fBsetuid\fR/\fBsetgid\fR programs.
258 .sp
259 .LP
260 Tracing functions whose usage requires the inclusion of <\fBvarargs.h\fR>, such
261 as \fBvwprintw\fR(3XCURSES) and \fBvwscanw\fR(3XCURSES), will not provide
262 formatted printing of arguments.
263 .SH ATTRIBUTES
264 .sp
265 .LP
266 See \fBattributes\fR(5) for descriptions of the following attributes:
267 .sp
269 .sp
270 .TS
271 box;
272 c | c
273 l | l .
274 ATTRIBUTE TYPE ATTRIBUTE VALUE
275 _
276 Interface Stability Unstable
277 .TE
279 .SH SEE ALSO
280 .sp
281 .LP
282 \fBld.so.1\fR(1), \fBtruss\fR(1), \fBvwprintw\fR(3XCURSES),
283 \fBvwscanw\fR(3XCURSES), \fBattributes\fR(5), \fBfnmatch\fR(5)
284 .sp
285 .LP
286 \fILinker and Libraries Guide\fR