XSCOPE(1) General Commands Manual XSCOPE(1)
NAME
xscope - X Window Protocol Viewer
SYNOPSIS
xscope [-i<in-port>] [-o<out-port>] [-h<server-host>] [-d<display-
number>] [-f<filename>] [-I] [-S<n>] [-T] [-A] [-a<level>] [-n<server-
host>] [-D<level>] [-q] [-r] [-v<level>] [-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<in-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 connect 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-number>
Defines the display number. The display number is 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 previously captured
raw data from a file to decode.
-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.
-T Transpose some output with an offset of 0x20.
-A Enables tracing of the Network Audio System (NAS) protocol as
well, using a port number derived by adding 2000 to the X11
port number.
-a<level> NAS verbose output level (1 to 4, 1 by default).
-n<server-host>
Set the hostname of the NAS server to connect to.
-D<level> Print debugging information at the specified level (255 by
default) :
- 2, Trace each procedure entry
- 4, I/O, connections
- 8, Scope internals
- 16, Message protocol
- 32 to 64, Was malloc, now unused
- 128 to 256, Really low level
-q Quiet output mode. Gives only the names of requests,
replies, errors, and events, but does not indicate contents.
-r Print only raw data without decoding it.
-v<level> Determines the level of printing which xscope will provide.
The level can be 0 (same as quiet mode), 1 (default), 2, 3,
4, 5. 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.
-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. Available 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 packets to n.
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
processing 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 packets to n.
quit, q Quit xscope.
step, s Process one request, then prompt for another command.
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(7), Xsecurity(7), X11 Protocol and extension protocol documents
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 documentation, and that the name of MCC not be used in
advertising 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 FITNESS, IN NO EVENT
SHALL MCC BE LIABLE FOR ANY SPECIAL, INDIRECT 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 xscope 1.4.2 XSCOPE(1)