APPTRACE(1) User Commands 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 function calls that the programcommand makes to the Solaris
shared libraries. For each function call that is traceable, 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 executable 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(7). 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
specified 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(0xff3bf9ac, 0x22000, 0x0) ** NR
-> date -> libc.so.1:atexit(0x11550, 0xfefeef80, 0xab268) ** NR
-> date -> libc.so.1:setlocale(0x6, 0x11560, 0x0) ** NR
-> date -> libc.so.1:textdomain(0x11564, 0xfefce156, 0xff160200) ** NR
-> date -> libc.so.1:int getopt(int = 0x1,
const char * * = 0xffbffa5c,
const char * = 0x11574 "a:u")
<- date -> libc.so.1:getopt() = 0xffffffff
-> date -> libc.so.1:time_t time(time_t * = 0x225c0)
<- date -> libc.so.1:time() = 0x41ab6e82
-> date -> libc.so.1:char * nl_langinfo(nl_item = 0x3a)
<- date -> libc.so.1:nl_langinfo() = 0xfefd3e10
-> date -> libc.so.1:struct tm * localtime(const time_t * = 0x225c0)
<- date -> libc.so.1:localtime() = 0xff160240
-> date -> libc_psr.so.1:memcpy(0xffbff9cc, 0xff160240, 0x24) ** NR
-> date -> libc.so.1:size_t strftime(char * = 0x225c4 "",
size_t = 0x400,
const char * = 0xfefd3e10 "%a %b %e %T %Z %Y",
const struct tm * = 0xffbff9cc)
<- date -> libc.so.1:strftime() = 0x1c
-> date -> libc.so.1:int puts(const char * = 0x225c4
"Mon Nov 29 10:46:26 PST 2004")
Mon Nov 29 10:46:26 PST 2004
<- date -> libc.so.1:puts() = 0x1d
-> date -> libc.so.1:exit(0x0, 0x22400, 0x0) ** NR


Example 2: Tracing a specific set of interfaces with verbosity set



% apptrace -v localtime,strftime,puts date
-> date -> libc.so.1:struct tm * localtime(const time_t * = 0x225c0)
arg0 = (const time_t *) 0x225c0
return = (struct tm *) 0xff160280 (struct tm) {
tm_sec: (int) 0x4
tm_min: (int) 0x34
tm_hour: (int) 0xa
tm_mday: (int) 0x1d
tm_mon: (int) 0xa
tm_year: (int) 0x68
tm_wday: (int) 0x1
tm_yday: (int) 0x14d
tm_isdst: (int) 0
}
<- date -> libc.so.1:localtime() = 0xff160280
-> date -> libc.so.1:size_t strftime(char * = 0x225c4 "",
size_t = 0x400,
const char * = 0xfefd3e10 "%a %b %e %T %Z %Y",
const struct tm * = 0xffbff99c)
arg0 = (char *) 0x225c4 ""
arg1 = (size_t) 0x400
arg2 = (const char *) 0xfefd3e10 "%a %b %e %T %Z %Y"
arg3 = (const struct tm *) 0xffbff99c (struct tm) {
tm_sec: (int) 0x4
tm_min: (int) 0x34
tm_hour: (int) 0xa
tm_mday: (int) 0x1d
tm_mon: (int) 0xa
tm_year: (int) 0x68
tm_wday: (int) 0x1
tm_yday: (int) 0x14d
tm_isdst: (int) 0
}
return = (size_t) 0x1c
<- date -> libc.so.1:strftime() = 0x1c
-> date -> libc.so.1:int puts(const char * = 0x225c4
"Mon Nov 29 10:52:04 PST 2004")
arg0 = (const char *) 0x225c4 "Mon Nov 29 10:52:04 PST 2004"
Mon Nov 29 10:52:04 PST 2004
return = (int) 0x1d
<- date -> libc.so.1:puts() = 0x1d


** NR - The return value of a function call will not be traced.

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.

LIMITATIONS


In general, apptrace cannot trace calls to functions accepting variable
argument lists. There has been some clever coding in several specific
cases to work around this limitation, most notably in the printf and
scanf families.


The apptrace utility can not trace the return value of a function call
whose return type is a struct or union.


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 will not be traced for their
return values.


For security reasons, only those processes with appropriate privileges
can use apptrace to trace 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(7) for descriptions of the following attributes:


+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Unstable |
+--------------------+-----------------+

SEE ALSO


ld.so.1(1), truss(1), vwprintw(3XCURSES), vwscanw(3XCURSES),
attributes(7), fnmatch(7)


Linker and Libraries Guide


November 29, 2004 APPTRACE(1)