--- name: "xtrace" section: "1" platform: "linux" package: "xtrace" version: "1.4.0-1+b1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/xtrace" --- # xtrace(1) trace communication between X11 client and server ## NAME xtrace - trace communication between X11 client and server ## SYNOPSIS **xtrace** \[ ***options*** \] \[ **-s** \| **-k** \] \[ \[ **-W** \] \[ **--** \] ***command args ...*** \] ## DESCRIPTION Xtrace fakes an X server and forwards all connections to a real X server, displaying the communication between clients in (well, theoretically) human readable form. If a command is given, **xtrace** executes the named command with **$DISPLAY** set to the faked X server. If that command exits before any connections are made, **xtrace** exits immediately unless **-W** is specified. ## OPTIONS - **-I *directory*** Look into *directory* for protocol description files. (i.e. the directory where the **.proto** files can be found). - **-s \| --stopwhendone (default)** Terminate when all forwarded clients have disconnected. (Or when a program was run once the program has finished and all connections are closed). - **-k \| --keeprunning** If all clients disconnected, wait for new ones to connect. - **-W \| --waitforclient** Do not stop when the started program terminates before any connection was made. (Might be necessary if the program forks to background). - **-d *name* \| --display *name*** Forward connections to the X server specified by *name* instead of the one specified by the environment variable **DISPLAY**. - **-D *name* \| --fakedisplay *name*** Fake display *name* instead of **$FAKEDISPLAY** or **:9** respectively. - **-f *filename* \| --authfile *filename*** Add an **-f** *filename* to the arguments for all calls to xauth to get the authentication tokens of the X server to connect to. - **-F *filename* \| --newauthfile *filename*** Add an **-f** *filename* to the arguments for all calls to xauth to save the authentication tokens to connect to the faked X server. - **-c \| --copyauthentication (default)** Copy the authentication tokens for the X server to connect to so that clients connecting to our fake server will use them. The commands run are roughly equivalent to: **xauth add $FAKEDISPLAY . \`xauth list $DISPLAY \| awk '$2=="MIT-MAGIC-COOKIE-1" {print $3}'\`** Not that only **MIT-MAGIC-COOKIE-1** tokens are copied as xtrace does not yet support to change the authentication tokens so that **XDM-AUTHORIZATION-1** would be possible. - **-n \| --nocopyauthentication** Do not call **xauth** and do fiddle with authentication tokens but leave that to the user to handle. - **-e \| --denyextensions** Modify all server replies to say there are no extensions available. (As xtrace does supports only a small number of extensions anyway and calls all extended requests "unknown" and all replies to such requests "unexpected"). - **-w \| --readwritedebug** Print how many bytes are read and/or written when. - **-m *count* \| --maxklistlength *count*** Print only the first *count* many elements of all lists. - **-i \| --interactive** Only sent requests from the client to the server after interactive confirmation. Confirmation is given by pressing enter or a number followed by enter via stdin. This can give funny results when multiple clients are tunneled. - **-o \| --outfile *filename*** Dump output into *filename* instead of stdout. - **-b \| --buffered** Do not write every line on its own but wait until buffers are full. Speeds up things a little bit when outputting to a file. Not very useful at all together with **-i**. - **--timestamps** Print a timestamp before each line. Note that the time a packet is printed is between the time a packet is received and the time a packet is sent, but it gives no other information than that. - **--relative-timestamps** Print a timestamp relative to the beginning of the connection before each line. Note that the time a packet is printed is between the time a packet is received and the time a packet is sent, but it gives no other information than that. - **--monotonic-timestamps** Print a CLOCK\_MONOTONIC (see [**clock\_gettime**(3)](/clock_gettime/3.md)) timestamp each time a package is printed. This is likely to be the uptime of your system. Note that the time a packet is printed is between the time a packet is received and the time a packet is sent, but it gives no other information than that. - **--print-offsets** Print offsets of all fields (useful to debug nested lists in protocol descriptions) - **--print-counts** Print counts (useful to debug lists in protocol descriptions) ## ENVIRONMENT VARIABLES - **DISPLAY** Without **--display** the content of this variable is used to determine the server to connect to. (And without **-n** given to **xauth** to get the authentication tokens for this display.) - **FAKEDISPLAY** Without **--fakedisplay** the content of this variable is used to determine how to listen for clients. (And without **-n** given to **xauth** to set the authentication tokens for this display.) If neither is given, **xtrace** will try **:9** - **XAUTHORITY** Without **-n** and without **-f** or **-F** your **xauth** program will most likely look into this variable for the file to get/save the authentication tokens from/into. If this is not set it will most likely use *$HOME***/.Xauthority**. ## REPORTING BUGS Report bugs to the Debian BTS. ## SEE ALSO [**xauth**(1)](/xauth/1.md), **x**(7x), ## COPYRIGHT Copyright © 2005 Bernhard R. Link\ This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.