Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

OpenSolaris 2009.06 - man page for apptrace (opensolaris section 1)

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 func-
       tion calls that the programcommand makes to the Solaris shared libraries. For  each  func-
       tion  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 pro-
       cedure  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 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 limita-
       tion, 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 call-
       er 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 argu-
       ments.

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.11				   29 Nov 2004				      apptrace(1)


All times are GMT -4. The time now is 07:32 PM.

Unix & Linux Forums Content CopyrightŠ1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password