xmon(1)xmon(1)NAME
xmon - interactive X protocol monitor
SYNOPSIS
xmonui [ options ] | xmond [ options ]
DESCRIPTION
Xmon interactively monitors the byte-stream connections between an X
server and a number of X clients. Xmon recognizes all requests, events,
errors and replies sent between the clients and the server which are
part of the core X protocol. The contents of these messages are dis‐
played on standard output at a user settable degree of detail from none
to every bit and byte. Xmon also allows the user to select a number of
requests or events to be monitored at a different degree of detail.
Xmon will also block the transmission of selected requests from the
clients to the server and selected events from the server to the
clients. Xmon also keeps statistics of the number of requests, events,
and errors received.
Xmon is made up of two separate processes. The core of xmon is xmond
which monitors the X protocol streams and displays the protocol mes‐
sages on standard output. The interactive interface is handled by
xmonui. These two processes communicate via a pipe from the standard
output of xmonui to the standard input of xmond.
The following diagram shows the relationships between xmonui and xmond,
and the clients and the server.
----------
| xmonui |
----------
|
v
----------------------
| client 1 |<------->| |
------------ | | ----------
: | xmond |<----->| server |
: | | ----------
------------ | |
| client n |<------->| |
----------------------
|
v
monitor output to stdout
In the diagram the vertical connections are pipes and the horizontal
connections are normal X socket connections.
Xmond sits transparently between the X clients and an X server. To the
clients it behaves just like an X server and to the server it behaves
just like a number of X clients.
OPTIONS TO XMOND-server display_name:display_number
This option sets the X display which xmond connects to. dis‐
play_name can be a name or numerical network address. The
default for both values is the value of the DISPLAY environment
variable. If this is not set, then the default for display_name
is the local host and the default for display_number is 0. If
display_number is positive, the real port number is determined
by adding it to the base X server port number, 6000, just as is
done for standard X servers. If it is negative, the real port
number is the absolute value of display_number. A negative
value may be useful when using xmond as a general purpose tcp/ip
monitor and the byte stream being monitored does not obey the X
protocol.
-port display_number
This option sets the port on which xmond listens for client con‐
nections. This port is always on the host where xmond is run‐
ning. Default is 1. The real port number is determined in the
same way as for the -server option.
-verbose verbose_level
This option sets the amount of output initially produced by
xmond for each request, reply, event or error received. The
values are 0 (off), 1 (names), 2 (main), 3 (full), 4 (hex).
Default is 0. The meaning of each value is described in the
USER INTERFACE section.
-raw If this option is given, xmond simply acts as a tcp/ip monitor,
passing bytes from one side to the other without parsing the
stream. By default, it prints the hexadecimal value of each
byte passed. This behaviour may be altered by using the -ascii
or -noprintraw options.
-ascii If this option is given, dumps are printed as ascii characters,
except for unprintable characters, which are printed as hexadec‐
imal, escaped with a '\'. This is useful with the -raw option.
-noprintraw
If this option is given with the -raw option, xmond does not
print anything.
-packet_size
If this option is given, xmond initially prints the size of each
block of data received from the clients and server.
-raw_size
Print size of traffic only. Equivalent to "-packet_size -raw
-noprintraw".
OPTIONS TO XMONUI
Xmonui accepts all of the standard X Toolkit command line options. In
particular
-display display_name:display_number
Indicates where to display the user interface window.
EXAMPLES
1) To monitor connections made to the local host use the following com‐
mand line
xmonui | xmond
Connections made to the display localhost:1 will appear on the display
localhost:0. The xmonui user interface will appear on the display
localhost:0.
When starting up the application that you want to monitor, be sure to
set it's display correctly. When you normally start up an X applica‐
tion, and if you have not done anything special, it will by default
start up on display 0 of your local host. But xmon by default is lis‐
tening as if it is display 1 of your local host. Assuming your X appli‐
cation is called "myclient" and your local host name is "dolphin" then
type the following to start up your application:
myclient -display dolphin:1
Another way to do the same thing is to change the DISPLAY environment
variable. If you are using a C shell you can do this:
setenv DISPLAY dolphin:1
myclient
If you are not using a C shell, you may have to do something different
to change the DISPLAY environment variable. Also, most clients under‐
stand the -display option, but there are those that do not. To deter‐
mine the name of your local host try the hostname command (although it
may not be available on all machines).
2) If you are on the host squiggle which has two X servers using the
displays squiggle:0 and squiggle:1, and want to monitor connections
made to the server running on the display juggler:0, enter the follow‐
ing command line.
xmonui -display squiggle:0 | xmond-server juggler:0 -port 2
Connections now made to the "display" squiggle:2 will appear on the
display juggler:0. The xmonui user interface will appear on the dis‐
play squiggle:0. Monitor output will appear in the window where the
command was entered.
3) A good way to view the output of xmon is to pipe it through xless,
which allows you to scroll and search through the output interactively.
For example:
xmonui | xmond | xless -f
THE USER INTERFACE
The user interface is divided into four parts: output detail, statis‐
tics, selected requests and selected events.
In the output detail section, the amount of detail contained in the
output of xmon can be selected. Different levels of detail can be
selected for each of the message types: requests, events, errors and
replies. The meaning of each level is as follows.
off No monitor output is produced.
names Only the names of the messages are output.
main The most interesting fields of the message are output.
full All fields of the message are output.
hex All fields of the message are output, as well as a hexadecimal
dump.
The detail setting for errors also applies to the following: setup mes‐
sages sent at client connection; the end-of-file "message" sent at
client shutdown; unknown extended messages; and unexpected replies. If
xmon receives a request, reply, event or error which it does not know
how to handle, and if the detail setting for errors is "hex", then the
message will be dumped in hexadecimal. Similarly, if xmon receives a
reply for which it did not send a corresponding request, and the detail
setting for errors is "hex", then the reply will be dumped in hexadeci‐
mal.
Note that synthetic events (events sent by XSendEvent) are monitored in
the same way as normal events but are identified as being "SYNTHETIC".
Also in this section is the show packet size toggle. If this is turned
on, xmon will display the size of each packet received from both
clients and servers. The file descriptor of the client or server which
sent the packet is also displayed. The first client file descriptor is
4. File descriptors 0, 1 and 2 are used by standard input, standard
output and standard error and file descriptor 3 is where xmon listens
for new connections.
In the statistics section, the counting of requests, events and errors
can be controlled as follows.
start Enable the taking of statistics.
stop Disable the taking of statistics.
clear Clear the counts for this message group.
print Print the name and number of occurrences of each message in this
group, excluding messages received zero times.
print zero
Print the names of messages in this group that have been
received zero times.
In the selected requests section, selected requests can be monitored at
a different level of detail, or can be blocked from transmission.
Requests can be selected by clicking on their names in the scrollable
list. Clicking again de-selects the request. Selected requests are
indicated by an asterisk (*) in the scrollable list.
The detail toggle is of the same form as in the output detail section,
but applies only to those requests selected in the left scrollable
list.
If the blocking toggle in set to on, all selected requests in the right
hand scrollable list are blocked by xmon. They are not forwarded to
the server, although they are monitored and counted normally. If the
blocking toggle in set to off, all requests are forwarded to the
server.
The selected events section is similar to the above section but deals
with events received from the server.
USING XMOND WITHOUT XMONUI
Normally xmonui is used as an interactive interface to xmond. However,
for some testing procedures it may be better to run xmond by itself
initialising it with some standard setup. The interface between xmonui
and xmond is made up of simple ascii strings. Pressing buttons on
xmonui causes it to write these strings to standard output which are
then usually read by xmond. You can just run xmond by itself and type
in the strings, or, even better, use a file as input to xmond. There
are too many strings to list here, but if you run xmonui by itself, you
will see the strings being printed to standard output. Run
xmonui > command.file
to create a file of strings that can be used as input to xmond. For
example, a file which will cause xmond to monitor the Bell request and
also print the names of all events would contain the lines:
monitor_request_on 104
event_verbose 1
Running
xmond < command.file
will then set up xmond in the same way each time. Note that when run‐
ning xmond by itself, it does not exit on reading end-of-file and so it
must be killed. (I use CONTROL-C to kill. Your kill character may be
different.)
It is also possible to initialise xmond with a file, and then take fur‐
ther commands from xmonui by running
xmonui | cat command.file - | xmond
The cat command first sends the command.file to xmond and then passes
the output of xmonui to xmond. Please note that in this case xmonui
will not show the new state of xmond correctly. For example, xmonui
starts up assuming that no requests have been selected, even if the
command.file has initialised xmond by selecting some requests. This
inconsistency does not effect the usability of xmon but may be confus‐
ing.
The string
quit
will cause xmond to exit, so make sure that this does not occur in any
input file. Also it is meaningless to use the statistics commands from
within an input file because these will be read before any X clients
have connected.
EVENT RECORDING AND PLAYBACK
Xmon contains an unfinished attempt at event recording and playback.
It is fairly crude and does not work properly. If you are interested
in exploring it and perhaps doing some more work on it, please try it
out. To compile it in, you will need to modify the Imakefile as sug‐
gested in the comments.
To try it out, first run xmond with the -record option and with stan‐
dard output redirected to a file. The -record option causes xmon to
write, to standard output, a log of all user events it receives. Run
an X client through xmond and interact with it. The mouse and keyboard
events will be logged to the file. Now kill that invocation of xmond.
Now run xmond with the -play option and with standard input redirected
from the event log file just produced. Now run the same X client as
before, but do not interact with it. The client should receive events
from xmond according to the log file and behave in the same way as
before.
The events are played back at the same speed as when recorded (thanks
to code contributed by Marc Vertes). The algorithm used to decide when
the client is ready to receive the next event is faulty and can some‐
times wait forever. It simply counts the number of ImageText8 and
PolyText8 requests that are received and records the counts with each
event in the log file. During replay, an event is sent to the client
when the matching number of requests have been received.
For example, to record and playback a simple xterm session:
xmond-record > foo
(then run xterm through it, typing a few commands)
(exit xterm and kill xmond)
xmond-play < foo
(now run xterm through it again)
It half works. Good luck.
BUGS
No provision is included for extensions to the base protocol.
Xmon only handles TCP socket connections. UNIX domain sockets and DEC‐
net are not supported.
There should be a better way of initialising the state of xmond and
having this new state reflected in xmonui.
Because of the security method used by your X server, it may reject
connection attempts made by xmond. A work-around is to run
xhost +
to force the X server to accept all connections.
SEE ALSOX(1)
X Window System Protocol, MIT X Consortium Standard, X Version 11,
Release 4, by Robert W. Scheifler.
AUTHORS
Greg McFarlane, OTC, Australia, from the xscope program written by
James L Peterson, MCC.
Please send any bug reports or modifications to
gregm@iname.com
X Version 11 30 March 1996 xmon(1)
