xmon(1) X Version 11 (30 March 1996) 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
displayed 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 messages 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.
Page 1 (printed 7/20/06)
xmon(1) X Version 11 (30 March 1996) xmon(1)
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.
display_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 connections. This port is always on the host
where xmond is running. 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 hexadecimal, 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.
Page 2 (printed 7/20/06)
xmon(1) X Version 11 (30 March 1996) xmon(1)-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 command 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 application, 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 listening as if it is
display 1 of your local host. Assuming your X application 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 understand the -display option, but there are
those that do not. To determine 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
Page 3 (printed 7/20/06)
xmon(1) X Version 11 (30 March 1996) xmon(1)
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 following 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 display 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, statistics, 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 messages 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 hexadecimal.
Note that synthetic events (events sent by XSendEvent) are
monitored in the same way as normal events but are
Page 4 (printed 7/20/06)
xmon(1) X Version 11 (30 March 1996) xmon(1)
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
Page 5 (printed 7/20/06)
xmon(1) X Version 11 (30 March 1996) xmon(1)
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 running 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 further 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 confusing.
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
Page 6 (printed 7/20/06)
xmon(1) X Version 11 (30 March 1996) xmon(1)
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 suggested in the
comments.
To try it out, first run xmond with the -record option and
with standard 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 sometimes 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 DECnet 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
Page 7 (printed 7/20/06)
xmon(1) X Version 11 (30 March 1996) xmon(1)
reject connection attempts made by xmond. A work-around is
to run
xhost +
to force the X server to accept all connections.
SEE ALSO
X(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
Page 8 (printed 7/20/06)
