1
.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996, 2002 The Open Group
3
.\" Permission is hereby granted, free of charge, to any person obtaining
4
.\" a copy of this software and associated documentation files (the
5
.\" "Software"), to deal in the Software without restriction, including
6
.\" without limitation the rights to use, copy, modify, merge, publish,
7
.\" distribute, sublicense, and/or sell copies of the Software, and to
8
.\" permit persons to whom the Software is furnished to do so, subject to
9
.\" the following conditions:
11
.\" The above copyright notice and this permission notice shall be included
12
.\" in all copies or substantial portions of the Software.
14
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
15
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
17
.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
18
.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
19
.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
20
.\" OTHER DEALINGS IN THE SOFTWARE.
22
.\" Except as contained in this notice, the name of The Open Group shall
23
.\" not be used in advertising or otherwise to promote the sale, use or
24
.\" other dealings in this Software without prior written authorization
25
.\" from The Open Group.
27
.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
28
.\" Digital Equipment Corporation
30
.\" Portions Copyright \(co 1990, 1991 by
33
.\" Permission to use, copy, modify and distribute this documentation for
34
.\" any purpose and without fee is hereby granted, provided that the above
35
.\" copyright notice appears in all copies and that both that copyright notice
36
.\" and this permission notice appear in all copies, and that the names of
37
.\" Digital and Tektronix not be used in in advertising or publicity pertaining
38
.\" to this documentation without specific, written prior permission.
39
.\" Digital and Tektronix makes no representations about the suitability
40
.\" of this documentation for any purpose.
41
.\" It is provided ``as is'' without express or implied warranty.
46
\s+1\fBChapter 9\fP\s-1
48
\s+1\fBWindow and Session Manager Functions\fP\s-1
58
Chapter 9: Window and Session Manager Functions
60
Although it is difficult to categorize functions as exclusively
61
for an application, a window manager, or a session manager,
62
the functions in this chapter are most often used by window managers
64
It is not expected that these functions will be used by most
66
Xlib provides management functions to:
68
Change the parent of a window
70
Control the lifetime of a window
72
Manage installed colormaps
74
Set and retrieve the font search path
80
Control the screen saver
84
Changing the Parent of a Window
86
\*(SN Changing the Parent of a Window
89
To change a window's parent to another window on the same screen, use
91
There is no way to move a window between screens.
92
.IN "XReparentWindow" "" "@DEF@"
95
XReparentWindow\^(\^\fIdisplay\fP, \fIw\fP\^, \fIparent\fP\^, \fIx\fP\^, \fIy\fP\^)
97
Display *\fIdisplay\fP\^;
101
Window \fIparent\fP\^;
103
int \fIx\fP\^, \fIy\fP\^;
106
Specifies the connection to the X server.
108
Specifies the window.
110
Specifies the parent window.
111
.ds Xy \ of the position in the new parent window
116
Specify the x and y coordinates\*(Xy.
119
If the specified window is mapped,
121
automatically performs an
123
request on it, removes it from its current position in the hierarchy,
124
and inserts it as the child of the specified parent.
125
The window is placed in the stacking order on top with respect to
128
After reparenting the specified window,
130
causes the X server to generate a
133
The override_redirect member returned in this event is
134
set to the window's corresponding attribute.
135
Window manager clients usually should ignore this window if this member
138
Finally, if the specified window was originally mapped,
139
the X server automatically performs a
143
The X server performs normal exposure processing on formerly obscured
145
The X server might not generate
147
events for regions from the initial
149
request that are immediately obscured by the final
156
The new parent window is not on the same screen as
157
the old parent window.
159
The new parent window is the specified window or an inferior of the
164
and the window is not.
166
The specified window has a
168
background, and the new parent window is not the same depth as the
178
Controlling the Lifetime of a Window
180
\*(SN Controlling the Lifetime of a Window
183
The save-set of a client is a list of other clients' windows that,
184
if they are inferiors of one of the client's windows at connection close,
185
should not be destroyed and should be remapped if they are unmapped.
186
For further information about close-connection processing,
188
To allow an application's window to survive when a window manager that
189
has reparented a window fails,
190
Xlib provides the save-set functions that you can
191
use to control the longevity of subwindows
192
that are normally destroyed when the parent is destroyed.
193
For example, a window manager that wants to add decoration
194
to a window by adding a frame might reparent an application's
196
When the frame is destroyed,
197
the application's window should not be destroyed
198
but be returned to its previous place in the window hierarchy.
200
The X server automatically removes windows from the save-set
201
when they are destroyed.
204
To add or remove a window from the client's save-set, use
206
.IN "XChangeSaveSet" "" "@DEF@"
209
XChangeSaveSet\^(\^\fIdisplay\fP, \fIw\fP\^, \fIchange_mode\fP\^)
211
Display *\fIdisplay\fP\^;
215
int \fIchange_mode\fP\^;
218
Specifies the connection to the X server.
219
.ds Wi that you want to add to or delete from the client's save-set
221
Specifies the window \*(Wi.
222
.IP \fIchange_mode\fP 1i
230
Depending on the specified mode,
232
either inserts or deletes the specified window from the client's save-set.
233
The specified window must have been created by some other client,
247
To add a window to the client's save-set, use
249
.IN "XAddToSaveSet" "" "@DEF@"
252
XAddToSaveSet\^(\^\fIdisplay\fP, \fIw\fP\^)
254
Display *\fIdisplay\fP\^;
259
Specifies the connection to the X server.
260
.ds Wi that you want to add to the client's save-set
262
Specifies the window \*(Wi.
267
function adds the specified window to the client's save-set.
268
The specified window must have been created by some other client,
281
To remove a window from the client's save-set, use
282
.PN XRemoveFromSaveSet .
283
.IN "XRemoveFromSaveSet" "" "@DEF@"
286
XRemoveFromSaveSet\^(\^\fIdisplay\fP, \fIw\fP\^)
288
Display *\fIdisplay\fP\^;
293
Specifies the connection to the X server.
294
.ds Wi that you want to delete from the client's save-set
296
Specifies the window \*(Wi.
300
.PN XRemoveFromSaveSet
301
function removes the specified window from the client's save-set.
302
The specified window must have been created by some other client,
307
.PN XRemoveFromSaveSet
314
Managing Installed Colormaps
316
\*(SN Managing Installed Colormaps
319
The X server maintains a list of installed colormaps.
320
Windows using these colormaps are guaranteed to display with
321
correct colors; windows using other colormaps may or may not display
323
Xlib provides functions that you can use to install a colormap,
324
uninstall a colormap, and obtain a list of installed colormaps.
327
there is a subset of the installed maps that is viewed as an ordered list
328
and is called the required list.
329
The length of the required list is at most M,
330
where M is the minimum number of installed colormaps specified for the screen
331
in the connection setup.
332
The required list is maintained as follows.
333
When a colormap is specified to
334
.PN XInstallColormap ,
335
it is added to the head of the list;
336
the list is truncated at the tail, if necessary, to keep its length to
338
When a colormap is specified to
339
.PN XUninstallColormap
340
and it is in the required list,
341
it is removed from the list.
342
A colormap is not added to the required list when it is implicitly installed
344
and the X server cannot implicitly uninstall a colormap that is in the
348
To install a colormap, use
349
.PN XInstallColormap .
350
.IN "XInstallColormap" "" "@DEF@"
353
XInstallColormap\^(\^\fIdisplay\fP, \fIcolormap\fP\^)
355
Display *\fIdisplay\fP\^;
357
Colormap \fIcolormap\fP\^;
360
Specifies the connection to the X server.
361
.IP \fIcolormap\fP 1i
362
Specifies the colormap.
367
function installs the specified colormap for its associated screen.
368
All windows associated with this colormap immediately display with
370
You associated the windows with this colormap when you created them by calling
372
.PN XCreateSimpleWindow ,
373
.PN XChangeWindowAttributes ,
375
.PN XSetWindowColormap .
377
If the specified colormap is not already an installed colormap,
378
the X server generates a
380
event on each window that has that colormap.
381
In addition, for every other colormap that is installed as
382
a result of a call to
383
.PN XInstallColormap ,
384
the X server generates a
386
event on each window that has that colormap.
394
To uninstall a colormap, use
395
.PN XUninstallColormap .
396
.IN "XUninstallColormap" "" "@DEF@"
399
XUninstallColormap\^(\^\fIdisplay\fP, \fIcolormap\fP\^)
401
Display *\fIdisplay\fP\^;
403
Colormap \fIcolormap\fP\^;
406
Specifies the connection to the X server.
407
.IP \fIcolormap\fP 1i
408
Specifies the colormap.
412
.PN XUninstallColormap
413
function removes the specified colormap from the required
416
the specified colormap might be uninstalled,
417
and the X server might implicitly install or uninstall additional colormaps.
418
Which colormaps get installed or uninstalled is server dependent
419
except that the required list must remain installed.
421
If the specified colormap becomes uninstalled,
422
the X server generates a
424
event on each window that has that colormap.
425
In addition, for every other colormap that is installed or uninstalled as a
427
.PN XUninstallColormap ,
428
the X server generates a
430
event on each window that has that colormap.
432
.PN XUninstallColormap
438
To obtain a list of the currently installed colormaps for a given screen, use
439
.PN XListInstalledColormaps .
440
.IN "XListInstalledColormaps" "" "@DEF@"
443
Colormap *XListInstalledColormaps\^(\^\fIdisplay\fP, \fIw\fP, \fInum_return\fP\^)
445
Display *\fIdisplay\fP\^;
449
int *\fInum_return\fP\^;
452
Specifies the connection to the X server.
453
.ds Wi that determines the screen
455
Specifies the window \*(Wi.
456
.IP \fInum_return\fP 1i
457
Returns the number of currently installed colormaps.
461
.PN XListInstalledColormaps
462
function returns a list of the currently installed colormaps for the screen
463
of the specified window.
464
The order of the colormaps in the list is not significant
465
and is no explicit indication of the required list.
466
When the allocated list is no longer needed,
470
.PN XListInstalledColormaps
475
Setting and Retrieving the Font Search Path
477
\*(SN Setting and Retrieving the Font Search Path
480
The set of fonts available from a server depends on a font
481
search path. Xlib provides functions to set and retrieve the
482
search path for a server.
485
To set the font search path, use
487
.IN "XSetFontPath" "" "@DEF@"
490
XSetFontPath\^(\^\fIdisplay\fP, \fIdirectories\fP\^, \fIndirs\fP\^)
492
Display *\fIdisplay\fP\^;
494
char **\fIdirectories\fP\^;
499
Specifies the connection to the X server.
500
.IP \fIdirectories\fP 1i
501
Specifies the directory path used to look for a font.
502
Setting the path to the empty list restores the default path defined
505
Specifies the number of directories in the path.
510
function defines the directory search path for font lookup.
511
There is only one search path per X server, not one per client.
512
The encoding and interpretation of the strings are implementation-dependent,
513
but typically they specify directories or font servers to be searched
515
An X server is permitted to cache font information internally;
516
for example, it might cache an entire font from a file and not
517
check on subsequent opens of that font to see if the underlying
518
font file has changed.
520
when the font path is changed,
521
the X server is guaranteed to flush all cached information about fonts
522
for which there currently are no explicit resource IDs allocated.
523
The meaning of an error from this request is implementation-dependent.
531
To get the current font search path, use
533
.IN "XGetFontPath" "" "@DEF@"
536
char **XGetFontPath\^(\^\fIdisplay\fP, \fInpaths_return\fP\^)
538
Display *\fIdisplay\fP\^;
540
int *\fInpaths_return\fP\^;
544
Specifies the connection to the X server.
545
.IP \fInpaths_return\fP 1i
546
Returns the number of strings in the font path array.
551
function allocates and returns an array of strings containing the search path.
552
The contents of these strings are implementation-dependent
553
and are not intended to be interpreted by client applications.
554
When it is no longer needed,
555
the data in the font path should be freed by using
559
To free data returned by
563
.IN "XFreeFontPath" "" "@DEF@"
566
XFreeFontPath\^(\^\fIlist\fP\^)
572
Specifies the array of strings you want to free.
578
frees the data allocated by
583
\*(SN Grabbing the Server
586
Xlib provides functions that you can use to grab and ungrab the server.
587
These functions can be used to control processing of output on other
588
connections by the window system server.
589
While the server is grabbed,
590
no processing of requests or close downs on any other connection will occur.
591
A client closing its connection automatically ungrabs the server.
593
.IN "Window" "managers"
594
Although grabbing the server is highly discouraged, it is sometimes necessary.
597
To grab the server, use
599
.IN "Server" "grabbing"
600
.IN "Grabbing" "server"
601
.IN "XGrabServer" "" "@DEF@"
604
XGrabServer\^(\^\fIdisplay\fP\^)
606
Display *\fIdisplay\fP\^;
609
Specifies the connection to the X server.
614
function disables processing of requests and close downs on all other
615
connections than the one this request arrived on.
616
You should not grab the X server any more than is absolutely necessary.
619
To ungrab the server, use
621
.IN "XUngrabServer" "" "@DEF@"
624
XUngrabServer\^(\^\fIdisplay\fP\^)
626
Display *\fIdisplay\fP\^;
629
Specifies the connection to the X server.
634
function restarts processing of requests and close downs on other connections.
635
You should avoid grabbing the X server as much as possible.
639
\*(SN Killing Clients
642
Xlib provides a function to cause the connection to
643
a client to be closed and its resources to be destroyed.
644
To destroy a client, use
646
.IN "XKillClient" "" "@DEF@"
649
XKillClient\^(\^\fIdisplay\fP, \fIresource\fP\^)
651
Display *\fIdisplay\fP\^;
653
XID \fIresource\fP\^;
656
Specifies the connection to the X server.
657
.IP \fIresource\fP 1i
658
Specifies any resource associated with the client that you want to destroy or
665
forces a close down of the client
666
that created the resource
667
if a valid resource is specified.
668
If the client has already terminated in
673
mode, all of the client's
674
resources are destroyed.
677
is specified, the resources of all clients that have terminated in
679
are destroyed (see section 2.5).
680
This permits implementation of window manager facilities that aid debugging.
681
A client can set its close-down mode to
682
.PN RetainTemporary .
683
If the client then crashes,
684
its windows would not be destroyed.
685
The programmer can then inspect the application's window tree
686
and use the window manager to destroy the zombie windows.
693
Controlling the Screen Saver
695
\*(SN Controlling the Screen Saver
698
Xlib provides functions that you can use to set or reset the mode
699
of the screen saver, to force or activate the screen saver,
700
or to obtain the current screen saver values.
703
To set the screen saver mode, use
704
.PN XSetScreenSaver .
705
.IN "XSetScreenSaver" "" "@DEF@"
708
XSetScreenSaver\^(\^\fIdisplay\fP, \fItimeout\fP\^, \fIinterval\fP\^, \fIprefer_blanking\fP\^, \fIallow_exposures\fP\^)
710
Display *\fIdisplay\fP\^;
712
int \fItimeout\fP\^, \fIinterval\fP\^;
714
int \fIprefer_blanking\fP\^;
716
int \fIallow_exposures\fP\^;
719
Specifies the connection to the X server.
721
Specifies the timeout, in seconds, until the screen saver turns on.
722
.IP \fIinterval\fP 1i
723
Specifies the interval, in seconds, between screen saver alterations.
724
.IP \fIprefer_blanking\fP 1i
725
Specifies how to enable screen blanking.
727
.PN DontPreferBlanking ,
730
.PN DefaultBlanking .
731
.IP \fIallow_exposures\fP 1i
732
Specifies the screen save control values.
734
.PN DontAllowExposures ,
737
.PN DefaultExposures .
740
Timeout and interval are specified in seconds.
741
A timeout of 0 disables the screen saver
742
(but an activated screen saver is not deactivated),
743
and a timeout of \-1 restores the default.
744
Other negative values generate a
747
If the timeout value is nonzero,
749
enables the screen saver.
750
An interval of 0 disables the random-pattern motion.
751
If no input from devices (keyboard, mouse, and so on) is generated
752
for the specified number of timeout seconds once the screen saver is enabled,
753
the screen saver is activated.
756
if blanking is preferred and the hardware supports video blanking,
757
the screen simply goes blank.
758
Otherwise, if either exposures are allowed or the screen can be regenerated
762
the screen is tiled with the root window background tile randomly
763
re-origined each interval seconds.
764
Otherwise, the screens' state do not change,
765
and the screen saver is not activated.
766
The screen saver is deactivated,
767
and all screen states are restored at the next
768
keyboard or pointer input or at the next call to
769
.PN XForceScreenSaver
771
.PN ScreenSaverReset .
773
If the server-dependent screen saver method supports periodic change,
774
the interval argument serves as a hint about how long the change period
775
should be, and zero hints that no periodic change should be made.
776
Examples of ways to change the screen include scrambling the colormap
777
periodically, moving an icon image around the screen periodically, or tiling
778
the screen with the root window background tile, randomly re-origined
787
To force the screen saver on or off, use
788
.PN XForceScreenSaver .
789
.IN "XForceScreenSaver" "" "@DEF@"
792
XForceScreenSaver\^(\^\fIdisplay\fP\^, \fImode\fP\^)
794
Display *\fIdisplay\fP\^;
799
Specifies the connection to the X server.
801
Specifies the mode that is to be applied.
803
.PN ScreenSaverActive
805
.PN ScreenSaverReset .
808
If the specified mode is
809
.PN ScreenSaverActive
810
and the screen saver currently is deactivated,
811
.PN XForceScreenSaver
812
activates the screen saver even if the screen saver had been disabled
813
with a timeout of zero.
814
If the specified mode is
816
and the screen saver currently is enabled,
817
.PN XForceScreenSaver
818
deactivates the screen saver if it was activated,
819
and the activation timer is reset to its initial state
820
(as if device input had been received).
822
.PN XForceScreenSaver
828
To activate the screen saver, use
829
.PN XActivateScreenSaver .
830
.IN "XActivateScreenSaver" "" "@DEF@"
833
XActivateScreenSaver\^(\^\fIdisplay\fP\^)
835
Display *\fIdisplay\fP\^;
838
Specifies the connection to the X server.
842
To reset the screen saver, use
843
.PN XResetScreenSaver .
844
.IN "XResetScreenSaver" "" "@DEF@"
847
XResetScreenSaver\^(\^\fIdisplay\fP\^)
849
Display *\fIdisplay\fP\^;
852
Specifies the connection to the X server.
856
To get the current screen saver values, use
857
.PN XGetScreenSaver .
858
.IN "XGetScreenSaver" "" "@DEF@"
861
XGetScreenSaver\^(\^\fIdisplay\fP, \fItimeout_return\fP\^, \fIinterval_return\fP\^, \fIprefer_blanking_return\fP\^,
863
\fIallow_exposures_return\fP\^)
865
Display *\fIdisplay\fP\^;
867
int *\fItimeout_return\fP\^, *\fIinterval_return\fP\^;
869
int *\fIprefer_blanking_return\fP\^;
871
int *\fIallow_exposures_return\fP\^;
874
Specifies the connection to the X server.
875
.IP \fItimeout_return\fP 1i
876
Returns the timeout, in seconds, until the screen saver turns on.
877
.IP \fIinterval_return\fP 1i
878
Returns the interval between screen saver invocations.
879
.IP \fIprefer_blanking_return\fP 1i
880
Returns the current screen blanking preference
881
.Pn ( DontPreferBlanking ,
884
.PN DefaultBlanking ).
885
.IP \fIallow_exposures_return\fP 1i
886
Returns the current screen save control value
887
.Pn ( DontAllowExposures ,
890
.PN DefaultExposures ).
894
Controlling Host Access
896
\*(SN Controlling Host Access
899
This section discusses how to:
901
Add, get, or remove hosts from the access control list
903
Change, enable, or disable access
905
.IN "Access control list"
907
X does not provide any protection on a per-window basis.
908
If you find out the resource ID of a resource, you can manipulate it.
909
To provide some minimal level of protection, however,
910
connections are permitted only from machines you trust.
911
This is adequate on single-user workstations but obviously
912
breaks down on timesharing machines.
913
Although provisions exist in the X protocol for proper connection
914
authentication, the lack of a standard authentication server
915
leaves host-level access control as the only common mechanism.
917
.IN "Default Protection"
918
The initial set of hosts allowed to open connections typically consists of:
920
The host the window system is running on.
922
On POSIX-conformant systems, each host listed in the
925
The ? indicates the number of the
927
.IN "Files" "/etc/X?.hosts"
928
This file should consist of host names separated by newlines.
929
DECnet nodes must terminate in :: to distinguish them from Internet hosts.
931
If a host is not in the access control list when the access control
932
mechanism is enabled and if the host attempts to establish a connection,
933
the server refuses the connection.
934
To change the access list,
935
the client must reside on the same host as the server and/or must
936
have been granted permission in the initial authorization at connection
939
Servers also can implement other access control policies in addition to
940
or in place of this host access facility.
941
For further information about other access control implementations,
942
see ``X Window System Protocol.''
944
Adding, Getting, or Removing Hosts
946
\*(SN Adding, Getting, or Removing Hosts
949
Xlib provides functions that you can use to add, get, or remove hosts
950
from the access control list.
951
All the host access control functions use the
953
structure, which contains:
955
.IN "XHostAddress" "" "@DEF@"
961
int family; /* for example FamilyInternet */
962
int length; /* length of address, in bytes */
963
char *address; /* pointer to where to find the address */
968
The family member specifies which protocol address family to use
969
(for example, TCP/IP or DECnet) and can be
971
.PN FamilyInternet6 ,
972
.PN FamilyServerInterpreted ,
976
The length member specifies the length of the address in bytes.
977
The address member specifies a pointer to the address.
979
For TCP/IP, the address should be in network byte order.
980
For IP version 4 addresses, the family should be FamilyInternet
981
and the length should be 4 bytes. For IP version 6 addresses, the
982
family should be FamilyInternet6 and the length should be 16 bytes.
984
For the DECnet family,
985
the server performs no automatic swapping on the address bytes.
986
A Phase IV address is 2 bytes long.
987
The first byte contains the least significant 8 bits of the node number.
988
The second byte contains the most significant 2 bits of the
989
node number in the least significant 2 bits of the byte
990
and the area in the most significant 6 bits of the byte.
992
For the ServerInterpreted family, the length is ignored and the address
993
member is a pointer to a
994
.PN XServerInterpretedAddress
995
structure, which contains:
997
.IN "XServerInterpretedAddress" "" "@DEF@"
1003
int typelength; /* length of type string, in bytes */
1004
int valuelength;/* length of value string, in bytes */
1005
char *type; /* pointer to where to find the type string */
1006
char *value; /* pointer to where to find the address */
1007
} XServerInterpretedAddress;
1011
The type and value members point to strings representing the type and value of
1012
the server interpreted entry. These strings may not be NULL-terminated so care
1013
should be used when accessing them. The typelength and valuelength members
1014
specify the length in byte of the type and value strings.
1017
To add a single host, use
1019
.IN "XAddHost" "" "@DEF@"
1022
XAddHost\^(\^\fIdisplay\fP, \fIhost\fP\^)
1024
Display *\fIdisplay\fP\^;
1026
XHostAddress *\fIhost\fP\^;
1028
.IP \fIdisplay\fP 1i
1029
Specifies the connection to the X server.
1032
Specifies the host that is to be \*(Ho.
1037
function adds the specified host to the access control list for that display.
1038
The server must be on the same host as the client issuing the command, or a
1050
To add multiple hosts at one time, use
1052
.IN "XAddHosts" "" "@DEF@"
1055
XAddHosts\^(\^\fIdisplay\fP, \fIhosts\fP, \fInum_hosts\fP\^)
1057
Display *\fIdisplay\fP\^;
1059
XHostAddress *\fIhosts\fP\^;
1061
int \fInum_hosts\fP\^;
1063
.IP \fIdisplay\fP 1i
1064
Specifies the connection to the X server.
1067
Specifies each host that is to be \*(Ho.
1068
.IP \fInum_hosts\fP 1i
1069
Specifies the number of hosts.
1074
function adds each specified host to the access control list for that display.
1075
The server must be on the same host as the client issuing the command, or a
1087
To obtain a host list, use
1089
.IN "XListHosts" "" "@DEF@"
1092
XHostAddress *XListHosts\^(\^\fIdisplay\fP, \fInhosts_return\fP, \fIstate_return\fP\^)
1094
Display *\fIdisplay\fP\^;
1096
int *\fInhosts_return\fP\^;
1098
Bool *\fIstate_return\fP\^;
1100
.IP \fIdisplay\fP 1i
1101
Specifies the connection to the X server.
1102
.IP \fInhosts_return\fP 1i
1103
Returns the number of hosts currently in the access control list.
1104
.IP \fIstate_return\fP 1i
1105
Returns the state of the access control.
1110
function returns the current access control list as well as whether the use
1111
of the list at connection setup was enabled or disabled.
1113
allows a program to find out what machines can make connections.
1114
It also returns a pointer to a list of host structures that
1115
were allocated by the function.
1116
When no longer needed,
1117
this memory should be freed by calling
1121
To remove a single host, use
1123
.IN "XRemoveHost" "" "@DEF@"
1126
XRemoveHost\^(\^\fIdisplay\fP, \fIhost\fP\^)
1128
Display *\fIdisplay\fP\^;
1130
XHostAddress *\fIhost\fP\^;
1132
.IP \fIdisplay\fP 1i
1133
Specifies the connection to the X server.
1136
Specifies the host that is to be \*(Ho.
1141
function removes the specified host from the access control list
1143
The server must be on the same host as the client process, or a
1146
If you remove your machine from the access list,
1147
you can no longer connect to that server,
1148
and this operation cannot be reversed unless you reset the server.
1158
To remove multiple hosts at one time, use
1160
.IN "XRemoveHosts" "" "@DEF@"
1163
XRemoveHosts\^(\^\fIdisplay\fP, \fIhosts\fP, \fInum_hosts\fP\^)
1165
Display *\fIdisplay\fP\^;
1167
XHostAddress *\fIhosts\fP\^;
1169
int \fInum_hosts\fP\^;
1171
.IP \fIdisplay\fP 1i
1172
Specifies the connection to the X server.
1175
Specifies each host that is to be \*(Ho.
1176
.IP \fInum_hosts\fP 1i
1177
Specifies the number of hosts.
1182
function removes each specified host from the access control list for that
1184
The X server must be on the same host as the client process, or a
1187
If you remove your machine from the access list,
1188
you can no longer connect to that server,
1189
and this operation cannot be reversed unless you reset the server.
1198
Changing, Enabling, or Disabling Access Control
1200
\*(SN Changing, Enabling, or Disabling Access Control
1203
Xlib provides functions that you can use to enable, disable,
1204
or change access control.
1206
For these functions to execute successfully,
1207
the client application must reside on the same host as the X server
1208
and/or have been given permission in the initial authorization
1209
at connection setup.
1212
To change access control, use
1213
.PN XSetAccessControl .
1214
.IN "XSetAccessControl" "" "@DEF@"
1217
XSetAccessControl\^(\^\fIdisplay\fP, \fImode\fP\^)
1219
Display *\fIdisplay\fP\^;
1223
.IP \fIdisplay\fP 1i
1224
Specifies the connection to the X server.
1234
.PN XSetAccessControl
1235
function either enables or disables the use of the access control list
1236
at each connection setup.
1238
.PN XSetAccessControl
1246
To enable access control, use
1247
.PN XEnableAccessControl .
1248
.IN "XEnableAccessControl" "" "@DEF@"
1251
XEnableAccessControl\^(\^\fIdisplay\fP\^)
1253
Display *\fIdisplay\fP\^;
1255
.IP \fIdisplay\fP 1i
1256
Specifies the connection to the X server.
1260
.PN XEnableAccessControl
1261
function enables the use of the access control list at each connection setup.
1263
.PN XEnableAccessControl
1269
To disable access control, use
1270
.PN XDisableAccessControl .
1271
.IN "XDisableAccessControl" "" "@DEF@"
1274
XDisableAccessControl\^(\^\fIdisplay\fP\^)
1276
Display *\fIdisplay\fP\^;
1278
.IP \fIdisplay\fP 1i
1279
Specifies the connection to the X server.
1283
.PN XDisableAccessControl
1284
function disables the use of the access control list at each connection setup.
1286
.PN XDisableAccessControl
added
removed
specs/libX11/CH09
