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] [-f atom format [dfor‐
12       mat]]* [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       -f name format [dformat]
77               Specifies  that  the  format for name should be format and that
78               the dformat for name should be dformat.  If dformat is missing,
79               " = $0+\n" is assumed.
80

DESCRIPTION

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

EXAMPLES

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

ENVIRONMENT

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

SEE ALSO

305       X(7), xdpyinfo(1), xwininfo(1), xdriinfo(1), glxinfo(1), xvinfo(1)
306

AUTHOR

308       Mark Lillibridge, MIT Project Athena
309
310
311
312X Version 11                      xprop 1.2.2                         XPROP(1)
Impressum