XMON(1) — Kubota Pacfic Computer Inc. (May 1992)

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 X requests, events, errors, and replies sent between the clients and the server, which are part of the 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 server.

XMOND:        box "xmond"
      arrow <- up from XMOND.n
      box "xmonui"
      arrow <-> left from XMOND.nw CLNT1:        box ht boxht ∗ .3 "client 1"

      arrow <-> left from XMOND.sw CLNTN:        box ht boxht ∗ .3 "client n"

      line dotted from CLNT1.s to CLNTN.n

      arrow down from XMOND.s
      box invis "monitor output to stdout"

      arrow <-> right from XMOND.e
      box "server"

In the previous 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 like an X server. To the server, it behaves like a number of X clients.

XMOND OPTIONS

-server display_name:display_number
Sets the X display to which xmond connects. 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.

-port display_number
Sets the port on which xmond listens for client connections. This port is always on the host where xmond is running. Default is 1.

XMONUI OPTIONS

xmonui accepts all standard X Toolkit command line options, such as the following:

-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 its display correctly. When you normally start up an X application, and if you have not done anything special, it will start up on display 0 of your local host by default. 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 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 display on juggler:0. The xmonui user interface will display on squiggle:0. Monitor output will display in the window where the command was entered.

THE USER INTERFACE

The user interface is divided into four parts: output detail, statistics, selected requests, and selected events.

You can select the amount of detail contained in the output of xmon in the output detail section. You can select different levels of detail for each of the message types: requests, events, errors and replies. The detail setting for errors also applies to setup messages sent at client connection and the end-of-file "message" sent at client shutdown. 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.

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 that 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. File descriptor 3 is where xmon listens for new connections.

You can control the counting of requests, events, and errors in the statistics section 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.

You can monitor selected requests at a different level of detail, or block them from transmission in the selected requests section. You can select requests by clicking on their names in the scrollable list. Clicking again deselects 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 is 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 is 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 initializing 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 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, the strings will print to standard output. To display the strings, run the following command:

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, therefore, it must be killed. (I use CONTROL-C to kill. Your kill character may be different.)

It is also possible to initialize xmond with a file, and then take further commands from xmonui by running the following command:

xmonui | cat command.file - | xmond

The cat command first sends the command.file to xmond and then passes the output of xmonui to xmond. 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 initialized xmond by selecting some requests. This inconsistency does not effect the usability of xmon but it 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 will be read before any X clients have connected.

BUGS

No provision is included for extensions to the base protocol.

xmon handles only TCP socket connections. UNIX domain sockets and DECnet are not supported.

There should be a better way of initializing the state of xmond and having this new state reflected in xmonui.

AUTHORS

Greg McFarlane, OTC, Australia, from the xscope program written by James L Peterson, MCC.

Please send bug reports or modifications to

gregm@otc.otca.oz.au

September 02, 1992

Museum

Related Articles