xscope
(1)
Name
xscope - X Window Protocol Viewer
Synopsis
/usr/bin/xscope [-i<in-port>] [-o<out-port>] [-h<server-
host>] [-d<display-number>] [-q] [-v<n>] [-r] [-D<debug-
level>] [-I] [-S<n>] [-V] [-t]
Description
User Commands XSCOPE(1)
NAME
xscope - X Window Protocol Viewer
SYNOPSIS
/usr/bin/xscope [-i<in-port>] [-o<out-port>] [-h<server-
host>] [-d<display-number>] [-q] [-v<n>] [-r] [-D<debug-
level>] [-I] [-S<n>] [-V] [-t]
DESCRIPTION
Xscope sits in-between an X11 client and an X11 server and
prints the contents of each request, reply, error, or event
that is communicated between them. Xscope can decode the
core X11 protocol and several extensions, including BIG-
REQUESTS, LBX, MIT-SHM, NCD-WinCenterPro, RANDR, and RENDER.
This information can be useful in debugging and performance
tuning of X11 servers and clients.
To operate, xscope must know the host, port, and display to
use to connect to the X11 server. In addition, it must know
the port on which it should listen for X11 clients. Two
cases are common:
(1) The X11 server is on the same host as xscope.
In this case, the input port for xscope should be
selected as an X11 server on a different display, and
the client DISPLAY argument adjusted to select xscope .
For example, if the X11 server is on port 6001, display
1, then xscope can use port 6002 as its input port.
The client can use display 1 for direct access to X11
or display 2 for access to xscope.
(2) The X11 server is on a different host than xscope.
In this case the same input and output ports can be
used, and the host component of the DISPLAY is used to
select xscope or X11.
ARGUMENTS
-i<input-port>
Specify the port that xscope will use to take
requests from clients (defaults to 1). For X11,
this port is automatically biased by 6000.
-o<output-port>
Determines the port that xscope will use to con-
nect to X11 (defaults to 0). For X11, this port
is automatically biased by 6000.
-h<host> Determines the host that xscope will use to find
its X11 server.
-d<display>
Defines the display number. The display number is
X Version 11 Last change: xscope 1.4 1
User Commands XSCOPE(1)
added to the input and output port to give the
actual ports which are used by xscope.
-f<filename>
Instead of decoding a live session, reads previ-
ously captured raw data from a file to decode.
-q Quiet output mode. Gives only the names of
requests, replies, errors, and events, but does
not indicate contents.
-v<print-level>
Determines the level of printing which xscope will
provide. The print-level can be 0 (same as quiet
mode), 1, 2, 3, 4. The larger numbers give more
and more output. For example, a successful setup
returns a string which is the name of the vendor
of the X11 server. At level 1, the explicit field
giving the length of the string is suppressed
since it can be inferred from the string. At
level 2 and above the length is explicitly
printed.
-r Print only raw data without decoding it.
-D<debug-level>
Print debugging information at the specified
level.
-I Enter interactive mode at startup.
-S<n> Toggle output on or off when SIGUSR1 is received.
If n is 0, the initial state is off. If n is 1,
the initial state is on.
-V Print version information and exit.
-t Terminate xscope when all clients close.
INTERACTIVE MODE
When xscope receives an interrupt signal (normally generated
by Control-C) or is started with the -I flag, it enters an
interactive mode in which it prompts for commands. Avail-
able commands in this mode are:
audio, a Show current verbosity level for NAS protocol
packets.
audio n, a n
Set current verbosity level for NAS protocol pack-
ets to n.
X Version 11 Last change: xscope 1.4 2
User Commands XSCOPE(1)
break, b List currently defined breakpoints.
break request..., b request...
Create a breakpoint for the specified protocol
requests. The breakpoint will be enabled by
default. When the breakpoint is enabled, xscope
will stop for interactive commands after process-
ing a request of the specified type. Requests
and extensions may be specified by name or number.
If an extension is followed by a ":" and a number,
it will only break for the specified minor opcode
for that extension. Note that since extension
opcodes are not known until the extension is first
seen, breakpoints cannot currently be set on
extensions until after a QueryExtension request
and reply are processed for that extension, so
users may need to initially set a breakpoint on
QueryExtension, and after processing that set the
breakpoint for the target extension.
cont, c Resume processing of data passing between server
and clients.
delete, del
Delete all breakpoints.
delete breakpoint..., del breakpoint...
Delete listed breakpoints, specified by number.
disable, d
Disable all breakpoints.
disable breakpoint..., d breakpoint...
Disable listed breakpoints, specified by number.
enable, e Enable all breakpoints.
enable breakpoint..., e breakpoint...
Enable listed breakpoints, specified by number.
help, ? Print list of available commands.
help command..., ? command...
Describe specified command or commands.
level, l Show current verbosity level for X11 protocol
packets.
level n, l n
Set current verbosity level for X11 protocol pack-
ets to n.
X Version 11 Last change: xscope 1.4 3
User Commands XSCOPE(1)
quit, q Quit xscope.
step, s Process one request, then prompt for another com-
mand.
EXAMPLES
xscope -v4 -hcleo -d0 -o0 -i1
This command would have xscope communicate with an X11
server on host ``cleo'', display 0; xscope itself would be
available on the current host as display 1 (display of 0
plus the 1 of -i1). Verbose level 4.
xscope -q -d1 -o1 -o3
The X11 server for the current host, display 2 (1 for -d1
plus 1 for -o1) would be used by xscope which would run as
display 4 (1 for -d1 plus 3 for -o3). Quiet mode (verbose
level 0).
SEE ALSO
X(5), Xsecurity(5), X11 Protocol and extension protocol doc-
uments
AUTHOR
James L. Peterson (MCC)
Copyright (C) 1988 MCC
Permission to use, copy, modify, distribute, and sell this
software and its documentation for any purpose is hereby
granted without fee, provided that the above copyright
notice appear in all copies and that both that copyright
notice and this permission notice appear in supporting docu-
mentation, and that the name of MCC not be used in advertis-
ing or publicity pertaining to distribution of the software
without specific, written prior permission. MCC makes no
representations about the suitability of this software for
any purpose. It is provided "as is" without express or
implied warranty.
MCC DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FIT-
NESS, IN NO EVENT SHALL MCC BE LIABLE FOR ANY SPECIAL, INDI-
RECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
OF THIS SOFTWARE.
X Version 11 Last change: xscope 1.4 4
User Commands XSCOPE(1)
ATTRIBUTES
See attributes(5) for descriptions of the following
attributes:
+-----------------------------+-----------------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+-----------------------------+-----------------------------+
|Availability |x11/diagnostic/xscope |
+-----------------------------+-----------------------------+
|Interface Stability |Volatile |
+-----------------------------+-----------------------------+
X Version 11 Last change: xscope 1.4 5