apptrace(1) (man pages section 1: User Commands)

man pages section 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

syscall

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 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 traced may be restricted, using a regular expression that matches the interface names to be traced, and is given to either the -t or -v option.

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 [!]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 are to be excluded from the trace. If the tracing of calls from command is required, then command must be a member of tracefromlist.
-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 are to be excluded from the trace.
-o outputfile: apptrace output will be directed to the outputfile. By default, apptrace output is placed on stderr.
-f: Follows all children created by fork(2) and also print truss(1) output on each. This option will also cause a 'pid' to be output on each truss(1) output line.
-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 all. The use of shell style wildcards is allowed.
-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 verbosity 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 provided 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 interceptor function in the library's supporting verbose-tracing shared object. In the case that 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 for the call-tracing report (simply hex-formatted printing of the first three arguments).

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 family.

Functions that attempt to probe the stack or otherwise extract information about the caller cannot be traced. Some examples are [gs]etcontext(), getsp(), [sig]longjmp(), [sig]setjmp(), and vfork().

Functions such as exit(2) that do not return may also produce strange output.

ATTRIBUTES

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWcstl (32-bit)
	SUNWcstlx (64-bit)