\cfg{man-identity}{xtruss}{1}{2009-05-02}{PuTTY spinoffs}{PuTTY spinoffs}

\define{dash} \u2013{-}

\title Man page for \cw{xtruss}

\U NAME

\cw{xtruss} \dash trace X protocol exchanges, in the manner of \cw{strace}

\U SYNOPSIS

\c xtruss [ options ] command [ command-arguments ]
\e bbbbbb   iiiiiii   iiiiiii   iiiiiiiiiiiiiiiii
\c xtruss [ options ] -p X-resource-ID
\e bbbbbb   iiiiiii   bb iiiiiiiiiiiii
\c xtruss [ options ] -p -
\e bbbbbb   iiiiiii   bb b
\c xtruss [ options ] -P
\e bbbbbb   iiiiiii   bb

\U DESCRIPTION

\cw{xtruss} is a utility which logs everything that passes between
the X server and one or more X client programs. In this it is
similar to \cw{xmon}(1), but intended to combine \cw{xmon}'s basic
functionality with an interface much more similar to \cw{strace}(1).

Like \cw{xmon}, \cw{xtruss} in its default mode works by setting up
a proxy X server, waiting for connections to that, and forwarding
them on to the real X server. However, unlike \cw{xmon}, you don't
have to deal with any of that by hand: there's no need to start the
trace utility in one terminal and manually attach processes to it
from another, unless you really want to (in which case the \cw{-P}
option will do that). The principal mode of use is just to type
\cw{xtruss} followed by the command line of your X program;
\cw{xtruss} will automatically take care of adjusting the new
program's environment to point at its proxy server, and (also unlike
\cw{xmon}) it will also take care of X authorisation automatically.

As an alternative mode of use, you can also attach \cw{xtruss} to an
already-running X application, if you didn't realise you were going
to want to trace it until it had already been started. This mode
requires cooperation from the X server \dash specifically, it can't
work unless the server supports the \cw{RECORD} protocol extension
\dash but since modern X.Org servers do provide that, it's often
useful.

The logging format of \cw{xtruss} is much more compact than that of
\cw{xmon}, and resembles \cw{strace} in that it's written to look
like a series of function calls some of which return values. For
instance, where \cw{xmon} would print

\c          ............REQUEST: GetSelectionOwner
\c              sequence number: 000f
\c               request length: 0002
\c                    selection: <PRIMARY>
\c                                  ..............REPLY: GetSelectionOwner
\c                                      sequence number: 000f
\c                                         reply length: 00000000
\c                                                owner: WIN 02c0002b
\c          ............REQUEST: InternAtom
\c              sequence number: 0010
\c               only-if-exists: False
\c               request length: 0005
\c               length of name: 000c
\c                         name: "VT_SELECTION"
\c                                  ..............REPLY: InternAtom
\c                                      sequence number: 0010
\c                                         reply length: 00000000
\c                                                 atom: ATM 000002bf

\cw{xtruss} will instead print

\c GetSelectionOwner(selection=a#1) = {owner=w#02C0002B}
\c InternAtom(name="VT_SELECTION", only-if-exists=False) = {atom=a#703}

Note that not only has each request been condensed on to one line
(though most lines will be long enough to wrap, at least on a
standard 80-column terminal), but also each request and reply have
been printed on the \e{same} line.

That last is not always possible, of course: sometimes an
application will queue multiple requests before receiving the reply
to the first one (in fact, this is generally good behaviour since it
minimises network round-trip delays), in which case \cw{xtruss}'s
output will look \dash again mimicking \cw{strace} \dash something
like this:

\c InternAtom(name="TARGETS", only-if-exists=False) = <unfinished>
\c InternAtom(name="TIMESTAMP", only-if-exists=False) = <unfinished>
\c  ... InternAtom(name="TARGETS", only-if-exists=False) = {atom=a#378}
\c  ... InternAtom(name="TIMESTAMP", only-if-exists=False) = {atom=a#379}

\U OPTIONS

These options change the mode of operation of \cw{xtruss} away from
the default of acting as a wrapper on a single command:

\dt \cw{-p} \e{resource-ID}

\dd Attach to the X client owning the given resource, using the X
\cw{RECORD} extension (which the server must support for this to
work). The resource ID can be a decimal integer or a hex integer
preceded with \cq{0x}. It typically names an X window, but can name
another type of resource instead (e.g. a pixmap or cursor) or just
specify the resource base of the client connection. If you don't
know any of those things, you can give the resource ID as just
\cq{-}, in which case \cw{xtruss} will allow you to interactively
select a window by clicking with the mouse (similarly to
\cw{xkill}(1), \cw{xwininfo}(1) and \cw{xprop}(1)) and will trace
the client that owns the window you select.

\dt \cw{-P}

\dd Set up a logging X proxy as in the normal mode, but instead of
spawning a subprocess to connect to that proxy, just wait for
connections. This turns \cw{xtruss} into a tool more similar to
\cw{xmon}: you start it in one terminal window, and then from
another terminal window you can configure selected processes to
connect to the proxy server and be logged. \cw{xtruss} will print on
standard output the environment variables you need to set up to
connect other processes to the proxy (in both \cw{sh} and \cw{csh}
syntax).

The following options apply to all modes of operation:

\dt \cw{-s} \e{length}

\dd Limit the length of output lines by eliding most of the contents
of long arrays, strings and blocks of data. \cw{xtruss} will begin
to shorten lines at the specified length (any line shorter than that
should not be interfered with), but lines cannot always be chopped
to the exact length and continue to make sense, so the line length
is approximate only. Specifying zero or \cq{unlimited} will remove
all restriction, so that \cw{xtruss} will display the full contents
of every request it understands, no matter how big. Default is 256.

\dt \cw{-o} \e{filename}

\dd Send the trace output to the specified file, or to standard output
if \e{filename} is just \cq{-}. The default is to log to standard
error.

\dt \cw{-e} [\e{class}\cw{=}][\cw{!}]\e{item}[\cw{,}\e{item}...]

\dd Specify a subset of X requests or X events to log. \e{class} can
be either \cq{requests} or \cq{events}; if the class is omitted,
\cq{requests} is assumed. The list of \e{item} gives a list of X
request names or X event names (respectively) to be logged; all
other requests or events are omitted. If the list of items is
prefixed with \cw{!}, it is instead treated as a list of requests or
events \e{not} to be logged, and anything not in the list is
printed. Reply and error packets are not separately filtered: they
are logged if and only if the request they respond to was logged.

\lcont{

For example, to log only \cw{ImageText8} and \cw{ImageText16}
requests, you might say \q{\cw{xtruss -e
requests=ImageText8,ImageText16} \e{command}} or just \q{\cw{xtruss
-e ImageText8,ImageText16} \e{command}}. To inhibit the display of
\cw{FocusIn} and \cw{FocusOut} events, you might say \q{\cw{xtruss
-e events=!FocusIn,FocusOut} \e{command}}.

(Note that the \cw{!} character might be treated specially by your
shell, so you may need to escape it.)

}

\dt \cw{-I}

\dd Log the initialisation message sent by the X server at the start
of the connection. This is omitted by default because it's
particularly long and ugly.

\dt \cw{-R}

\dd As well as translating the X protocol, also give a raw hex dump
of all the data transferred over the connection. (Probably most
useful to include in a bug report about \cw{xtruss} itself!)

\dt \cw{-C}

\dd Prefix every output line with the X client id (resource base) of
the client connection it came from. By default \cw{xtruss} only
starts to do this if it's tracing more than one X client; before
then, lines are unprefixed. This option makes prefixing
unconditional from the start of the run.

\U BUGS

Many commonly used X protocol extensions are not currently decoded.

A lot of this program has been only minimally tested.

\U LICENCE

\cw{xtruss} is free software, distributed under the MIT/X11 licence.
Type \cw{xtruss --licence} to see the full licence text.
