2 The X Resource Extension
11 The protocol description of X Resource Extension version 1.1 has been
12 either lost or has never been written. This specification documents
13 version 1.0 based on reverse engineered library and server
14 code. Version 1.1 has been accidentally released from the version
15 control and while it doesn't have differences to version 1.0, this
16 version is labeled 1.2 in order to remove the risk of confusion. In
17 addition to the 1.0 description, this document introduces a new 1.2
18 version of the extension.
20 Version 1.2 is a minor release and therefore the changes are
21 compatible with the previous version. Main enhancements over version
24 - Client identification is now possible. For example, servers
25 supporting version 1.2 may report PID of local clients.
27 - Size of any resource can be queried from the server. Servers may not
28 necessarily support size calculation for every resource. However,
29 clients have now at least the chance to let the server do resource
30 size estimation for them.
34 2. Notations used in this document
36 Notation for data types and requests follows the guidelines set in
37 sections 2-4 of X Window System Protocol standard.
41 3. Interoperability between version 1.1 and 1.2
43 Version 1.2 only introduces two new requests. However, these requests
44 could be seen as generalized versions of existing requests. Even
45 though we aren't deprecating any old requests, libraries could
46 implement some old requests using the new ones.
48 The new XResQueryClientIds request could be used instead of
51 The new XResQueryResourceBytes request could be used instead of
52 XResQueryClientPixmapBytes.
54 Using the old requests is still acceptable because we don't want to
55 change the semantics of existing requests between version 1.1 and 1.2.
61 4.1 Types in version 1.0
63 CLIENTXIDRANGE [ resource_base: CARD32
64 resource_mask: CARD32 ]
66 This type is used for reply of XResQueryClients in version 1.1. It
67 represents the range of resource allocated for a client and can be
68 also used for client identification.
71 First resource ID reserved for a client. Used also to identify the
74 Mask that can be used to identify a client from some resource
75 ID. Just zero the bits indicated by this mask from any resource ID
76 to identify the client that owns the resource.
78 CLIENTXID [ client: XID ]
80 This type identifies a single client by a resource owned by that
81 client or by the first resource ID allocated for the client
82 (resource_base of CLIENTXIDRANGE). Whenever a resource ID is used, it
83 is masked by resource_mask of CLIENTXIDRANGE to find out the client
84 that owns the resource.
86 CLIENTRESOURCETYPECOUNT [ resource_type: ATOM
89 This type is used for reply of XResQueryClientResources in version
90 1.1. It represents the number of certain type of resources that are
94 Atom specifying the type of a resource.
96 Number of resources of the given type owned by a client.
98 4.2 Types in version 1.2
100 4.2.1 Types used by XResQueryClientIds
102 CLIENTIDMASK { ClientXid = 0x1, LocalClientPid = 0x2 }
104 A bitmask specifying a client identification method. Currently only
105 the PID of local clients is supported in the form of
106 LocalClientPid. ClientXid is provided for backward compatibility with
107 version 1.0 so that the new 1.2 requests (XResQueryClientIds) can be
108 used in place of the older ones (XResQueryClients).
110 CLIENTIDSPEC [ client: CLIENTXID or None
111 mask: SETofCLIENTIDMASK or None ]
113 A data structure for selecting client IDs.
116 ID of a resource allocated for some client. Only the part
117 identifying a client is actually used. The resource_base of
118 CLIENTXIDRANGE can be used if the client doesn't own any
119 resources. However, any resource ID is accepted because that makes
120 identifying the owners of existing resources easy. The null
121 resource None can be used to select all clients.
123 Collection of identification methods that should be applied on the
124 client. The special value None can be used to apply all supported
125 identification methods.
127 CLIENTIDVALUE [ spec: CLIENTIDSPEC
129 value: LISTofCARD32 ]
131 A data structure specifying a single client ID.
134 A unique identifier for a specific ID of some client. Wildcards
135 such as None and bitmask unions aren't allowed. The data structure
136 must always identify a single client and single ID type. However,
137 the client doesn't have to be specified as the resource_base of
138 CLIENTXIDRANGE and can be any resource owned by the client.
140 Specifies the length of an ID in units of CARD32. The length
141 depends on the ID type. In version 1.2 the lengths are 0 for
142 ClientXid and 4 for LocalClientPid. The length of ClientXid is 0
143 because that is already stored in the spec field.
145 Actual ID data. In version 1.2 this is missing for ClientXid and
146 consists of a single CARD32 for LocalClientPid.
148 4.2.2 Types used by XResQueryResourceBytes
150 To better understand how resources are related to each other, it's
151 useful to introduce the concepts of main resource and cross
152 reference. By main resource we just mean a normal resource that has a
153 valid XID. By cross reference we mean a resource that is used by some
156 The same resource may have both of these roles depending on the
157 context. For example, there could be an ordinary pixmap resource. When
158 we talk about this resource in isolation the term main resource is
159 used. We call the exact same resource a cross reference when we are
160 concentrating on some higher level resource, such as window or
161 graphics context, that is using the lower level resource. Cross
162 references may also be internal server resources that don't have a
165 RESOURCEIDSPEC [ resource: XID or None
166 type: ATOM or None/AnyPropertyType ]
168 A data structure for selecting or identifying resources. The
169 interpretation of fields changes depending on the context. The
170 differences in interpretation are described below.
173 An XID of a resource. The null resource None can be used to select
174 all resources matching some type if the data structure is used in
175 XResQueryResourceBytes request. The null resource None can be used
176 to mark private server resources if the data structure is used in
177 a cross reference of XResQueryResourceBytes reply.
179 An atom identifying the resource type. The null atom
180 None/AnyPropertyType can be used to select all resource types
181 matching some resource ID if the data structure is used in
182 XResQueryResourceBytes request.
184 RESOURCESIZESPEC [ spec: RESOURCEIDSPEC
189 A data structure specifying the size of a single resource.
192 Uniquely identifies a single resource. Wildcards such as None and
193 AnyPropertyType aren't allowed for main resources. In cross
194 references, None is used to mark internal server resources.
196 Number of bytes allocated for the resource. The size of a resource
197 is never divided by a reference count. This is the number of bytes
198 released in server when there are no more references left to the
201 Number of total users of the resource. Typically the reference
202 count is 1 but for pixmaps and other resources used from different
203 contexts the count may be larger.
205 Number of times the resource is used by some other resource. For
206 main resources this is typically 1, because a resource doesn't
207 usually use itself recursively. For cross references this is the
208 number of times the resource is used and is also 1 usually.
210 RESOURCESIZEVALUE [ size: RESOURCESIZESPEC
211 num_cross_references: CARD32
212 cross_references: LISTofRESOURCESIZESPEC ]
214 A data structure specifying sizes of cross references to other
215 resources in addition to the main resource size.
218 Size of a main resource.
220 Number of cross references to other resources from the main
221 resource. Currently resources can only have pixmaps as cross
222 references but this can be extended to other types in the
223 future. For simple resources this field is therefore 0 and the
224 cross_references list is missing.
226 Size specifications for cross references. Note that cross
227 references may contain resources that don't have a valid XID. For
228 example, a DRI2 drawable might have a cross reference to a private
229 pixmap that is used internally in the server only. These private
230 cross references are contained in this list also. This makes it
231 possible to emulate XResGetClientPixmapBytes with
232 XResGetResourceBytes.
238 5.1 Requests in version 1.0
249 The client sends the highest supported version to the server and the
250 server sends the highest version it supports, but no higher than the
251 requested version. Major version changes can introduce
252 incompatibilities in existing functionality, minor version changes
253 introduce only backward compatible changes. It is the client's
254 responsibility to ensure that the server supports a version which is
255 compatible with its expectations.
258 Major X Resource Extension version supported by client.
260 Minor X Resource Extension version supported by client.
262 Highest version supported by server that is compatible with
265 Highest version supported by server that is compatible with
272 clients: LISTofCLIENTXIDRANGE
275 The request asks X server to return the list of all currently
279 Number of currently connected clients.
281 List of XID ranges allocated for the connected clients.
284 XResQueryClientResources
288 types: LISTofCLIENTRESOURCETYPECOUNT
293 This request can be used to ask the number of resources owned by a
294 client. The server will return the counts of each type of resource.
297 An XID in the resource range of a client. This identifies the
298 client and not some specific resource.
300 Number of different resource types owned by the client.
302 A list of counts for each resource type.
304 A value error is generated if invalid resource or client XID is given
308 XResQueryClientPixmapBytes
312 bytes_overflow: CARD32
317 This request is used to get the pixmap usage of some client. The
318 returned number is a sum of memory usage of each pixmap that can be
319 attributed to the given client. Ideally the server goes through all
320 pixmaps and divides each pixmap size by the pixmap reference count to
321 get a pixmap reference size. The reference size is then added to the
322 returned sum if the client happens to be referencing that pixmap. In
323 practice some pixmap references may be missed, because it would be too
324 difficult to keep track of all pixmap references. However, the server
325 will check the most important client resources that are using pixmaps
326 and tries to estimate the pixmap usage as well as is possible. In
327 other words, the server need only make a best-effort attempt to
328 calculate resource source, so actual resource size may differ from
329 that reported in practice.
332 Identifies a client by an ID in its resource ID range.
334 Number of bytes attributed to pixmap references from the client
337 Higher order word for the bytes field in case the sum of pixmap
338 reference sizes doesn't fit in CARD32.
340 A value error is generated if invalid resource or client XID is given
343 5.2 Requests in version 1.2
348 client_specs: LISTofCLIENTIDSPEC
351 client_ids: LISTofCLIENTIDVALUE
356 XResQueryClientIds can be used to identify a given set of clients with
357 some identification method. The request sends a list of specifiers
358 that select clients and identification methods to server. The server
359 then tries to identify the chosen clients using the identification
360 methods specified for each client. The server returns IDs for those
361 clients that were successfully identified. It's not an error condition
362 if some identification method couldn't be applied to a client. If the
363 server is unable to identify some clients, they simply aren't included
364 in the returned list.
366 The request supports wildcards in the client specifications so that in
367 the most general case all IDs of all clients can be queried with a
370 The CLIENTIDSPEC of request and CLIENTIDSPEC of CLIENTIDVALUE in reply
371 usually match each other. For example, if a request selected a client
372 by a resource ID owned by the client, then the client is identified by
373 the same resource ID in the reply. This has been done so that it would
374 be easy to identify an owner of some resource.
376 However, the CLIENTIDSPEC of returned CLIENTIDVALUE never contains any
377 wildcards. If the request used a wildcard to specify all clients in a
378 single CLIENTIDSPEC, then the reply has expanded the wildcard and
379 returns separate CLIENTIDVALUE records for each client. In this case
380 wildcarded clients are identified by resource_base of CLIENTXIDRANGE.
382 The LocalClientPid type of IDs are included in the reply list only if
383 the client executing the request asked for it and was also a local
384 client itself. It doesn't make sense for remote clients to ask PIDs of
388 Number of client ID specifications.
390 A list specifying identification methods for clients. Supports
391 multiple identification methods and clients in a single
392 specification. See CLIENTIDSPEC for details.
394 Number of IDs that were successfully determined. Can be different
395 from num_specs or even zero if the server didn't support any
396 identification methods for the given clients.
398 A list specifying ID information for successfully identified
399 clients. If wildcards were used in a single CLIENTIDSPEC of
400 client_specs, then multiple CLIENTIDVALUE records may be returned
401 for that CLIENTIDSPEC. See CLIENTIDVALUE for details.
403 A Value error is returned if the request specifies an invalid client
404 XID or invalid identification method type.
407 XResQueryResourceBytes
408 client: CLIENTXID or None
410 resource_specs: LISTofRESOURCEIDSPEC
413 sizes: LISTofRESOURCESIZEVALUE
418 XResQueryResourceBytes can be used to ask the sizes of resources from
419 X server. The request sends a list of specifiers that selects
420 resources for size calculation. The server tries to calculate the
421 sizes of chosen resources and returns an estimate for a resource only
422 if the size could be determined. It's not an error condition if a size
423 couldn't be calculated. In that case the resources simply aren't
424 included in the returned list.
426 The request supports wildcards so that in the most general case sizes
427 of all resources of all clients can be queried with a single
428 RESOURCEIDSPEC. However, the reply has all wildcards expanded and
429 reports a size of a single resource in each RESOURCESIZEVALUE.
432 An ID of a client can be given to limit the query to resources of
433 that client. Just like in CLIENTIDSPEC, any resource ID can be
434 given to identify a client and None can be used if the query
435 shouldn't be limited to a specific client. Note that in some cases
436 this field is redundant because resource_specs already fully
437 determines which resources are selected. If the client ID doesn't
438 match the owner of any resource in resource_specs, no sizes are
439 returned and no error is generated.
441 Number of resource specifications.
443 A list of resource specifications. Each specification can either
444 uniquely identify a single resource or multiple resources if
445 wildcarding is used. See RESOURCEIDSPEC for details.
447 Number of resources whose size could be determined. Can be
448 different from num_specs or even zero if the server didn't support
449 size calculation for the given resources.
451 A list of resource sizes. Each resource size is linked to a unique
452 resource. Wildcards are never used in the returned size
453 records. For example, it's not possible to receive a single
454 RESOURCESIZEVALUE that would specify the size of all pixmaps if
455 the sizes of pixmap type resources were asked. Instead, a single
456 RESOURCESIZEVALUE would be returned for each pixmap in that case.
458 An Atom error is returned if the request specifies an invalid resource
459 type. A Value error is returned if the request specifies an invalid
460 XID for a client or a resource.