Xming

Xmon Manual

Name

       Xmon - interactive X protocol monitor for Microsoft Windows

Synopsis

       xmonui [-option ...] | xmond [-option ...]

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 :1 will appear on the display :0.  The
       xmonui user interface will appear on the display :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  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 Command Prompt you can do this:

       set DISPLAY=dolphin:1
       myclient

       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.

       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.

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.

       type command.file | xmond

       The type command sends the command.file to xmond. 

       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 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; Linux/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 reject
       connection attempts made by xmond.   A possible workaround  is  to  try
       setting  the  authorization  information for the client using xauth; an
       example use would be

       xauth add dolphin:1 MIT-MAGIC-COOKIE-1 <magic-cookie>

       where <magic-cookie> is to be replaced by the cookie that  should  nor-
       mally  be  used  to connect to the X server xmond is talking too (xmond
       will pass the authentication information  on).  Check  the  manpage  of
       xauth  for more information about authorization. If all else fails, you
       can try running

       xhost +

       to force the X server to accept all connections, but beware that  doing
       so is a very bad idea security wise.

Authors

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

       Xmon was adapted for use on Microsoft Windows by Colin Harrison.

Table of contents

  1. Name
  2. Synopsis
  3. Description
  4. Options to xmond
  5. Options to xmonui
  6. Examples
  7. The user interface
  8. Using xmond without xmonui
  9. Event recording and playback
  10. Bugs
  11. Authors
Creative Commons License
The [WWW]Xming website, documentation and images are licensed under a
[WWW]Creative Commons Attribution-NonCommercial-ShareAlike 2.0 UK: England & Wales License.
Xmon is Copyright 1997 by Telstra Corporation Limited, Australia (ACN 051 775 556)
Copyright © 2005-2014 Colin Harrison All Rights Reserved