XTRACE(1)

💖 XTRACE 💖

okay bestie, settle in, because xtrace is that girl. it's a lil program (a manual page in section 1, so it's a user command, iykyk) that traces communication between an X11 client and server. yes, like, wiretap but make it cute and for X11. ✨

---

🌸 SYNOPSIS 🌸

xtrace [ options ] [ -s | -k ] [ [ -W ] [ -- ] command args ...

like, options first, then you pick -s or -k, then optionally -W, then optionally --, then whatever command you want it to run. simple as. 💅

---

🦋 DESCRIPTION 🦋

So here's the whole vibe: xtrace fakes an X server and then forwards all connections to a real X server, showing you the communication between the clients in (and this is the original's own words, not mine) well, theoretically human readable form. it's giving translator but for X11 gossip. 🙈

if you hand it a command, xtrace runs that named command with $DISPLAY set to the faked X server. slay. but heads up: if that command exits before any connections are made, xtrace exits immediately — unless you passed -W. that's the whole rule, no cap. ✨

---

✨ OPTIONS ✨

• -I directory — look into directory for protocol description files. like, the directory where the .proto files can be found. 🎀
• -s, --stopwhendone (this one's the default) — terminate when all forwarded clients have disconnected. (or, if a program was run, once the program has finished and all connections are closed.) 💤
• -k, --keeprunning — if all clients disconnected, don't dip, just 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, fr fr. 🧚
• -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, bestie, this is the 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}'`

and not that only MIT-MAGIC-COOKIE-1 tokens are copied, because xtrace does not yet support changing the authentication tokens so that XDM-AUTHORIZATION-1 would be possible. so that's a limit, not a vibe. 😭

• -n, --nocopyauthentication — do not call xauth and do fiddle with authentication tokens, but leave that to the user to handle. you're on your own, main character. 👑
• -e, --denyextensions — modify all server replies to say there are no extensions available. (as xtrace 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, and when. 🔍
• -m count, --maxklistlength count — print only the first count many elements of all lists.
• -i, --interactive — only send 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)) 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, it's 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, it's 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. (that's it, that's the whole section, go off.) 📮

---

🫶 SEE ALSO 🫶

xauth(1), 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. 🚨

---

bestie reminder: no warranty, not even for merchantability or fitness for a particular purpose. that's not me being dramatic, that's literally the license. periodt. 💅

and that's the whole page, gorgeous — this one's from the xtrace manual, dated 26 June 2009, section XTRACE(1). now go trace something. 🦋✨🎀