Current File : //usr/share/doc/xorgproto/resproto.txt
DRAFT FOR REVIEW
The X Resource Extension
Version 1.2
Rami Ylimäki
rami.ylimaki@vincit.fi
❧❧❧❧❧❧❧❧❧❧❧
1. Introduction
The protocol description of X Resource Extension version 1.1 has been
either lost or has never been written. This specification documents
version 1.0 based on reverse engineered library and server
code. Version 1.1 has been accidentally released from the version
control and while it doesn't have differences to version 1.0, this
version is labeled 1.2 in order to remove the risk of confusion. In
addition to the 1.0 description, this document introduces a new 1.2
version of the extension.
Version 1.2 is a minor release and therefore the changes are
compatible with the previous version. Main enhancements over version
1.0 are:
- Client identification is now possible. For example, servers
supporting version 1.2 may report PID of local clients.
- Size of any resource can be queried from the server. Servers may not
necessarily support size calculation for every resource. However,
clients have now at least the chance to let the server do resource
size estimation for them.
❧❧❧❧❧❧❧❧❧❧❧
2. Notations used in this document
Notation for data types and requests follows the guidelines set in
sections 2-4 of X Window System Protocol standard.
❧❧❧❧❧❧❧❧❧❧❧
3. Interoperability between version 1.1 and 1.2
Version 1.2 only introduces two new requests. However, these requests
could be seen as generalized versions of existing requests. Even
though we aren't deprecating any old requests, libraries could
implement some old requests using the new ones.
The new XResQueryClientIds request could be used instead of
XResQueryClients.
The new XResQueryResourceBytes request could be used instead of
XResQueryClientPixmapBytes.
Using the old requests is still acceptable because we don't want to
change the semantics of existing requests between version 1.1 and 1.2.
❧❧❧❧❧❧❧❧❧❧❧
4. Data types
4.1 Types in version 1.0
CLIENTXIDRANGE [ resource_base: CARD32
resource_mask: CARD32 ]
This type is used for reply of XResQueryClients in version 1.1. It
represents the range of resource allocated for a client and can be
also used for client identification.
resource_base
First resource ID reserved for a client. Used also to identify the
clients themselves.
resource_mask
Mask that can be used to identify a client from some resource
ID. Just zero the bits indicated by this mask from any resource ID
to identify the client that owns the resource.
CLIENTXID [ client: XID ]
This type identifies a single client by a resource owned by that
client or by the first resource ID allocated for the client
(resource_base of CLIENTXIDRANGE). Whenever a resource ID is used, it
is masked by resource_mask of CLIENTXIDRANGE to find out the client
that owns the resource.
CLIENTRESOURCETYPECOUNT [ resource_type: ATOM
count: CARD32 ]
This type is used for reply of XResQueryClientResources in version
1.1. It represents the number of certain type of resources that are
owned by some client.
resource_type
Atom specifying the type of a resource.
count
Number of resources of the given type owned by a client.
4.2 Types in version 1.2
4.2.1 Types used by XResQueryClientIds
CLIENTIDMASK { ClientXid = 0x1, LocalClientPid = 0x2 }
A bitmask specifying a client identification method. Currently only
the PID of local clients is supported in the form of
LocalClientPid. ClientXid is provided for backward compatibility with
version 1.0 so that the new 1.2 requests (XResQueryClientIds) can be
used in place of the older ones (XResQueryClients).
CLIENTIDSPEC [ client: CLIENTXID or None
mask: SETofCLIENTIDMASK or None ]
A data structure for selecting client IDs.
client
ID of a resource allocated for some client. Only the part
identifying a client is actually used. The resource_base of
CLIENTXIDRANGE can be used if the client doesn't own any
resources. However, any resource ID is accepted because that makes
identifying the owners of existing resources easy. The null
resource None can be used to select all clients.
mask
Collection of identification methods that should be applied on the
client. The special value None can be used to apply all supported
identification methods.
CLIENTIDVALUE [ spec: CLIENTIDSPEC
length: CARD32
value: LISTofCARD32 ]
A data structure specifying a single client ID.
spec
A unique identifier for a specific ID of some client. Wildcards
such as None and bitmask unions aren't allowed. The data structure
must always identify a single client and single ID type. However,
the client doesn't have to be specified as the resource_base of
CLIENTXIDRANGE and can be any resource owned by the client.
length
Specifies the length of an ID in units of CARD32. The length
depends on the ID type. In version 1.2 the lengths are 0 for
ClientXid and 4 for LocalClientPid. The length of ClientXid is 0
because that is already stored in the spec field.
value
Actual ID data. In version 1.2 this is missing for ClientXid and
consists of a single CARD32 for LocalClientPid.
4.2.2 Types used by XResQueryResourceBytes
To better understand how resources are related to each other, it's
useful to introduce the concepts of main resource and cross
reference. By main resource we just mean a normal resource that has a
valid XID. By cross reference we mean a resource that is used by some
other resource.
The same resource may have both of these roles depending on the
context. For example, there could be an ordinary pixmap resource. When
we talk about this resource in isolation the term main resource is
used. We call the exact same resource a cross reference when we are
concentrating on some higher level resource, such as window or
graphics context, that is using the lower level resource. Cross
references may also be internal server resources that don't have a
valid XID.
RESOURCEIDSPEC [ resource: XID or None
type: ATOM or None/AnyPropertyType ]
A data structure for selecting or identifying resources. The
interpretation of fields changes depending on the context. The
differences in interpretation are described below.
resource
An XID of a resource. The null resource None can be used to select
all resources matching some type if the data structure is used in
XResQueryResourceBytes request. The null resource None can be used
to mark private server resources if the data structure is used in
a cross reference of XResQueryResourceBytes reply.
type
An atom identifying the resource type. The null atom
None/AnyPropertyType can be used to select all resource types
matching some resource ID if the data structure is used in
XResQueryResourceBytes request.
RESOURCESIZESPEC [ spec: RESOURCEIDSPEC
bytes: CARD32
ref_count: CARD32
use_count: CARD32 ]
A data structure specifying the size of a single resource.
spec
Uniquely identifies a single resource. Wildcards such as None and
AnyPropertyType aren't allowed for main resources. In cross
references, None is used to mark internal server resources.
bytes
Number of bytes allocated for the resource. The size of a resource
is never divided by a reference count. This is the number of bytes
released in server when there are no more references left to the
resource.
ref_count
Number of total users of the resource. Typically the reference
count is 1 but for pixmaps and other resources used from different
contexts the count may be larger.
use_count
Number of times the resource is used by some other resource. For
main resources this is typically 1, because a resource doesn't
usually use itself recursively. For cross references this is the
number of times the resource is used and is also 1 usually.
RESOURCESIZEVALUE [ size: RESOURCESIZESPEC
num_cross_references: CARD32
cross_references: LISTofRESOURCESIZESPEC ]
A data structure specifying sizes of cross references to other
resources in addition to the main resource size.
size
Size of a main resource.
num_cross_references
Number of cross references to other resources from the main
resource. Currently resources can only have pixmaps as cross
references but this can be extended to other types in the
future. For simple resources this field is therefore 0 and the
cross_references list is missing.
cross_references:
Size specifications for cross references. Note that cross
references may contain resources that don't have a valid XID. For
example, a DRI2 drawable might have a cross reference to a private
pixmap that is used internally in the server only. These private
cross references are contained in this list also. This makes it
possible to emulate XResGetClientPixmapBytes with
XResGetResourceBytes.
❧❧❧❧❧❧❧❧❧❧❧
5. Requests
5.1 Requests in version 1.0
┌───
XResQueryVersion
client_major: CARD8
client_minor: CARD8
▶
server_major: CARD16
server_minor: CARD16
└───
The client sends the highest supported version to the server and the
server sends the highest version it supports, but no higher than the
requested version. Major version changes can introduce
incompatibilities in existing functionality, minor version changes
introduce only backward compatible changes. It is the client's
responsibility to ensure that the server supports a version which is
compatible with its expectations.
client_major
Major X Resource Extension version supported by client.
client_minor
Minor X Resource Extension version supported by client.
server_major
Highest version supported by server that is compatible with
client.
server_minor
Highest version supported by server that is compatible with
client.
┌───
XResQueryClients
▶
num_clients: CARD32
clients: LISTofCLIENTXIDRANGE
└───
The request asks X server to return the list of all currently
connected clients.
num_clients
Number of currently connected clients.
clients
List of XID ranges allocated for the connected clients.
┌───
XResQueryClientResources
client: CLIENTXID
▶
num_types: CARD32
types: LISTofCLIENTRESOURCETYPECOUNT
Errors: Value
└───
This request can be used to ask the number of resources owned by a
client. The server will return the counts of each type of resource.
client
An XID in the resource range of a client. This identifies the
client and not some specific resource.
num_types
Number of different resource types owned by the client.
types
A list of counts for each resource type.
A value error is generated if invalid resource or client XID is given
in the request.
┌───
XResQueryClientPixmapBytes
client: CLIENTXID
▶
bytes: CARD32
bytes_overflow: CARD32
Errors: Value
└───
This request is used to get the pixmap usage of some client. The
returned number is a sum of memory usage of each pixmap that can be
attributed to the given client. Ideally the server goes through all
pixmaps and divides each pixmap size by the pixmap reference count to
get a pixmap reference size. The reference size is then added to the
returned sum if the client happens to be referencing that pixmap. In
practice some pixmap references may be missed, because it would be too
difficult to keep track of all pixmap references. However, the server
will check the most important client resources that are using pixmaps
and tries to estimate the pixmap usage as well as is possible. In
other words, the server need only make a best-effort attempt to
calculate resource source, so actual resource size may differ from
that reported in practice.
client
Identifies a client by an ID in its resource ID range.
bytes:
Number of bytes attributed to pixmap references from the client
resources.
bytes_overflow:
Higher order word for the bytes field in case the sum of pixmap
reference sizes doesn't fit in CARD32.
A value error is generated if invalid resource or client XID is given
in the request.
5.2 Requests in version 1.2
┌───
XResQueryClientIds
num_specs: CARD32
client_specs: LISTofCLIENTIDSPEC
▶
num_ids: CARD32
client_ids: LISTofCLIENTIDVALUE
Errors: Value
└───
XResQueryClientIds can be used to identify a given set of clients with
some identification method. The request sends a list of specifiers
that select clients and identification methods to server. The server
then tries to identify the chosen clients using the identification
methods specified for each client. The server returns IDs for those
clients that were successfully identified. It's not an error condition
if some identification method couldn't be applied to a client. If the
server is unable to identify some clients, they simply aren't included
in the returned list.
The request supports wildcards in the client specifications so that in
the most general case all IDs of all clients can be queried with a
single CLIENTIDSPEC.
The CLIENTIDSPEC of request and CLIENTIDSPEC of CLIENTIDVALUE in reply
usually match each other. For example, if a request selected a client
by a resource ID owned by the client, then the client is identified by
the same resource ID in the reply. This has been done so that it would
be easy to identify an owner of some resource.
However, the CLIENTIDSPEC of returned CLIENTIDVALUE never contains any
wildcards. If the request used a wildcard to specify all clients in a
single CLIENTIDSPEC, then the reply has expanded the wildcard and
returns separate CLIENTIDVALUE records for each client. In this case
wildcarded clients are identified by resource_base of CLIENTXIDRANGE.
The LocalClientPid type of IDs are included in the reply list only if
the client executing the request asked for it and was also a local
client itself. It doesn't make sense for remote clients to ask PIDs of
local clients.
num_specs
Number of client ID specifications.
client_specs
A list specifying identification methods for clients. Supports
multiple identification methods and clients in a single
specification. See CLIENTIDSPEC for details.
num_ids
Number of IDs that were successfully determined. Can be different
from num_specs or even zero if the server didn't support any
identification methods for the given clients.
client_ids
A list specifying ID information for successfully identified
clients. If wildcards were used in a single CLIENTIDSPEC of
client_specs, then multiple CLIENTIDVALUE records may be returned
for that CLIENTIDSPEC. See CLIENTIDVALUE for details.
A Value error is returned if the request specifies an invalid client
XID or invalid identification method type.
┌───
XResQueryResourceBytes
client: CLIENTXID or None
num_specs: CARD32
resource_specs: LISTofRESOURCEIDSPEC
▶
num_sizes: CARD32
sizes: LISTofRESOURCESIZEVALUE
Errors: Atom, Value
└───
XResQueryResourceBytes can be used to ask the sizes of resources from
X server. The request sends a list of specifiers that selects
resources for size calculation. The server tries to calculate the
sizes of chosen resources and returns an estimate for a resource only
if the size could be determined. It's not an error condition if a size
couldn't be calculated. In that case the resources simply aren't
included in the returned list.
The request supports wildcards so that in the most general case sizes
of all resources of all clients can be queried with a single
RESOURCEIDSPEC. However, the reply has all wildcards expanded and
reports a size of a single resource in each RESOURCESIZEVALUE.
client
An ID of a client can be given to limit the query to resources of
that client. Just like in CLIENTIDSPEC, any resource ID can be
given to identify a client and None can be used if the query
shouldn't be limited to a specific client. Note that in some cases
this field is redundant because resource_specs already fully
determines which resources are selected. If the client ID doesn't
match the owner of any resource in resource_specs, no sizes are
returned and no error is generated.
num_specs
Number of resource specifications.
resource_specs
A list of resource specifications. Each specification can either
uniquely identify a single resource or multiple resources if
wildcarding is used. See RESOURCEIDSPEC for details.
num_sizes
Number of resources whose size could be determined. Can be
different from num_specs or even zero if the server didn't support
size calculation for the given resources.
sizes
A list of resource sizes. Each resource size is linked to a unique
resource. Wildcards are never used in the returned size
records. For example, it's not possible to receive a single
RESOURCESIZEVALUE that would specify the size of all pixmaps if
the sizes of pixmap type resources were asked. Instead, a single
RESOURCESIZEVALUE would be returned for each pixmap in that case.
An Atom error is returned if the request specifies an invalid resource
type. A Value error is returned if the request specifies an invalid
XID for a client or a resource.
❧❧❧❧❧❧❧❧❧❧❧
Mini Shell