apptrace(1)
NAME
apptrace - trace application function calls to Solaris
shared libraries
SYNOPSIS
apptrace [-f] [ -F [!] tracefromlist] [ -T [!] tracetolist]
[-o outputfile] [ [-tv] [!] call ,...] command [ command
arguments]
DESCRIPTION
The apptrace utility runs the executable program specified
by command and traces all calls that the program command
makes to the Solaris shared libraries. Tracing means that
for each call the program makes, apptrace reports the name
of the library interface called, the values of the arguments
passed, and the return value.
By default, apptrace traces calls directly from the execut-
able object to any of the shared objects it depends on.
Indirect calls (that is, calls made between shared objects
that the executable depends upon) are not reported by
default.
Calls from or to additional shared objects may be traced
using the -F or -T options (see below).
The default reporting format is a single line per call, with
no formatted printing of arguments passed by reference or of
data structures.
Formatted printing providing additional argument details is
obtained using the -v option (see below).
By default, every interface provided by a shared object is
traced if called. However, the set of interfaces to be
traced can be restricted, using the -t and/or -v options.
Since it is generally possible to trace calls between any of
the dynamic objects linked at runtime (the executable object
and any of the shared objects depended upon), the report of
each traced call gives the name of the object from which the
call was made.
apptrace traces all of the procedure calls that occur
between dynamic objects via the procedure linkage table, so
only those procedure calls which are bound via the table
will be traced. See the Linker and Libraries Guide.
OPTIONS
The following options are supported:
-f Follows all children created by fork(2). This option
will also cause the process id to be printed at the
beginning of each line.
-F [!]tracefromlist
Traces calls from a comma-separated list of shared
objects. Only calls from these shared objects will be
traced. The default is to trace calls from the main
executable only. Only the basename of the shared
object is required. For example, libc will match
/usr/lib/libc.so.1. Additionally, shell style wildcard
characters are supported as described in fnmatch(5). A
list preceded by a ``!'' defines a list of objects
from which calls should not be traced. If the tracing
of calls from command is required, then command must
be a member of tracefromlist.
-o outputfile
apptrace output will be directed to the outputfile. By
default, apptrace output is placed on the stderr
stream of the process being traced.
-t [!]call,...
Traces or excludes function calls. Those calls speci-
fied in the comma-separated list call are traced. If
the list begins with a !, the specified function calls
are excluded from the trace output. The default is -t
*. The use of shell style wildcards is allowed.
-T [!]tracetolist
Traces calls to a comma-separated list of shared
objects. The default is to trace calls to all shared
objects. As above, the basename is all that is
required and wildcarding is allowed. A list preceded
by a ``!'' denotes a list of objects to which calls
should not be traced.
-v [!]call,...
Provides verbose, formatted output of the arguments
and return values of the function calls specified (as
above in the -t option). Unlike truss(1), calls named
by the -v option do not have to be named by the -t
option. For example, apptrace -v open is equivalent to
truss -t open -v open.
EXAMPLES
Example 1: Tracing the date command
% apptrace date
date -> libc.so.1:atexit(func = 0xff3ba1c8) = 0x0
date -> libc.so.1:atexit(func = 0x117e4) = 0x0
date -> libc.so.1:setlocale(category = 0x6, locale = "") = "C"
date -> libc.so.1:textdomain(domainname =
"SUNW_OST_OSCMD") = "SUNW_OST_OSCMD"
date -> libc.so.1:getopt(argc = 0x1, argv = 0xffbeed5c,
optstring = "a:u") = 0xffffffff errno = No error
date -> libc.so.1:time(tloc = 0x21ecc) = 0x371397c3
date -> libc.so.1:nl_langinfo(item = 0x3a) = "%a %b %e %T %Z %Y"
date -> libc.so.1:localtime(clock = 0x21ecc) = 0xff03c928
date -> libc_psr.so.1:memcpy(0xffbeeccc, 0xff03c928, 0x24)
date -> libc.so.1:strftime(s = "Tue Apr 13 15:15:15 ",
maxsize = 0x400, format = "%a %b %e %T %Z %Y",
timeptr = 0xffbeeccc) = 0x1c
date -> libc.so.1:puts(Tue Apr 13 15:15:15 EDT 1999
s = "Tue Apr 13 15:15:15 ") = 0x1d
date -> libc.so.1:exit(status = 0)
Example 2: Tracing a specific set of interfaces with verbos-
ity set
% apptrace -v '*gid*' id -a
id -> libc.so.1:getgid() = 0xa
return = (gid_t) 10 (0xa)
id -> libc.so.1:getegid() = 0xa
return = (gid_t) 10 (0xa)
id -> libc.so.1:getgrgid(gid = 0xa) = 0x2238c
gid = (gid_t) 10 (0xa)
return = (struct group *) 0x2238c (struct group) {
gr_name: (char *) 0x223a0 "staff"
gr_passwd: (char *) 0x223a6 ""
gr_gid: (gid_t) 10 (0xa)
gr_mem: (char **) 0x2239c
}
id -> libc.so.1:getgrgid(gid = 0xa) = 0x2238c
gid = (gid_t) 10 (0xa)
return = (struct group *) 0x2238c (struct group) {
gr_name: (char *) 0x223a0 "staff"
gr_passwd: (char *) 0x223a6 ""
gr_gid: (gid_t) 10 (0xa)
gr_mem: (char **) 0x2239c
}
id -> libc.so.1:getgrgid(gid = 0x3) = 0x2238c
gid = (gid_t) 3 (0x3)
return = (struct group *) 0x2238c (struct group) {
gr_name: (char *) 0x223b4 "sys"
gr_passwd: (char *) 0x223b8 ""
gr_gid: (gid_t) 3 (0x3)
gr_mem: (char **) 0x2239c
}
id -> libc.so.1:getgrgid(gid = 0x29) = 0x2238c
gid = (gid_t) 41 (0x29)
return = (struct group *) 0x2238c (struct group) {
gr_name: (char *) 0x223a4 "opcom"
gr_passwd: (char *) 0x223aa ""
gr_gid: (gid_t) 41 (0x29)
gr_mem: (char **) 0x2239c
}
id -> libc.so.1:getgrgid(gid = 0xe) = 0x2238c
gid = (gid_t) 14 (0xe)
return = (struct group *) 0x2238c (struct group) {
gr_name: (char *) 0x223a0 "sysadmin"
gr_passwd: (char *) 0x223a9 ""
gr_gid: (gid_t) 14 (0xe)
gr_mem: (char **) 0x2239c
}
id -> libc.so.1:getgrgid(gid = 0xd3) = 0x2238c
gid = (gid_t) 211 (0xd3)
return = (struct group *) 0x2238c (struct group) {
gr_name: (char *) 0x223a8 "test"
gr_passwd: (char *) 0x223ad ""
gr_gid: (gid_t) 211 (0xd3)
gr_mem: (char **) 0x2239c
}
uid=44013(georgn) gid=10(staff) groups=10(staff),3(sys),
41(opcom),14(sysadmin),211(test)
FILES
Basic runtime support for apptrace is provided by the link
auditing feature of the Solaris runtime linker (ld.so.1(1))
and the apptrace command's use of this facility relies on an
auditing object (apptrace.so.1) kept in /usr/lib/abi.
In order to perform formatted printing of arguments when
tracing calls (as selected by the -v option), apptrace
needs to know the number and data types of the arguments
supplied to the called interface. Special runtime support
shared objects are provided which apptrace relies upon to
perform formatted printing. A runtime support object is pro-
vided for each Solaris shared library, which contains an
"interceptor" function for each interface within the shared
library. These supporting shared objects are kept in
/usr/lib/abi. apptrace has a simple algorithm to map from
the name of a library interface to the name of an intercep-
tor function in the library's supporting verbose-tracing
shared object. If an interceptor is not found in the
library's supporting tracing shared object, apptrace cannot
determine either the number or data types of the arguments
for that interface. In this case, apptrace uses a default
output format for the call-tracing report (hex-formatted
printing of the first three arguments).
LIMITATIONS
In general, apptrace cannot trace calls to functions accept-
ing variable argument lists. There has been some clever cod-
ing in several specific cases to work around this limita-
tion, most notably in the printf and scanf families.
Functions that attempt to probe the stack or otherwise
extract information about the caller cannot be traced. Some
examples are [gs]etcontext(), [sig]longjmp(), [sig]setjmp(),
and vfork().
Functions such as exit(2) that do not return may also pro-
duce strange output. Also, functions that call other traced
functions before returning will produce slightly garbled
output.
For security reasons, only root can apptrace setuid/setgid
programs.
Tracing functions whose usage requires the inclusion of
varargs.h, such as vwprintw(3XCURSES) and vwscanw(3XCURSES),
will not provide formatted printing of arguments.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | SUNWcstl (32-bit) |
|_____________________________|_____________________________|
| | SUNWcstlx (64-bit) |
|_____________________________|_____________________________|
SEE ALSO
ld.so.1(1), truss(1), vwprintw(3XCURSES), vwscanw(3XCURSES),
attributes(5), fnmatch(5)
Linker and Libraries Guide
Man(1) output converted with
man2html