MAN page from Mandrake Other xmon-1.5.4-0.i386.rpm

xmon

Section: User Commands (1)
Updated: 30 March 1996
Index

NAME

xmon - interactive X protocol monitor

SYNOPSIS

xmonui[options] |xmond[options]

DESCRIPTION

Xmon interactively monitors the byte-stream connections between anX server and a number of X clients. Xmon recognizes all requests,events, errors and replies sent between the clients and the serverwhich are part of the core X protocol. The contents of these messages aredisplayed on standard output at a user settable degree of detailfrom none to every bit and byte. Xmon also allows the user toselect a number of requests or events to be monitored at a differentdegree of detail. Xmon will also block the transmissionof selected requests from the clients to the server and selected eventsfrom the server to the clients. Xmon also keeps statistics of thenumber of requests, events, and errors received.

Xmon is made up of two separate processes. The core of xmon is xmondwhich monitors the X protocol streams and displays the protocolmessages on standard output. The interactive interface ishandled by xmonui. These two processes communicate via a pipe fromthe standard output of xmonui to the standard input of xmond.

The following diagram shows the relationships between xmonuiand 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 horizontalconnections 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 serverit 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 environmentvariable. If this is not set, then thedefault for display_name is the local host and thedefault for display_number is 0.If display_number is positive, the real port number is determined by adding it to the baseX server port number, 6000, just as is done for standard X servers.If it is negative, the real port number is the absolute valueof display_number.A negative value may be useful when using xmond as a general purposetcp/ip monitor and the byte stream being monitored does notobey the X protocol.
-port display_number: This option sets the port on which xmond listens for client connections. This port is alwayson the host where xmond is running.Default is 1.The real port number is determined in the same way as forthe -server option.
-verbose verbose_level: This option sets the amount of output initially produced by xmond for eachrequest, reply, event or error received. Thevalues 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, passingbytes from one side to the other without parsing the stream. By default,it prints the hexadecimal value of each byte passed. This behaviourmay be altered by using the -ascii or -noprintraw options.
-ascii: If this option is given, dumps are printed as ascii characters, exceptfor 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 printanything.
-packet_size: If this option is given, xmond initially prints the size of eachblock 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 followingcommand line

xmonui | xmond

Connections made to the display localhost:1 will appear onthe display localhost:0.The xmonui user interface willappear on the display localhost:0.

When starting up the application that you want to monitor, be sure to setit's display correctly.When you normally start up an X application, and ifyou have not done anything special, itwill by default start up on display 0 of your local host.But xmon by defaultis listening as if it is display 1 of your local host. Assuming your Xapplicationis called "myclient" and your local host name is "dolphin" then type thefollowing to start up your application:

myclient -display dolphin:1

Another way to do the same thing is to change the DISPLAY environmentvariable. 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 somethingdifferent to change the DISPLAY environment variable.Also, most clients understand the -display option, but there are thosethat do not.To determine the name of your local host trythe hostname command (although it may not be availableon all machines).

2) If you are on the host squiggle which has two X servers usingthe displays squiggle:0 and squiggle:1, and want to monitorconnections made to the server running on the displayjuggler:0, enter the following command line.

xmonui -display squiggle:0 | xmond -server juggler:0 -port 2

Connections now made to the "display" squiggle:2 willappear on the display juggler:0.The xmonui user interface willappear 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 containedin the output of xmon can be selected. Different levels of detail canbe 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" sentat client shutdown; unknown extended messages; and unexpected replies.If xmon receives a request, reply, event or error whichit 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 correspondingrequest, 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 identified asbeing "SYNTHETIC".

Also in this section is the show packet size toggle. If this isturned on, xmon will display the size of each packet received fromboth clients and servers. The file descriptor of the client or serverwhich sent the packet is also displayed. The first client filedescriptor is 4. File descriptors 0, 1 and 2 are used by standardinput, standard output and standard error and file descriptor 3 is wherexmon listens for new connections.

In the statistics section, the counting of requests, events anderrors 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 monitoredat 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 indicatedby an asterisk (*) in the scrollable list.

The detail toggle isof the same form as in the output detail section, but applies onlyto 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 andcounted normally.If the blocking toggle in set to off, all requests areforwarded to the server.

The selected events section is similar to the above section butdeals 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 itselfinitialising it with some standard setup.The interface between xmonui and xmond is made up of simple asciistrings.Pressing buttons on xmonui causes it to write these strings tostandard output which are then usually read by xmond.You can just run xmond by itselfand type in the strings, or, even better, use a file as input to xmond.There are too many strings to list here, butif you run xmonui by itself, you will see the strings being printed tostandard 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 requestand 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 whenrunning xmond by itself, it does notexit on reading end-of-file and so it must be killed. (I useCONTROL-C to kill.Your kill character may be different.)

It is also possible to initialise xmond with a file, and thentake further commands from xmonui by running

xmonui | cat command.file - | xmond

The cat command first sends the command.file to xmond and then passes theoutput of xmonui to xmond. Please note that in this case xmonui will notshow the new state of xmond correctly.For example, xmonui starts up assuming thatno requests have been selected, even if the command.file has initialisedxmond by selecting some requests.This inconsistency does not effect the usability of xmonbut may be confusing.

The string

quit

will cause xmond to exit, so make sure that this does not occur inany input file. Also it is meaningless to use the statistics commandsfrom within an input file because these will be read before any X clientshave 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 areinterested in exploring it and perhaps doing some more work on it,please try it out. To compile it in, you will need to modify theImakefile as suggested in the comments.

To try it out, first run xmond with the -record option and withstandard output redirected to a file. The -record option causes xmonto write, to standard output, a log of all user events it receives. Run an X client through xmond and interact with it. The mouse andkeyboard events will be logged to the file. Now kill that invocationof xmond.

Now run xmond with the -play option and with standard input redirectedfrom the event log file just produced. Now run the same X client asbefore, but do not interact with it. The client should receive eventsfrom xmond according to the log file and behave in the same way asbefore.

The events are played back at the same speed as when recorded (thanksto code contributed by Marc Vertes). The algorithm used todecide when the client is ready to receive the next event is faultyand can sometimes wait forever. It simply counts the number ofImageText8 and PolyText8 requests that are received and records thecounts with each event in the log file. During replay, an event issent to the client when the matching number of requests have beenreceived.

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 havingthis new state reflected in xmonui.

Because of the security method used by your X server, it may rejectconnection attempts made by xmond. A work-around is to run

xhost +

to force the X server to accept all connections.

AUTHORS

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

Please send any bug reports or modifications to

gregmAATTnms.otc.com.au

This document was created byman2html,using the manual pages.