.TH xprop "" "" "X Utility"
.PC "Display an application's properties"
\fBxprop [\-help] [\-grammar] [\-id \fIid\^\fB] [\-root] [\-name \fIname\^\fB] [\-frame] [\-font \fIfont\^\fB] [\-display \fIdisplay\^\fB] [\-len \fIn\^\fB]
	[\-notype] [\-fs \fIfile\^\fB] [\-remove \fIproperty-name\^\fB] [\-spy]  [\-f \fIatom format\fB [\fIdformat\^\fB] ]
.PP
.HS
.SH Options:
.IC "\fB\-display \fIhost\^\fB[:\fIserver\^\fB][.\fIscreen\^\fB]\fR"
Display the output window on screen number
.I screen
of
.I server
on host system
.I host
.IC "\fB\-f \fIname \fIformat\fR [\fIdformat\^\fB]\fR"
Use
.I format
as the format for property
.IR name ,
and use
.I dformat
as its dformat
.IC "\fB\-font \fIname\fR"
Display the properties of font
.I name
.IC "\fB\-frame\fR"
When selecting a window interactively
look at the window manager's frame
instead of for the client window
.IC "\fB\-fs \fIfile\fR"
Read \fIfile\fR as a source of formats for properties
.IC \fB\-grammar\fR
Print a detailed grammar of all command-line options
.IC \fB\-help\fR
Print a summary of command-line options
.IC \fB\-id \fIid\fR"
Display the properties of window with X identifier
.I id
.IC "\fB\-len \fIn\fR"
Read or display no more than
.I n
bytes of any property.
.IC "\fB\-name \fIname\fR"
Display the properties of the window named
.I name
.IC "\fB\-notype\fR"
Do not display a property's type
.IC "\fB\-remove \fIproperty\fR"
Remove
.I property
from the indicated window
.IC "\fB\-spy\fR"
Examine a window's properties forever, looking for changes in properties
.IC "\fB\-root\fR"
Display the properties of the X server's root window
.HE
The X utility
.B xprop
displays the contents of properties.
You can select a window or font by using an command-line argument or,
in the case of a window, by clicking on it.
.B xprop
then displays that window's or font's properties,
possibly with formatting information.
.SH Options
.B xprop
recognizes the following command-line options:
.IP "\fB\-display \fIhost\^\fB[:\fIserver\^\fB][.\fIscreen\^\fB]\fR"
Display the output window on screen number
.I screen
of
.I server
on host system
.IR host .
.IP "\fB\-f \fIname \fIformat\fR [\fIdformat\^\fB]\fR"
Use
.I format
as the format for property
.IR name ,
and use
.I dformat
as its dformat.
If
.I dformat
is missing,
.B xprop
assumes
.BR  "= $0+\en" .
.IP "\fB\-font \fIname\fR"
Display the properties of font
.IR name .
.IP "\fB\-frame\fR"
When the user selects a window interactively
(i.e., if command-line options \fB\-name\fR,
\fB\-root\fR, and \fB\-id\fR are not used),
look at the window manager's frame (if any)
instead of looking for the client window.
.IP "\fB\-fs \fIfile\fR"
Read \fIfile\fR as a source of formats for properties.
.IP \fB\-grammar\fR
Print a detailed grammar of all command-line options.
.IP \fB\-help\fR
Print a summary of command-line options.
.IP "\fB\-id \fIid\fR"
Display the properties of window with X identifier
.IR id .
This is useful when the target window is not mapped to the screen
or when using the mouse is impossible or would interfere with the
application being examined.
.IP "\fB\-len \fIn\fR"
Read or display no more than
.I n
bytes of any property.
This is useful when displaying the contents of the cut buffer, which can
be several pages long.
.IP "\fB\-name \fIname\fR"
Display the properties of the window named
.IR name .
.IP "\fB\-notype\fR"
Do not display a property's type.
.IP "\fB\-remove \fIproperty\fR"
Remove
.I property
from the indicated window.
.IP "\fB\-spy\fR"
Examine a window's properties forever, looking for changes in properties.
.IP "\fB\-root\fR"
Display the properties of the X server's root window.
This is useful in situations where the root window is completely obscured.
.SH "Selecting a Font or Window"
To display the properties of a font, you must use the command-line option
.BR \-font .
To display the properties of a window, you can select the window in any
of four ways:
.IP \fB1.\fR 0.3i
If the desired window is the root window, use the command-line argument
.BR \-root .
.IP \fB2.\fR
If the desired window is not the root window,
you can selected it by its ID number, by using the command-line option
.BR \-id .
.IP \fB2.\fR
If the desired window is not the root window,
you can selected it by its name, by using the command-line option
.BR \-name .
.IP \fB4.\fR
If you do not use any of the options
.BR \-font ,
.BR \-id ,
.BR \-name ,
or
.BR \-root ,
.B xprop
displays a cross-hairs mouse cursor.
To select a window, move the cursor to that window and click any button on
the mouse.
.PP
By default,
.B xprop
prints first the property's name, then its type (if it has one) in parentheses,
then its value.
The command-line argument
.B \-notype
tells
.B xprop
not to display a property's type.
Argument
.B \-fs
names a file that contains a list of formats for properties,
and the argument
.B \-f
specifies the format for one property.
.SH "Formats"
The formatting information for a property consists of two parts:
.I format
and
.IR dformat .
The former specifies the format of the property itself
(i.e., whether it made up of words, bytes, or \fBlong\fRs, etc.),
whereas the latter specifies how the property should be displayed.
If you do not give
.B xprop
a list of properties, it prints information about every property of
the selected window or font.
If a window or font does not contain a requested property,
.B xprop
prints
.DM
	not defined
.DE
.PP
for that property.
.PP
The following paragraphs describe how to construct
.I format
and
.I dformat
strings.
However, for the vast majority of uses, this should not be necessary:
the built-in defaults are sufficient to display all standard properties.
You should find it necessary to specify a
.I format
and
.I dformat
only if you dislike the standard display format.
We encourage new users, in particular, to skip this part.
.PP
A
.I format
begins with a number that gives the number of bits per field in this property.
.B xprop
recognizes the following numbers:
.IP \fB0\fR
Use the field-size information within the property itself.
This is only needed for special cases like type
.BR INTEGER ,
which is actually three different types,
depending upon the size of the fields of the property.
.IP \fB8\fR
The property consists of a sequence of bytes.
.IP \fB16\fR
The property is a sequence of words.
The difference between this and a sequence of bytes is
the machine of the opposite byte ordering will swap the bytes of a word,
where it will leave a sequence of bytes alone.
(For more information on byte ordering, see the entries for
.B "byte ordering"
and
.B swab()
in the \*(CO Lexicon.)
.IP \fB32\fR
The property consists of a sequence of long words.
.PP
Once the size of the fields has been specified,
you must specify the type of each field.
This is done using one format character per field.
If you supply fewer format characters than the property has fields,
.B xprop
repeats the last format
character as many times as necessary for the extra fields.
The format characters and their meaning are as follows:
.IP \fBa\fR
The field holds an atom number.
A field of this type should be of size 32.
.IP \fBb\fR
The field is Boolean.
A `0' means ``false,'' whereas anything else means ``true''.
.IP \fBc\fR
The field is a cardinal value, i.e., an unsigned integer.
.IP \fBi\fR
The field is a signed integer.
.IP \fBm\fR
The field is a set of bit flags; `1' means ``on''.
.IP \fBs\fR
The field is a string.
.B xprop
follows the C standard, in that it assumes that all subsequent bytes
are characters until it reads a NUL (that is, a character with value zero).
Use this format character only with a field size of
.BR 8 .
.IP \fBx\fR
The field is a hexadecimal number.
It is the same as the formatting character
.BR c ,
except that the output is displayed in hexadecimal notation.
This is most useful for displaying window identifiers and the like.
.PP
For example, consider the format
.BR 32ica .
This describes a property that consists of three 32-bit fields,
the first of which holds a signed integer, the second an
unsigned integer, and the third an atom.
.PP
A
.B dformat
defines how you want
.B xprop
to display information about the property in question.
It cannot begin with a letter or a hyphen, so
.B xprop
can distinguish it from a property name or an argument.
For example, the
.I dformat
.DM
	" is ( $0, $1 \e)\en"
.DE
.PP
renders \fBPOINT 3, \-4\fR (which has a
.I format
of
.BR 32ii ) as:
.DM
	is ( 3, -4 )\en
.DE
.PP
.B xprop
prints literally any character other than
.BR $ ,
.BR ? ,
.BR \e ,
or
.BR ( .
To print a literal
.BR $ ,
.BR ? ,
.BR \e ,
or
.BR ( ,
precede it by with a \e.
.B xprop
also recognizes the following escape sequences:
.IP \fB\en\fR
Print a newline character.
.IP \fB\et\fR
Print a tab character.
.IP \fB\e\fIO\fR
Print the number
.I O
in octal notation.
.PP
The notation
.BI \e$ N
tells
.B xprop
to display the contents of field number
.IR N .
How
.B xprop
formats the displayed field depends on the field's
format character in the corresponding
.I format
string.
For example, if the
.I format
string defines a character s being of type
.B c
(that is, a cardinal),
.B xprop
prints it in decimal; whereas if the
.I format
defines it as being of type
.B x
(that is, a hexadecimal number),
.B xprop
displays it in hexadecimal notation.
.PP
If the field is not present in
the property (which possible with some properties),
.B xprop
prints:
.DM
	<field not available>
.DE
.PP
The escape sequence \fB$\fIn\fB+\fR
displays every field from
.I n
through the end of the property.
If field
.I n
is not defined,
.B xprop
displays nothing.
This is useful for a property that is a list of values.
.PP
The formatting sequence
\fB?\fIexp(\fItext\fB)\fR
displays
.I text
only if expression
.I exp
evaluates to non-zero.
This is useful for two reasons.
First, it allow you display a field only if a flag is set.
Second, it lets you display a value (such as a state
number) as a name rather than as a number.
.PP
The syntax of
.I exp
is as follows:
.DS
	\fIexp\fB ::= \fIterm\fB | \fIterm\fB=\fIexp\fB | !\fIexp\fR
	\fIterm\fB ::= \fIn\fB | $\fIn\fB | m\fIn\fR
.DE
.PP
The symbol
.B !
is a logical NOT:
it changes zero to one, and any non-zero value to zero.
The symbol
.B =
is the equality operator.
Note that
.B xprop
evalutes all expressions as 32-bit numbers, so \-1 does not equal 65,535.
.B =
returns one if its two values are equal, and zero if they are not.
.I n
represents the constant value
.IR n ,
whereas
.BI $ n
represents the value of field
.IR n .
.BI m n
is one if flag
.I n
in the first field with format character
.B m
in the corresponding
.I format
string has value one; otherwise, it is zero.
.PP
For example, the format
.DM
	?m3(count: $3\en)
.DE
.PP
displays field 3 with a label of
.B count
only if flag 3 is on.
(Note that flags are counting beginning with 0.)
The format
.DM
	?$2=0(True)?!$2=0(False)
.DE
.PP
displays the string
.B True
if field 2 equals zero, and displays
.B False
if field 2 equals anything other than zero.
.PP
To display a property,
.B xprop
needs both a
.I format
and a
.IR dformat .
Before
.B xprop
uses its default values of a
.I format
of
.B 32x
and a
.I dformat
of
.DM
	= { $0+ }\en
.DE
.PP
it searches several places to find more specific formats.
First, it searches using the name of the property.
If this fails, it searches using the type of the property.
This lets you give properties of type
.B STRING
with one format, yet give property
.B WM_NAME
(which is of type
.BR STRING )
a different format.
.PP
The locations searched are in the following order:
.IP \(bu 0.3i
The format, if any is specified with the
property name.
.IP \(bu
The formats defined by the options
.BR \-f ,
in last to first order.
.IP \(bu
The contents of the file named by the command-line option
.BR \-fs .
.IP \(bu
The contents of the file specified by the environmental variable
.BR XPROPFORMATS ,
if any.
.IP \(bu
Finally,
.BR xprop 's
built-in formats.
.PP
The files referred to by the
.B \-fs
argument and the variable
.B XPROPFORMATS
consist of one or more lines of the following form:
.DM
	\fIname\fR \fIformat\fR [\fIdformat\fR]
.DE
.PP
where
.I name
names a property or type.
If
.I dformat
is not present,
.B xprop
uses
.DM
	" = $0+\en"
.DE
.PP
by default.
.SH Examples
To display the name of the root window, use the command:
.DM
	xprop \-root WM_NAME
.DE
.PP
To display the window manager's hints for the clock, use the command:
.DM
	xprop -name xclock WM_HINTS
.DE
.PP
To display the first 100 bytes of the cut buffer, use the command:
.DM
	xprop -root -len 100 CUT_BUFFER0
.DE
.PP
To display the point size of the fixed font, use the command:
.DM
	xprop -font fixed POINT_SIZE
.DE
.PP
Finally, to display all the properties of window 0x200007,
use the command:
.DM
	xprop -id 0x200007
.DE
.SH Environment
.B xprop
reads the following environmental variables:
.IP \fBDISPLAY\fR
The default display.
.IP \fBXPROPFORMATS\fR
The name of the file from which additional formats are obtained.
.SH "See Also"
.B
appres,
X utilities,
xwininfo
.R
.SH Notes
Copyright \(co 1988, Massachusetts Institute of Technology.
.PP
.II "Lillibridge, Mark"
.B xprop
was written by Mark Lillibridge of MIT Project Athena.
