Unix‎ > ‎Solaris‎ > ‎Solaris man pages‎ > ‎1‎ > ‎

apptrace


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 program-
     command 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  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 pre-
                             ceded  by  a ``!'' defines a list of
                             objects from which calls should  not
                             be  traced.  If the tracing of calls
                             from command is required, then  com-
                             mand  must be a member of tracefrom-
                             list.



     -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 speci-
                             fied  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 verbos-
     ity 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 accept-
     ing variable argument lists. There has been some clever cod-
     ing  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(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       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










Man pages from Solaris 10 Update 8. See docs.sun.com and www.oracle.com for further documentation and Solaris information.
Comments