unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

apptrace(1)                      User Commands                     apptrace(1)



NAME
       apptrace - trace application function calls to Solaris shared libraries

SYNOPSIS
       apptrace [-f] [ -F [!] tracefromlist] [ -T [!] tracetolist] [-o output-
       file] [ [-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 format-
       ted 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 output-
                               file.  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 argu-
                               ments 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 (app-
       trace.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 informa-
       tion  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  <&lt;varargs.h>&gt;,
       such as vwprintw(3XCURSES) and vwscanw(3XCURSES), will not provide for-
       matted  printing of arguments.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:


       tab()    allbox;    cw(2.750000i)|     cw(2.750000i)     lw(2.750000i)|
       lw(2.750000i).    ATTRIBUTE  TYPEATTRIBUTE  VALUE  AvailabilitySUNWcstl
       (32-bit) SUNWcstlx (64-bit) Interface StabilityUnstable


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)