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