1XPROP(1)                    General Commands Manual                   XPROP(1)
2
3
4

NAME

6       xprop - property displayer for X
7

SYNOPSIS

9       xprop  [-help] [-grammar] [-id id] [-root] [-name name] [-frame] [-font
10       font] [-display display] [-len n] [-notype] [-fs file]  [-remove  prop‐
11       erty-name] [-set property-name value] [-spy] [-version] [-f atom format
12       [dformat]]* [format [dformat] atom]*
13

SUMMARY

15       The xprop utility is for displaying window and font properties in an  X
16       server.   One  window  or font is selected using the command line argu‐
17       ments or possibly in the case of a window, by clicking on  the  desired
18       window.   A  list of properties is then given, possibly with formatting
19       information.
20

OPTIONS

22       -help   Print out a summary of command line options.
23
24       -grammar
25               Print out a detailed grammar for all command line options.
26
27       -id id  This argument allows the user to select window id on  the  com‐
28               mand  line  rather  than using the pointer to select the target
29               window.  This is very useful in debugging X applications  where
30               the  target window is not mapped to the screen or where the use
31               of the pointer might be impossible or interfere with the appli‐
32               cation.
33
34       -name name
35               This  argument allows the user to specify that the window named
36               name is the target window on the command line rather than using
37               the pointer to select the target window.
38
39       -font font
40               This argument allows the user to specify that the properties of
41               font font should be displayed.
42
43       -root   This argument specifies that X's root window is the target win‐
44               dow.   This  is  useful  in situations where the root window is
45               completely obscured.
46
47       -display display
48               This argument allows you to specify the server to  connect  to;
49               see X(7).
50
51       -len n  Specifies  that  at most n bytes of any property should be read
52               or displayed.
53
54       -notype Specifies that the type of each property  should  not  be  dis‐
55               played.
56
57       -fs file
58               Specifies  that  file  file  should be used as a source of more
59               formats for properties.
60
61       -frame  Specifies that when selecting a window by hand (i.e. if none of
62               -name,  -root,  or  -id  are given), look at the window manager
63               frame (if any) instead of looking for the client window.
64
65       -remove property-name
66               Specifies the name of a property to be removed from  the  indi‐
67               cated window.
68
69       -set property-name value
70               Specifies  the  name  of a property and a property value, to be
71               set on the indicated window.
72
73       -spy    Examine window properties forever, looking for property  change
74               events.
75
76       -verson Print program version information and exit.
77
78       -f name format [dformat]
79               Specifies  that  the  format for name should be format and that
80               the dformat for name should be dformat.  If dformat is missing,
81               " = $0+\n" is assumed.
82

DESCRIPTION

84       For  each of these properties, its value on the selected window or font
85       is printed using the supplied formatting information  if  any.   If  no
86       formatting  information  is supplied, internal defaults are used.  If a
87       property is not defined on the selected window or font,  "not  defined"
88       is  printed  as  the  value  for that property.  If no property list is
89       given, all the properties possessed by the selected window or font  are
90       printed.
91
92       A  window  may  be selected in one of four ways.  First, if the desired
93       window is the root window, the -root argument  may  be  used.   If  the
94       desired  window  is not the root window, it may be selected in two ways
95       on the command line, either by id number such as might be obtained from
96       xwininfo,  or by name if the window possesses a name.  The -id argument
97       selects a window by id number in either decimal or hex (must start with
98       0x) while the -name argument selects a window by name.
99
100       The  last  way  to select a window does not involve the command line at
101       all.  If none  of  -font,  -id,  -name,  and  -root  are  specified,  a
102       crosshairs  cursor  is  displayed and the user is allowed to choose any
103       visible window by pressing any pointer button in  the  desired  window.
104       If  it  is desired to display properties of a font as opposed to a win‐
105       dow, the -font argument must be used.
106
107       Other than the above four arguments and the -help argument for  obtain‐
108       ing  help,  and  the -grammar argument for listing the full grammar for
109       the command line, all the other command  line  arguments  are  used  in
110       specifying both the format of the properties to be displayed and how to
111       display them.  The -len n argument specifies that at most  n  bytes  of
112       any  given  property  will  be  read and displayed.  This is useful for
113       example when displaying the cut buffer on the root window  which  could
114       run to several pages if displayed in full.
115
116       Normally each property name is displayed by printing first the property
117       name then its type (if it has  one)  in  parentheses  followed  by  its
118       value.   The  -notype argument specifies that property types should not
119       be displayed.  The -fs argument is used to specify a file containing  a
120       list of formats for properties while the -f argument is used to specify
121       the format for one property.
122
123       The formatting information for a  property  actually  consists  of  two
124       parts, a format and a dformat.  The format specifies the actual format‐
125       ting of the property (i.e., is it made up of words, bytes,  or  longs?,
126       etc.) while the dformat specifies how the property should be displayed.
127
128       The  following  paragraphs  describe how to construct formats and dfor‐
129       mats.  However, for the vast majority of users and  uses,  this  should
130       not be necessary as the built in defaults contain the formats and dfor‐
131       mats necessary to display all the standard properties.  It should  only
132       be necessary to specify formats and dformats if a new property is being
133       dealt with or the user dislikes the standard display format.  New users
134       especially are encouraged to skip this part.
135
136       A  format  consists of one of 0, 8, 16, or 32 followed by a sequence of
137       one or more format characters.  The 0, 8, 16, or 32 specifies how  many
138       bits per field there are in the property.  Zero is a special case mean‐
139       ing use the field size information associated with the property itself.
140       (This is only needed for special cases like type INTEGER which is actu‐
141       ally three different types depending on the size of the fields  of  the
142       property.)
143
144       A  value  of  8  means that the property is a sequence of bytes while a
145       value of 16 would mean that the property is a sequence of  words.   The
146       difference  between  these  two  lies  in the fact that the sequence of
147       words will be byte swapped while the sequence of bytes will not be when
148       read by a machine of the opposite byte order of the machine that origi‐
149       nally wrote the property.  For more information on how  properties  are
150       formatted and stored, consult the Xlib manual.
151
152       Once  the  size  of  the  fields has been specified, it is necessary to
153       specify the type of each field (i.e., is it an integer,  a  string,  an
154       atom, or what?)  This is done using one format character per field.  If
155       there are more fields in the property than format characters  supplied,
156       the  last character will be repeated as many times as necessary for the
157       extra fields.  The format characters and their meaning are as follows:
158
159       a      The field holds an atom number.  A field of this type should  be
160              of size 32.
161
162       b      The  field  is  an boolean.  A 0 means false while anything else
163              means true.
164
165       c      The field is an unsigned number, a cardinal.
166
167       i      The field is a signed integer.
168
169       m      The field is a set of bit flags, 1 meaning on.
170
171       o      The field is an array of icons, packed as a sequence of  32  bit
172              numbers  consisting  of the width, height and ARGB pixel values,
173              as defined for the _NET_WM_ICON property in the Extended  Window
174              Manager  Hints  specification.   A field of this type must be of
175              size 32.
176
177       s      This field and the next ones until either a 0 or the end of  the
178              property  represent  a sequence of bytes.  This format character
179              is only usable with a field size of 8 and is most often used  to
180              represent a string.
181
182       t      This  field and the next ones until either a 0 or the end of the
183              property represent an internationalized text string. This format
184              character  is  only usable with a field size of 8. The string is
185              assumed to be in an ICCCM compliant encoding and is converted to
186              the current locale encoding before being output.
187
188       u      This  field and the next ones until either a 0 or the end of the
189              property represent an UTF-8 encoded unicode string. This  format
190              character  is  only usable with a field size of 8. If the string
191              is found to be an invalid character, the type of encoding viola‐
192              tion  is printed instead, followed by the string formatted using
193              's'. When in an environment  not  capable  of  displaying  UTF-8
194              encoded string, behaviour is identical to 's'.
195
196       x      The  field is a hex number (like 'c' but displayed in hex - most
197              useful for displaying window ids and the like)
198
199       An example format is 32ica which is the format for a property of  three
200       fields  of 32 bits each, the first holding a signed integer, the second
201       an unsigned integer, and the third an atom.
202
203       The format of a dformat unlike that of a format is not so  rigid.   The
204       only  limitations  on a dformat is that one may not start with a letter
205       or a dash.  This is so that it can be  distinguished  from  a  property
206       name  or  an  argument.   A dformat is a text string containing special
207       characters instructing that various fields be printed at various points
208       in a manner similar to the formatting string used by printf.  For exam‐
209       ple, the dformat " is ( $0, $1 \)\n" would render the POINT 3, -4 which
210       has a format of 32ii as " is ( 3, -4 )\n".
211
212       Any  character  other  than  a  $,  ?, \, or a ( in a dformat prints as
213       itself.  To print out one of $, ?, \, or ( precede  it  by  a  \.   For
214       example, to print out a $, use \$.  Several special backslash sequences
215       are provided as shortcuts.  \n will cause a  newline  to  be  displayed
216       while \t will cause a tab to be displayed.  \o where o is an octal num‐
217       ber will display character number o.
218
219       A $ followed by a number n causes field number n to be displayed.   The
220       format  of the displayed field depends on the formatting character used
221       to describe it in the corresponding format.  I.e.,  if  a  cardinal  is
222       described by 'c' it will print in decimal while if it is described by a
223       'x' it is displayed in hex.
224
225       If the field is not present in the property (this is possible with some
226       properties), <field not available> is displayed instead.  $n+ will dis‐
227       play field number n then a comma then field  number  n+1  then  another
228       comma  then  ...  until  the  last  field  defined.   If field n is not
229       defined, nothing is displayed.  This is useful for a property that is a
230       list of values.
231
232       A ? is used to start a conditional expression, a kind of if-then state‐
233       ment.  ?exp(text) will display text if and only  if  exp  evaluates  to
234       non-zero.   This  is useful for two things.  First, it allows fields to
235       be displayed if and only if a flag is set.  And  second,  it  allows  a
236       value  such  as a state number to be displayed as a name rather than as
237       just a number.  The syntax of exp is as follows:
238
239       exp    ::= term | term=exp | !exp
240
241       term   ::= n | $n | mn
242
243       The ! operator is a logical ``not'', changing 0 to 1 and  any  non-zero
244       value  to  0.   =  is  an  equality operator.  Note that internally all
245       expressions are evaluated as 32 bit numbers  so  -1  is  not  equal  to
246       65535.  = returns 1 if the two values are equal and 0 if not.  n repre‐
247       sents the constant value n while $n represents the value of field  num‐
248       ber n.  mn is 1 if flag number n in the first field having format char‐
249       acter 'm' in the corresponding format is 1, 0 otherwise.
250
251       Examples: ?m3(count: $3\n) displays field 3 with a label  of  count  if
252       and   only   if   flag   number   3   (count   starts  at  0!)  is  on.
253       ?$2=0(True)?!$2=0(False) displays the inverted value of field  2  as  a
254       boolean.
255
256       In  order  to display a property, xprop needs both a format and a dfor‐
257       mat.  Before xprop uses its default values of a format  of  32x  and  a
258       dformat  of " = { $0+ }\n", it searches several places in an attempt to
259       find more specific formats.  First, a search is made using the name  of
260       the  property.   If  this fails, a search is made using the type of the
261       property.  This allows type STRING to be defined with one set  of  for‐
262       mats  while  allowing  property  WM_NAME  which is of type STRING to be
263       defined with a different format.  In this way, the display formats  for
264       a given type can be overridden for specific properties.
265
266       The  locations  searched are in order: the format if any specified with
267       the property name (as in 8x WM_NAME), the formats defined by -f options
268       in  last  to first order, the contents of the file specified by the -fs
269       option if any, the contents of the file specified by the  environmental
270       variable XPROPFORMATS if any, and finally xprop's built in file of for‐
271       mats.
272
273       The format of the files referred to by the -fs argument and the  XPROP‐
274       FORMATS variable is one or more lines of the following form:
275
276       name format [dformat]
277
278       Where name is either the name of a property or the name of a type, for‐
279       mat is the format to be used with name and dformat is the dformat to be
280       used with name.  If dformat is not present, " = $0+\n" is assumed.
281

EXAMPLES

283       To display the name of the root window: xprop -root WM_NAME
284
285       To  display  the window manager hints for the clock: xprop -name xclock
286       WM_HINTS
287
288       To display the start of the cut buffer: xprop -root -len  100  CUT_BUF‐
289       FER0
290
291       To  display  the  point  size  of  the  fixed  font:  xprop -font fixed
292       POINT_SIZE
293
294       To display all the properties of window # 0x200007: xprop -id 0x200007
295
296       To set a simple string property: xprop -root  -format  MY_ATOM_NAME  8s
297       -set MY_ATOM_NAME  "my_value"
298

ENVIRONMENT

300       DISPLAY To get default display.
301
302       XPROPFORMATS
303               Specifies  the name of a file from which additional formats are
304               to be obtained.
305

SEE ALSO

307       X(7), xdpyinfo(1), xwininfo(1), xdriinfo(1), glxinfo(1), xvinfo(1)
308

AUTHOR

310       Mark Lillibridge, MIT Project Athena
311
312
313
314X Version 11                      xprop 1.2.3                         XPROP(1)
Impressum