Provided by: xtruss_0.0~git20241011.27fafffe-1_amd64 
NAME
xtruss - trace X protocol exchanges, in the manner of strace
SYNOPSIS
xtruss [ options ] command [ command-arguments ]
xtruss [ options ] -p X-resource-ID
xtruss [ options ] -p -
xtruss [ options ] -P
DESCRIPTION
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 xmon(1), but intended to combine xmon's basic functionality with an
interface much more similar to strace(1).
Like xmon, 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 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 -P option will do that). The principal
mode of use is just to type xtruss followed by the command line of your X program; xtruss will
automatically take care of adjusting the new program's environment to point at its proxy server, and
(also unlike xmon) it will also take care of X authorisation automatically.
As an alternative mode of use, you can also attach 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 - specifically, it can't work unless the server supports the RECORD
protocol extension - but since modern X.Org servers do provide that, it's often useful.
The logging format of xtruss is much more compact than that of xmon, and resembles strace in that it's
written to look like a series of function calls some of which return values. For instance, where xmon
would print
............REQUEST: GetSelectionOwner
sequence number: 000f
request length: 0002
selection: <PRIMARY>
..............REPLY: GetSelectionOwner
sequence number: 000f
reply length: 00000000
owner: WIN 02c0002b
............REQUEST: InternAtom
sequence number: 0010
only-if-exists: False
request length: 0005
length of name: 000c
name: "VT_SELECTION"
..............REPLY: InternAtom
sequence number: 0010
reply length: 00000000
atom: ATM 000002bf
xtruss will instead print
GetSelectionOwner(selection=a#1) = {owner=w#02C0002B}
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 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 xtruss's output will look - again mimicking strace - something
like this:
InternAtom(name="TARGETS", only-if-exists=False) = <unfinished>
InternAtom(name="TIMESTAMP", only-if-exists=False) = <unfinished>
... InternAtom(name="TARGETS", only-if-exists=False) = {atom=a#378}
... InternAtom(name="TIMESTAMP", only-if-exists=False) = {atom=a#379}
OPTIONS
These options change the mode of operation of xtruss away from the default of acting as a wrapper on a
single command:
-p resource-ID
Attach to the X client owning the given resource, using the X 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 `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 `-', in which case xtruss will allow you
to interactively select a window by clicking with the mouse (similarly to xkill(1), xwininfo(1)
and xprop(1)) and will trace the client that owns the window you select.
-P 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 xtruss into a tool more similar to 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. xtruss will print on standard output the
environment variables you need to set up to connect other processes to the proxy (in both sh and
csh syntax).
The following options apply to all modes of operation:
-s length
Limit the length of output lines by eliding most of the contents of long arrays, strings and
blocks of data. 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 `unlimited'
will remove all restriction, so that xtruss will display the full contents of every request it
understands, no matter how big. Default is 256.
-o filename
Send the trace output to the specified file, or to standard output if filename is just `-'. The
default is to log to standard error.
-e [class=][!]item[,item...]
Specify a subset of X requests or X events to log. class can be either `requests' or `events'; if
the class is omitted, `requests' is assumed. The list of 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 !, it is instead treated as a list of requests or events 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.
For example, to log only ImageText8 and ImageText16 requests, you might say `xtruss -e
requests=ImageText8,ImageText16 command' or just `xtruss -e ImageText8,ImageText16 command'. To
inhibit the display of FocusIn and FocusOut events, you might say `xtruss -e
events=!FocusIn,FocusOut command'.
(Note that the ! character might be treated specially by your shell, so you may need to escape
it.)
-I 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.
-R 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 xtruss itself!)
-C Prefix every output line with the X client id (resource base) of the client connection it came
from. By default 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.
BUGS
Many commonly used X protocol extensions are not currently decoded.
A lot of this program has been only minimally tested.
LICENCE
xtruss is free software, distributed under the MIT/X11 licence. Type xtruss --licence to see the full
licence text.
PuTTY spinoffs 2009‐05‐02 xtruss(1)