components/x11/xorg-server/srcs/os/solaris/mdb/README

   1 We have created an mdb module and some simple shell script wrappers
   2 that can be used to retrieve various information from a running X server
   3 or a X server core dump.
   4
   5 Currently available information includes:
   6
   7  - a list of the clients connected to an X server, including for each one:
   8         - the sequence number of the last request it sent
   9         - in the case of most local clients, their process id
  10
  11  - a list of the input devices connected to an X server and if any
  12         active grabs are applied to them, which client has done so.
  13
  14  - if a server grab has been done, the id of the client that has the grab.
  15
  16 Scripts
  17 -------
  18
  19 The simple shell script wrappers are all delivered in /usr/demo/Xserver/mdb
  20 All of these scripts can be run on either a running process or a core file.
  21
  22 To use these scripts on a running Xserver, specify the process id with the
  23 -p flag, such as "list_Xserver_clients -p 32999".   To use on a core file,
  24 simply provide the core file as an argument.   (The command line arguments
  25 are passed through to mdb, see the mdb(1) man page for more details.)
  26
  27 To use on a running Xorg server, you will need to run as root, due to the
  28 restrictions
  29
  30 - list_Xserver_clients
  31
  32 This can be useful for trying to figure out which client is
  33 responsible for the reads and writes you see to a certain file
  34 descriptor in a truss and similar debugging activities. The sequence
  35 number will basically be a count of the number of requests an X client
  36 has sent during its lifetime.
  37
  38 You will get output like this:
  39
  40 max_clients = 1024
  41 CLIENT SEQUENCE #  FD  PIDS
  42     0           0  -1 9719
  43     1           8  15  ??? - NULL OsCommPtr->process
  44     2           9  16 9721
  45     4           8  18  ??? - NULL OsCommPtr->process
  46     5          17 ??? - NULL ClientPtr->osPrivate
  47     6          14  19 9763
  48     7          71  20 9814
  49     8          13  21 9819
  50     9          17  22 9836
  51    10      501747  23 9837
  52    11         147  24 9837
  53    12          11  25 9837
  54    13        9676  26 9843
  55    14       38347  27 9843
  56    15          11  28 9843
  57    16       13251  29 9846 9857 9861 9871
  58    18        5299  31 9847 9891 9894 9900 9904 9922
  59    19        2397  32 9879
  60    21          11  34 9879
  61    23    34389507  36 9885
  62
  63 1342  /usr/dt/bin/dtlogin -daemon
  64   9719  /usr/X11/bin/Xorg :0 -depth 24 -nobanner -auth /var/dt/A:0-epayvc
  65   9721  /usr/openwin/bin/fbconsole -d :0
  66   9720  /usr/dt/bin/dtlogin -daemon
  67     9741  /bin/ksh /usr/dt/bin/Xsession
  68       9819  /usr/dt/bin/sdt_shell -c unsetenv _ PWD;             unsetenv DT;
  69         9821  -csh -c unsetenv _ PWD;             unsetenv DT;      setenv DISP
  70           9837  /usr/dt/bin/dtsession
  71             9843  dtwm
  72             9846  /usr/dt/bin/dtterm -session dtb2aitb -C -ls
  73               9857  -csh
  74               9861  -csh
  75               9871  -csh
  76             9847  /usr/dt/bin/dtterm -session dtP2aqtb -C -ls
  77               9891  -csh
  78               9894  -csh
  79               9900  -csh
  80               9904  -csh
  81               9922  -csh
  82             9879  dtfile -session dtqRaOFb
  83               9949  dtfile -session dtqRaOFb
  84             9885  sdtperfmeter -f -H -t cpu -t disk -s 1 -name fpperfmeter
  85 9836  /usr/dt/bin/ttsession
  86
  87 The output at the end comes from ptree. From this example we can see
  88 the busiest client in this CDE session has been sdtperfmeter since it
  89 has sent 34389507 X requests in order to update the performance meter
  90 once a second. (This session was running for 6 days before this output
  91 was taken.)
  92
  93 - list_Xserver_devicegrab_client
  94
  95 This lists all the input devices known to the Xserver and if they have
  96 been grabbed by any clients, which client holds an active grab.
  97
  98 For instance, on a machine where the xterm "Secure Keyboard" menu item
  99 was chosen to grab the keyboard:
 100
 101  # list_Xserver_devicegrab_client -p 6072
 102   Device "Virtual core pointer" id 2:
 103     -- no active grab on device
 104
 105   Device "Virtual core keyboard" id 3:
 106     -- active grab 5e00000 by client 47
 107
 108   Device "Virtual core XTEST pointer" id 4:
 109     -- no active grab on device
 110
 111   Device "Virtual core XTEST keyboard" id 5:
 112     -- no active grab on device
 113
 114   Device "mouse" id 6:
 115     -- no active grab on device
 116
 117   Device "hotkey" id 7:
 118     -- no active grab on device
 119
 120   Device "keyboard" id 8:
 121     -- no active grab on device
 122
 123 You can then use list_Xserver_clients to find out what client 47 is:
 124
 125   CLIENT SEQUENCE #  FD  PIDS
 126    [...]
 127      47        3378  78 8936
 128    [...]
 129       8936  xterm
 130
 131
 132 - list_Xserver_servergrab_client
 133
 134 This script checks a variable in the X server to determine if a server
 135 grab has been done, and if so which client has done it.
 136
 137 Debugging with mdb
 138 ------------------
 139
 140 The mdb module can also be used directly in an mdb debugging session
 141 on either a live server or a core file.  The module is delivered in
 142 /usr/lib/mdb/proc as Xorg.so, Xvfb.so, Xephyr.so and Xvnc.so so that
 143 it should be automatically loaded when mdb attaches to a process or
 144 core of any of those programs.
 145
 146 Two sets of dcmds are provided, each with a "walker" which simply
 147 iterates over the entries in the X server internal tables, and a
 148 command that prints the information for each entry.
 149
 150 The commands currently provided are:
 151
 152         ::client_pids - prints information about a ClientRec entry
 153            in the X server's array of currently connected X clients.
 154            Switches:
 155              -w    Print arguments with process name when available.
 156
 157         ::inputdev_grabs - prints information about a DeviceIntRec entry
 158            in the X server's list of currently connected input devices.
 159
 160 The walkers to iterate over the lists of these structures in the X server are:
 161
 162         ::client_walk - walks the array of ClientRec entries stored in the
 163                 global array "clients", from 0 to the value of the global
 164                 variable "currentMaxClients"
 165
 166         ::inputdev_walk - walks the linked list of DeviceIntRec entries
 167                 starting at the entry stored in the global variable "InputInfo"
 168
 169 You can run them like this:
 170
 171 # mdb -p 9719
 172 Loading modules: [ Xorg ld.so.1 libc.so.1 libproc.so.1 libnvpair.so.1 libuutil.so.1 libavl.so.1 libsysevent.so.1 ]
 173 > ::walk client_walk
 174 max_clients = 1024
 175 1b7db8
 176 1b7dbc
 177 1b7dc0
 178 [...]
 179 > 1b7dc0  ::client_pids
 180 CLIENT SEQUENCE #   FD  PROCESS
 181     2          20   21   1285 /usr/bin/dbus-launch
 182
 183 If you run one of the commands (such as ::client_pids) without an address in
 184 front, it will automatically call the associated walker to list the
 185 information for all the entries in the list.
 186
 187 For more information about using mdb, see the Solaris Modular Debugger Guide
 188 on http://docs.oracle.com and the mdb OpenSolaris Community website at
 189 http://hub.opensolaris.org/bin/view/Community+Group+mdb/
 190
 191 =============================================================================
 192
 193 Copyright (c) 2010, 2012, Oracle and/or its affiliates. All rights reserved.
 194
 195 Permission is hereby granted, free of charge, to any person obtaining a
 196 copy of this software and associated documentation files (the "Software"),
 197 to deal in the Software without restriction, including without limitation
 198 the rights to use, copy, modify, merge, publish, distribute, sublicense,
 199 and/or sell copies of the Software, and to permit persons to whom the
 200 Software is furnished to do so, subject to the following conditions:
 201
 202 The above copyright notice and this permission notice (including the next
 203 paragraph) shall be included in all copies or substantial portions of the
 204 Software.
 205
 206 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 207 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 208 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
 209 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 210 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 211 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 212 DEALINGS IN THE SOFTWARE.