1XGetWindowProperty(3)           XLIB FUNCTIONS           XGetWindowProperty(3)
2
3
4

NAME

6       XGetWindowProperty,  XListProperties,  XChangeProperty,  XRotateWindow‐
7       Properties, XDeleteProperty - obtain and change window properties
8

SYNTAX

10       int XGetWindowProperty(Display *display, Window w, Atom property,  long
11              long_offset,  long long_length, Bool delete, Atom req_type, Atom
12              *actual_type_return, int  *actual_format_return,  unsigned  long
13              *nitems_return, unsigned long *bytes_after_return, unsigned char
14              **prop_return);
15
16       Atom *XListProperties(Display *display,  Window  w,  int  *num_prop_re‐
17              turn);
18
19       int  XChangeProperty(Display  *display,  Window  w, Atom property, Atom
20              type, int format, int mode, _Xconst  unsigned  char  *data,  int
21              nelements);
22
23       int  XRotateWindowProperties(Display  *display,  Window w, Atom proper‐
24              ties[], int num_prop, int npositions);
25
26       int XDeleteProperty(Display *display, Window w, Atom property);
27

ARGUMENTS

29       actual_format_return
30                 Returns the actual format of the property.
31
32       actual_type_return
33                 Returns the atom identifier  that defines the actual type  of
34                 the property.
35
36       bytes_after_return
37                 Returns the number of bytes remaining to be read in the prop‐
38                 erty if a partial read was performed.
39
40       data      Specifies the property data.
41
42       delete    Specifies a Boolean value that determines whether  the  prop‐
43                 erty is deleted.
44
45       display   Specifies the connection to the X server.
46
47       format    Specifies  whether  the  data  should  be viewed as a list of
48                 8-bit, 16-bit, or 32-bit quantities.  Possible values are  8,
49                 16,  and  32.   This  information allows the X server to cor‐
50                 rectly perform byte-swap operations  as  necessary.   If  the
51                 format  is  16-bit  or  32-bit, you must explicitly cast your
52                 data pointer to an (unsigned char *) in the call to  XChange‐
53                 Property.
54
55       long_length
56                 Specifies  the  length  in 32-bit multiples of the data to be
57                 retrieved.
58
59       long_offset
60                 Specifies the offset in the  specified  property  (in  32-bit
61                 quantities) where the data is to be retrieved.
62
63       mode      Specifies  the  mode of the operation.  You can pass PropMod‐
64                 eReplace, PropModePrepend, or PropModeAppend.
65
66       nelements Specifies the number of elements of the specified  data  for‐
67                 mat.
68
69       nitems_return
70                 Returns  the  actual number of 8-bit, 16-bit, or 32-bit items
71                 stored in the prop_return data.
72
73       num_prop  Specifies the length of the properties array.
74
75       num_prop_return
76                 Returns the length of the properties array.
77
78       npositions
79                 Specifies the rotation amount.
80
81       prop_return
82                 Returns the data in the specified format.   If  the  returned
83                 format  is  8, the returned data is represented as a char ar‐
84                 ray.  If the returned format is 16, the returned data is rep‐
85                 resented  as  a array of short int type and should be cast to
86                 that type to obtain the elements.  If the returned format  is
87                 32,  the  property  data  will be stored as an array of longs
88                 (which in a 64-bit application will be 64-bit values that are
89                 padded in the upper 4 bytes).
90
91       property  Specifies the property name.
92
93       properties
94                 Specifies the array of properties that are to be rotated.
95
96       req_type  Specifies  the  atom  identifier associated with the property
97                 type or AnyPropertyType.
98
99       type      Specifies the type of the property.  The X  server  does  not
100                 interpret  the  type but simply passes it back to an applica‐
101                 tion that later calls XGetWindowProperty.
102
103       w         Specifies the window  whose  property  you  want  to  obtain,
104                 change, rotate or delete.
105

DESCRIPTION

107       The  XGetWindowProperty  function  returns the actual type of the prop‐
108       erty; the actual format of the property; the number of  8-bit,  16-bit,
109       or  32-bit  items transferred; the number of bytes remaining to be read
110       in the property; and a pointer to the data actually returned.  XGetWin‐
111       dowProperty sets the return arguments as follows:
112
113       •    If the specified property does not exist for the specified window,
114            XGetWindowProperty returns  None  to  actual_type_return  and  the
115            value  zero  to  actual_format_return and bytes_after_return.  The
116            nitems_return argument is empty.  In this case, the  delete  argu‐
117            ment is ignored.
118
119       •    If  the  specified property exists but its type does not match the
120            specified type, XGetWindowProperty  returns  the  actual  property
121            type  to  actual_type_return,  the  actual  property format (never
122            zero) to actual_format_return, and the property  length  in  bytes
123            (even  if the actual_format_return is 16 or 32) to bytes_after_re‐
124            turn.  It also ignores the delete argument.  The nitems_return ar‐
125            gument is empty.
126
127       •    If  the specified property exists and either you assign AnyProper‐
128            tyType to the req_type argument or the specified type matches  the
129            actual  property type, XGetWindowProperty returns the actual prop‐
130            erty type to actual_type_return and  the  actual  property  format
131            (never  zero) to actual_format_return.  It also returns a value to
132            bytes_after_return and nitems_return, by  defining  the  following
133            values:
134
135                 N = actual length of the stored property in bytes
136                      (even if the format is 16 or 32)
137                 I = 4 * long_offset
138                 T = N - I
139                 L = MINIMUM(T, 4 * long_length)
140                 A = N - (I + L)
141
142            The  returned value starts at byte index I in the property (index‐
143            ing from zero), and its length in bytes is L.  If  the  value  for
144            long_offset  causes  L  to  be negative, a BadValue error results.
145            The value of bytes_after_return is A, giving the number of  trail‐
146            ing unread bytes in the stored property.
147
148       If the returned format is 8, the returned data is represented as a char
149       array.  If the returned format is 16, the returned data is  represented
150       as  a  short  array  and should be cast to that type to obtain the ele‐
151       ments.  If the returned format is 32, the returned data is  represented
152       as a long array and should be cast to that type to obtain the elements.
153
154       XGetWindowProperty always allocates one extra byte in prop_return (even
155       if the property is zero length) and sets it  to  zero  so  that  simple
156       properties  consisting  of characters do not have to be copied into yet
157       another string before use.
158
159       If delete is True and bytes_after_return  is  zero,  XGetWindowProperty
160       deletes  the  property  from  the window and generates a PropertyNotify
161       event on the window.
162
163       The function returns Success if it executes successfully.  To free  the
164       resulting data, use XFree.
165
166       XGetWindowProperty  can  generate  BadAtom, BadValue, and BadWindow er‐
167       rors.
168
169       The XListProperties function returns a pointer  to  an  array  of  atom
170       properties that are defined for the specified window or returns NULL if
171       no properties were found.  To free the memory allocated by  this  func‐
172       tion, use XFree.
173
174       XListProperties can generate a BadWindow error.
175
176       The XChangeProperty function alters the property for the specified win‐
177       dow and causes the X server to generate a PropertyNotify event on  that
178       window.  XChangeProperty performs the following:
179
180       •    If  mode is PropModeReplace, XChangeProperty discards the previous
181            property value and stores the new data.
182
183       •    If mode is PropModePrepend or PropModeAppend, XChangeProperty  in‐
184            serts the specified data before the beginning of the existing data
185            or onto the end of the existing data, respectively.  The type  and
186            format must match the existing property value, or a BadMatch error
187            results.  If the property is undefined, it is treated  as  defined
188            with the correct type and format with zero-length data.
189
190       If  the  specified format is 8, the property data must be a char array.
191       If the specified format is 16, the property data must be a short array.
192       If the specified format is 32, the property data must be a long array.
193
194       The  lifetime of a property is not tied to the storing client.  Proper‐
195       ties remain until explicitly deleted, until the window is destroyed, or
196       until  the  server  resets.   For a discussion of what happens when the
197       connection to the X server is closed, see  section  2.6.   The  maximum
198       size of a property is server dependent and can vary dynamically depend‐
199       ing on the amount of memory the server has available.  (If there is in‐
200       sufficient space, a BadAlloc error results.)
201
202       XChangeProperty can generate BadAlloc, BadAtom, BadMatch, BadValue, and
203       BadWindow errors.
204
205       The XRotateWindowProperties function allows you to rotate properties on
206       a window and causes the X server to generate PropertyNotify events.  If
207       the property names in the properties array are viewed as being numbered
208       starting  from  zero  and  if  there are num_prop property names in the
209       list, then the value associated with property name I becomes the  value
210       associated  with  property  name  (I + npositions) mod N for all I from
211       zero to N - 1.  The effect is to rotate the states by npositions places
212       around  the  virtual  ring of property names (right for positive nposi‐
213       tions, left for negative npositions).  If npositions mod N is  nonzero,
214       the  X server generates a PropertyNotify event for each property in the
215       order that they are listed in the array.  If an atom occurs  more  than
216       once  in the list or no property with that name is defined for the win‐
217       dow, a BadMatch error results.  If a BadAtom or BadMatch error results,
218       no properties are changed.
219
220       XRotateWindowProperties  can  generate BadAtom, BadMatch, and BadWindow
221       errors.
222
223       The XDeleteProperty function deletes the specified property only if the
224       property was defined on the specified window and causes the X server to
225       generate a PropertyNotify event on the window unless the property  does
226       not exist.
227
228       XDeleteProperty can generate BadAtom and BadWindow errors.
229

DIAGNOSTICS

231       BadAlloc  The  server  failed  to  allocate  the  requested resource or
232                 server memory.
233
234       BadAtom   A value for an Atom argument does not name a defined Atom.
235
236       BadValue  Some numeric value falls outside the range of values accepted
237                 by  the request.  Unless a specific range is specified for an
238                 argument, the full range defined by the  argument's  type  is
239                 accepted.   Any argument defined as a set of alternatives can
240                 generate this error.
241
242       BadWindow A value for a Window argument does not name a defined Window.
243

SEE ALSO

245       XFree(3), XInternAtom(3)
246       Xlib - C Language X Interface
247
248
249
250X Version 11                    libX11 1.7.3.1           XGetWindowProperty(3)
Impressum