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(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 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  exam-
			       ple, 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  spe-
       cific 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]etcon-
       text(), [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(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWcstl (32-bit) 	   |
       +-----------------------------+-----------------------------+
       |			     |SUNWcstlx (64-bit)	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Unstable			   |
       +-----------------------------+-----------------------------+

SEE ALSO

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

       Linker and Libraries Guide

SunOS 5.10							    29 Nov 2004 						       apptrace(1)