.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "X11::Protocol::Ext::X_Resource 3pm" .TH X11::Protocol::Ext::X_Resource 3pm "2019-08-26" "perl v5.28.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" X11::Protocol::Ext::X_Resource \- server resource usage .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 4 \& use X11::Protocol; \& my $X = X11::Protocol\->new; \& $X\->init_extension(\*(AqX\-Resource\*(Aq) \& or print "X\-Resource extension not available"; \& \& my @clients = $X\->XResourceQueryClients(); \& \& my %resources = $X\->XResourceQueryClientResources ($client_xid); \& \& my $bytes = $X\->XResourceQueryClientPixmapBytes ($client_xid); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The X\-Resource extension gives some server resource utilization information, mainly for use as diagnostics. .IP "\(bu" 4 Current client connections and their \s-1XID\s0 ranges. .IP "\(bu" 4 How many windows, pixmaps, GCs, etc in use by a given client. .IP "\(bu" 4 Total memory used by all the pixmaps of a given client. .PP \&\*(L"Resources\*(R" here means memory, objects, etc, not to be confused with the resource database of user preferences and widget settings of \&\*(L"\s-1RESOURCES\*(R"\s0 in X(7). .PP See \fIexamples/xresource\-print.pl\fR for a simple dump of the resources reported. .SH "REQUESTS" .IX Header "REQUESTS" The following requests are made available with an \f(CW\*(C`init_extension()\*(C'\fR, as per \*(L"\s-1EXTENSIONS\*(R"\s0 in X11::Protocol. .PP .Vb 1 \& my $is_available = $X\->init_extension(\*(AqX\-Resource\*(Aq); .Ve .ie n .IP """($server_major, $server_minor) = $X\->XResourceQueryVersion ($client_major, $client_minor)""" 4 .el .IP "\f(CW($server_major, $server_minor) = $X\->XResourceQueryVersion ($client_major, $client_minor)\fR" 4 .IX Item "($server_major, $server_minor) = $X->XResourceQueryVersion ($client_major, $client_minor)" Negotiate the extension version. \f(CW$client_major\fR and \f(CW$client_minor\fR is what the client would like, the returned \f(CW$server_major\fR and \&\f(CW$server_minor\fR is what the server will do, which might be lower than requested (but not higher). .Sp The current code supports X\-Resource 1.0. The intention is for this module to automatically negotiate in \f(CW\*(C`$X\->init_extension()\*(C'\fR if/when needed. .ie n .IP """@clients = $X\->XResourceQueryClients ()""" 4 .el .IP "\f(CW@clients = $X\->XResourceQueryClients ()\fR" 4 .IX Item "@clients = $X->XResourceQueryClients ()" Return a list of client connections on the server. Each returned value is an arrayref pair .Sp .Vb 1 \& [ $xid_base, $xid_mask ] .Ve .Sp \&\f(CW$xid_base\fR (an integer) is the start of XIDs for the client. .Sp \&\f(CW$xid_mask\fR (an integer) is a bit mask for the XIDs above that base which the client may use. For example \f(CW$xid_base\fR might be 0xA00000 and \&\f(CW$xid_mask\fR 0x1FFFFF, meaning 0xA00000 through 0xBFFFFF is this client. .Sp .Vb 7 \& my @clients = $X\->XResourceQueryClients; \& print "there are ",scalar(@clients)," clients\en"; \& foreach my $aref (@clients) { \& my $xid_base = $aref\->[0]; \& my $xid_mask = $aref\->[1]; \& printf "client base %X mask %X\en", $xid_base, $xid_mask; \& } .Ve .Sp The given \f(CW$X\fR connection itself is included in the return. Its base and mask are per \f(CW\*(C`$X\->{\*(Aqresource_id_base\*(Aq}\*(C'\fR and \&\f(CW\*(C`$X\->{\*(Aqresource_id_mask\*(Aq}\*(C'\fR. .ie n .IP """($atom,$count,...) = $X\->XResourceQueryClientResources ($xid)""" 4 .el .IP "\f(CW($atom,$count,...) = $X\->XResourceQueryClientResources ($xid)\fR" 4 .IX Item "($atom,$count,...) = $X->XResourceQueryClientResources ($xid)" Return a list of how many of various server things are used by a given client. .Sp The client is identified by an \f(CW$xid\fR. It can be anything in the client's \&\s-1XID\s0 range and doesn't have to be currently allocated or created. For example to enquire about the current client use \&\f(CW\*(C`$X\->{\*(Aqresource_id_base\*(Aq}\*(C'\fR. .Sp The return is a list of resource type (an atom integer) and count of those things, .Sp .Vb 1 \& ($atom, $count, $atom, $count, ...) .Ve .Sp So for example to print all resources, .Sp .Vb 7 \& my @res = $X\->XResourceQueryClientResources ($xid); \& while (@res) { \& my $type_atom = shift @res; \& my $count = shift @res; \& my $type_name = $X\->atom_name($type_atom); \& printf "type $type_name count $count\en"; \& } .Ve .Sp Or put the list into a hash to lookup a particular resource type, .Sp .Vb 1 \& my %res = $X\->XResourceQueryClientResources ($xid); \& \& my $window_atom = X11::AtomConstants::WINDOW(); \& my $windows = $res{$window_atom} || 0; \& \& my $grab_atom = $X\->atom(\*(AqPASSIVE GRAB\*(Aq); \& my $grabs = $res{$grab_atom} || \*(Aqno\*(Aq; \& \& print "using $windows many windows, and $grabs passive grabs"; .Ve .Sp \&\f(CW\*(C`List::Pairwise\*(C'\fR has \f(CW\*(C`mapp()\*(C'\fR and other things to work with this sort of two-at-a-time list. See \fIexamples/xresource\-pairwise.pl\fR for a complete program. .Sp Generally a count entry is only present when the client has 1 or more of the thing. So if no pixmaps then no \f(CW\*(C`PIXMAP\*(C'\fR entry at all. .Sp Basics like \f(CW\*(C`WINDOW\*(C'\fR, \f(CW\*(C`PIXMAP\*(C'\fR, \f(CW\*(C`GC\*(C'\fR \f(CW\*(C`COLORMAP\*(C'\fR, \f(CW\*(C`FONT\*(C'\fR and \f(CW\*(C`CURSOR\*(C'\fR are how many of those in use. The server might also report things like \&\f(CW\*(C`PASSIVE GRAB\*(C'\fR or \f(CW\*(C`COLORMAP ENTRY\*(C'\fR (atoms with spaces in their names). The X.org server (circa version 1.9) even sometimes reports things like \*(L"Unregistered resource 30\*(R" (an atom with that name), which is something or other. .Sp If the given \f(CW$xid\fR is not a connected client then a \f(CW\*(C`BadValue\*(C'\fR error results. Be careful of that when querying resources of another client since the client might disconnect at any time. \f(CW\*(C`$X\->robust_req()\*(C'\fR is good, or maybe \f(CW\*(C`GrabServer\*(C'\fR to hold connections between \&\f(CW\*(C`XResourceQueryClients()\*(C'\fR and \f(CW\*(C`XResourceQueryClientResources()\*(C'\fR. .ie n .IP """$bytes = $X\->XResourceQueryClientPixmapBytes ($xid)""" 4 .el .IP "\f(CW$bytes = $X\->XResourceQueryClientPixmapBytes ($xid)\fR" 4 .IX Item "$bytes = $X->XResourceQueryClientPixmapBytes ($xid)" Return the total bytes of memory on the server used by all the pixmaps of a given client. Pixmaps which only exist as window backgrounds or \s-1GC\s0 tiles or stipples are included, or should be. If the client has no pixmaps at all the return is 0. .Sp The client is identified by an \f(CW$xid\fR as per \&\f(CW\*(C`XResourceQueryClientResources()\*(C'\fR above. It can be anything in the client's \s-1XID\s0 range, allocated or not. .Sp .Vb 5 \& my $pixmap = $X\->new_rsrc; \& $X\->CreatePixmap ($pixmap, \& $X\->{\*(Aqroot\*(Aq}, \& $X\->{\*(Aqroot_depth\*(Aq}, \& 100, 100); # width,height \& \& my $xid = $X\->{\*(Aqresource_id_base\*(Aq}; # own usage \& my $bytes = $X\->XResourceQueryClientPixmapBytes ($xid); \& print "total of all pixmaps is $bytes bytes of memory\en"; .Ve .Sp The return is a 64\-bit value. On a 32\-bit Perl a bigger than 32 bits is returned as floating point, or bigger than 53 bit float as \f(CW\*(C`Math::BigInt\*(C'\fR. Most of the time 32 bits is enough, since that would be 4 Gbytes of pixmaps, and or 53\-bit float should be plenty, that being about 8192 terabytes! .Sp For reference, the X.org server circa version 1.11.4 had a bug where it didn't count space used by pixmaps of depth less than 8 (including depth 1 bitmaps) in the bytes returned. .SH "SEE ALSO" .IX Header "SEE ALSO" X11::Protocol, X11::AtomConstants .PP X.org server source code \&\f(CW\*(C`http://cgit.freedesktop.org/xorg/xserver/tree/Xext/xres.c\*(C'\fR .PP \&\fBxrestop\fR\|(1) .SH "HOME PAGE" .IX Header "HOME PAGE" .SH "LICENSE" .IX Header "LICENSE" Copyright 2011, 2012, 2013, 2014, 2017 Kevin Ryde .PP X11\-Protocol\-Other is free software; you can redistribute it and/or modify it under the terms of the \s-1GNU\s0 General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version. .PP X11\-Protocol\-Other is distributed in the hope that it will be useful, but \&\s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of \s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0 See the \s-1GNU\s0 General Public License for more details. .PP You should have received a copy of the \s-1GNU\s0 General Public License along with X11\-Protocol\-Other. If not, see .