'\" te
.\" Copyright (c) 2004, Sun Microsystems, Inc.  All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH APPTRACE 1 "Nov 29, 2004"
.SH NAME
apptrace \- trace application function calls to Solaris shared libraries
.SH SYNOPSIS
.LP
.nf
\fBapptrace\fR [\fB-f\fR] [\fB-F\fR [!] \fItracefromlist\fR] [\fB-T\fR [!] \fItracetolist\fR]
     [\fB-o\fR \fIoutputfile\fR] [ [\fB-tv\fR] [!] \fIcall\fR ,...] \fIcommand\fR
     [\fIcommand\fR \fIarguments\fR]
.fi

.SH DESCRIPTION
.sp
.LP
The \fBapptrace\fR utility runs the executable program specified by
\fIcommand\fR and traces all function calls that the program\fIcommand\fR makes
to the Solaris shared libraries. For each function call that is traceable,
\fBapptrace\fR reports the name of the library interface called, the values of
the arguments passed, and the return value.
.sp
.LP
By default, \fBapptrace\fR 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.
.sp
.LP
Calls from or to additional shared objects may be traced using the \fB-F\fR or
\fB-T\fR options (see below).
.sp
.LP
The default reporting format is a single line per call, with no formatted
printing of arguments passed by reference or of data structures.
.sp
.LP
Formatted printing providing additional argument details is obtained using the
\fB-v\fR option (see below).
.sp
.LP
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
\fB-t\fR and/or \fB-v\fR options.
.sp
.LP
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.
.sp
.LP
\fBapptrace\fR 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 \fILinker and Libraries
Guide\fR.
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-f\fR \fR
.ad
.RS 24n
Follows all children created by \fBfork\fR(2). This option will also cause the
process id to be printed at the beginning of each line.
.RE

.sp
.ne 2
.na
\fB\fB-F\fR \fB[!]\fR\fItracefromlist\fR \fR
.ad
.RS 24n
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, \fIlibc\fR will match \fI/usr/lib/libc.so.1\fR. Additionally, shell
style wildcard characters are supported as described in \fBfnmatch\fR(5). A
list preceded by a ``!'' defines a list of objects from which calls should not
be traced. If the tracing of calls from \fIcommand\fR is required, then
\fIcommand\fR must be a member of \fItracefromlist\fR.
.RE

.sp
.ne 2
.na
\fB\fB-o\fR \fIoutputfile\fR \fR
.ad
.RS 24n
\fBapptrace\fR output will be directed to the \fIoutputfile\fR. By default,
\fBapptrace\fR output is placed on the stderr stream of the process being
traced.
.RE

.sp
.ne 2
.na
\fB\fB-t\fR [\fB!\fR]\fIcall,\|.\|.\|.\fR\fR
.ad
.RS 24n
Traces or excludes function calls. Those calls specified in the comma-separated
list \fIcall\fR are traced. If the list begins with a !, the specified function
calls are excluded from the trace output. The default is \fB-t\fR \fB*\fR. The
use of shell style wildcards is allowed.
.RE

.sp
.ne 2
.na
\fB\fB-T\fR \fB[!]\fR\fItracetolist\fR \fR
.ad
.RS 24n
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.
.RE

.sp
.ne 2
.na
\fB\fB-v\fR [\fB!\fR]\fIcall,\|.\|.\|.\fR\fR
.ad
.RS 24n
Provides verbose, formatted output of the arguments and return values of  the
function calls specified (as above in the \fB-t\fR option). Unlike
\fBtruss\fR(1), calls named by the \fB-v\fR option do not have to be named by
the \fB-t\fR option. For example, \fBapptrace\fR \fB-v\fR \fBopen\fR is
equivalent to \fBtruss\fR \fB-t\fR \fBopen\fR \fB-v\fR \fBopen\fR.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRTracing the date command
.sp
.in +2
.nf
% \fBapptrace date\fR
-> 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
.fi
.in -2
.sp

.LP
\fBExample 2 \fRTracing a specific set of interfaces with verbosity set
.sp
.in +2
.nf
% \fBapptrace -v localtime,strftime,puts date\fR
-> 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
.fi
.in -2
.sp

.sp
.LP
** NR - The return value of a function call will not be traced.
.SH FILES
.sp
.LP
Basic runtime support for \fBapptrace\fR is provided by the link auditing
feature of the Solaris runtime linker (\fBld.so.1\fR(1)) and the \fBapptrace\fR
command's use of this facility relies on an auditing object
(\fBapptrace.so.1\fR) kept in \fB/usr/lib/abi\fR.
.SH LIMITATIONS
.sp
.LP
In general, \fBapptrace\fR 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 \fBprintf\fR and \fBscanf\fR
families.
.sp
.LP
The \fBapptrace\fR utility can not trace the return value of a function call
whose return type is a \fBstruct\fR or \fBunion\fR.
.sp
.LP
Functions that attempt to probe the stack or otherwise extract information
about the caller cannot be traced. Some examples are \fB[gs]etcontext()\fR,
\fB[sig]longjmp()\fR, \fB[sig]setjmp()\fR, and \fBvfork()\fR.
.sp
.LP
Functions such as \fBexit\fR(2) that do not return will not be traced for their
return values.
.sp
.LP
For security reasons, only those processes with appropriate privileges can use
\fBapptrace\fR to trace \fBsetuid\fR/\fBsetgid\fR programs.
.sp
.LP
Tracing functions whose usage requires the inclusion of <\fBvarargs.h\fR>, such
as \fBvwprintw\fR(3XCURSES) and \fBvwscanw\fR(3XCURSES), will not provide
formatted printing of arguments.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Unstable
.TE

.SH SEE ALSO
.sp
.LP
\fBld.so.1\fR(1), \fBtruss\fR(1), \fBvwprintw\fR(3XCURSES),
\fBvwscanw\fR(3XCURSES), \fBattributes\fR(5), \fBfnmatch\fR(5)
.sp
.LP
\fILinker and Libraries Guide\fR