| xtruss(1) | PuTTY spinoffs | xtruss(1) |
xtruss - trace X protocol exchanges, in the manner of strace
xtruss [ options ] command [ command-arguments ] xtruss [ options ] -p X-resource-ID xtruss [ options ] -p - xtruss [ options ] -P
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}
These options change the mode of operation of xtruss away from the default of acting as a wrapper on a single command:
The following options apply to all modes of operation:
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.)
Many commonly used X protocol extensions are not currently decoded.
A lot of this program has been only minimally tested.
xtruss is free software, distributed under the MIT/X11 licence. Type xtruss --licence to see the full licence text.
| 2009‐05‐02 | PuTTY spinoffs |