specs/libX11/CH02.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
   3           "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
   4 <chapter id='Display_Functions'>
   5 <title>Display Functions</title>
   6 <para>
   7 Before your program can use a display, you must establish a connection
   8 to the X server.
   9 Once you have established a connection,
  10 you then can use the Xlib macros and functions discussed in this chapter
  11 to return information about the display.
  12 This chapter discusses how to:
  13 </para>
  14 <itemizedlist>
  15   <listitem>
  16     <para>
  17 Open (connect to) the display
  18     </para>
  19   </listitem>
  20   <listitem>
  21     <para>
  22 Obtain information about the display, image formats, or screens
  23     </para>
  24   </listitem>
  25   <listitem>
  26     <para>
  27 Generate a
  28 <systemitem>NoOperation</systemitem>
  29 protocol request
  30     </para>
  31   </listitem>
  32   <listitem>
  33     <para>
  34 Free client-created data
  35     </para>
  36   </listitem>
  37   <listitem>
  38     <para>
  39 Close (disconnect from) a display
  40     </para>
  41   </listitem>
  42   <listitem>
  43     <para>
  44 Use X Server connection close operations
  45     </para>
  46   </listitem>
  47   <listitem>
  48     <para>
  49 Use Xlib with threads
  50     </para>
  51   </listitem>
  52   <listitem>
  53     <para>
  54 Use internal connections
  55     </para>
  56   </listitem>
  57 </itemizedlist>
  58 <sect1 id="Opening_the_Display">
  59 <title>Opening the Display</title>
  60 <!-- .XS -->
  61 <!-- (SN Opening the Display -->
  62 <!-- .XE -->
  63 <para>
  64 <!-- .LP -->
  65 To open a connection to the X server that controls a display, use
  66 <xref linkend='XOpenDisplay' xrefstyle='select: title'/>.
  67 <indexterm significance="preferred"><primary>XOpenDisplay</primary></indexterm>
  68 </para>
  69 <funcsynopsis id='XOpenDisplay'>
  70 <funcprototype>
  71   <funcdef>Display *<function>XOpenDisplay</function></funcdef>
  72   <paramdef>char *<parameter>display_name</parameter></paramdef>
  73 </funcprototype>
  74 </funcsynopsis>
  75 <variablelist>
  76   <varlistentry>
  77     <term>
  78       <emphasis remap='I'>display_name</emphasis>
  79     </term>
  80     <listitem>
  81       <para>
  82 Specifies the hardware display name, which determines the display
  83 and communications domain to be used.
  84 On a <acronym>POSIX</acronym>-conformant system, if the display_name is NULL,
  85 it defaults to the value of the DISPLAY environment variable.
  86 <indexterm><primary>Environment</primary><secondary>DISPLAY</secondary></indexterm>
  87     </para>
  88   </listitem>
  89   </varlistentry>
  90 </variablelist>
  91 <para>
  92 <!-- .LP -->
  93 <!-- .eM -->
  94 The encoding and interpretation of the display name are
  95 implementation-dependent.
  96 Strings in the Host Portable Character Encoding are supported;
  97 support for other characters is implementation-dependent.
  98 On <acronym>POSIX</acronym>-conformant systems,
  99 the display name or DISPLAY environment variable can be a string in the format:
 100 </para>
 101 <!-- .LP -->
 102 <!-- .sM -->
 103 <literallayout class="monospaced">
 104 <!-- .TA 1i -->
 105 <!-- .ta 1i -->
 106         <emphasis remap='I'>protocol</emphasis>/<emphasis remap='I'>hostname</emphasis>:<emphasis remap='I'>number</emphasis>.<emphasis remap='I'>screen_number</emphasis>
 107 </literallayout>
 108 <variablelist>
 109   <varlistentry>
 110     <term>
 111       <emphasis remap='I'>protocol</emphasis>
 112     </term>
 113     <listitem>
 114       <para>
 115 Specifies a protocol family or an alias for a protocol family.  Supported
 116 protocol families are implementation dependent.  The protocol entry is
 117 optional.  If protocol is not specified, the / separating protocol and
 118 hostname must also not be specified.
 119       </para>
 120     </listitem>
 121   </varlistentry>
 122   <varlistentry>
 123     <term>
 124       <emphasis remap='I'>hostname</emphasis>
 125     </term>
 126     <listitem>
 127       <para>
 128 Specifies the name of the host machine on which the display is physically
 129 attached.
 130 You follow the hostname with either a single colon (:) or a double colon (::).
 131       </para>
 132     </listitem>
 133   </varlistentry>
 134   <varlistentry>
 135     <term>
 136       <emphasis remap='I'>number</emphasis>
 137     </term>
 138     <listitem>
 139       <para>
 140 Specifies the number of the display server on that host machine.
 141 You may optionally follow this display number with a period (.).
 142 A single <acronym>CPU</acronym> can have more than one display.
 143 Multiple displays are usually numbered starting with zero.
 144 <indexterm><primary>Screen</primary></indexterm>
 145       </para>
 146     </listitem>
 147   </varlistentry>
 148   <varlistentry>
 149     <term>
 150       <emphasis remap='I'>screen_number</emphasis>
 151     </term>
 152     <listitem>
 153       <para>
 154 Specifies the screen to be used on that server.
 155 Multiple screens can be controlled by a single X server.
 156 The screen_number sets an internal variable that can be accessed by
 157 using the
 158 <function>DefaultScreen</function>
 159 macro or the
 160 <xref linkend='XDefaultScreen' xrefstyle='select: title'/>
 161 function if you are using languages other than C
 162 (see <link linkend='Display_Macros'>section 2.2.1</link>).
 163     </para>
 164   </listitem>
 165   </varlistentry>
 166 </variablelist>
 167 <para>
 168 <!-- .LP -->
 169 <!-- .eM -->
 170 For example, the following would specify screen 1 of display 0 on the
 171 machine named ``dual-headed'':
 172 </para>
 173 <para>
 174 <!-- .LP -->
 175 <literallayout class="monospaced">
 176 dual-headed:0.1
 177 </literallayout>
 178 </para>
 179 <para>
 180 <!-- .LP -->
 181 The
 182 <xref linkend='XOpenDisplay' xrefstyle='select: title'/>
 183 function returns a
 184 <type>Display</type>
 185 structure that serves as the
 186 connection to the X server and that contains all the information
 187 about that X server.
 188 <xref linkend='XOpenDisplay' xrefstyle='select: title'/>
 189 connects your application to the X server through <acronym>TCP</acronym>
 190 or DECnet communications protocols,
 191 or through some local inter-process communication protocol.
 192 <indexterm><primary>Protocol</primary><secondary><acronym>TCP</acronym></secondary></indexterm>
 193 <indexterm><primary>Protocol</primary><secondary>DECnet</secondary></indexterm>
 194 If the protocol is specified as "tcp", "inet", or "inet6", or
 195 if no protocol is specified and the hostname is a host machine name and a single colon (:)
 196 separates the hostname and display number,
 197 <xref linkend='XOpenDisplay' xrefstyle='select: title'/>
 198 connects using <acronym>TCP</acronym> streams.  (If the protocol is specified as "inet", <acronym>TCP</acronym> over
 199 IPv4 is used.  If the protocol is specified as "inet6", <acronym>TCP</acronym> over IPv6 is used.
 200 Otherwise, the implementation determines which <acronym>IP</acronym> version is used.)
 201 If the hostname and protocol are both not specified,
 202 Xlib uses whatever it believes is the fastest transport.
 203 If the hostname is a host machine name and a double colon (::)
 204 separates the hostname and display number,
 205 <xref linkend='XOpenDisplay' xrefstyle='select: title'/>
 206 connects using DECnet.
 207 A single X server can support any or all of these transport mechanisms
 208 simultaneously.
 209 A particular Xlib implementation can support many more of these transport
 210 mechanisms.
 211 </para>
 212 <para>
 213 <!-- .LP -->
 214 <indexterm><primary>Display</primary></indexterm>
 215 If successful,
 216 <xref linkend='XOpenDisplay' xrefstyle='select: title'/>
 217 returns a pointer to a
 218 <type>Display</type>
 219 structure,
 220 which is defined in
 221 <filename class="headerfile">&lt;X11/Xlib.h&gt;</filename>.
 222 <indexterm type="file"><primary><filename class="headerfile">X11/Xlib.h</filename></primary></indexterm>
 223 <indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xlib.h&gt;</filename></secondary></indexterm>
 224 <indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xlib.h&gt;</filename></secondary></indexterm>
 225 If
 226 <xref linkend='XOpenDisplay' xrefstyle='select: title'/>
 227 does not succeed, it returns NULL.
 228 After a successful call to
 229 <xref linkend='XOpenDisplay' xrefstyle='select: title'/>,
 230 all of the screens in the display can be used by the client.
 231 The screen number specified in the display_name argument is returned
 232 by the
 233 <function>DefaultScreen</function>
 234 macro (or the
 235 <xref linkend='XDefaultScreen' xrefstyle='select: title'/>
 236 function).
 237 You can access elements of the
 238 <type>Display</type>
 239 and
 240 <type>Screen</type>
 241 structures only by using the information macros or functions.
 242 For information about using macros and functions to obtain information from
 243 the
 244 <type>Display</type>
 245 structure,
 246 see <link linkend='Display_Macros'>section 2.2.1</link>.
 247 </para>
 248 <para>
 249 <!-- .LP -->
 250 X servers may implement various types of access control mechanisms
 251 (see <link linkend="Controlling_Host_Access">section 9.8</link>).
 252 </para>
 253 </sect1>
 254 <sect1 id="Obtaining_Information_about_the_Display_Image_Formats_or_Screens">
 255 <title>Obtaining Information about the Display, Image Formats, or Screens</title>
 256 <!-- .XS -->
 257 <!-- (SN Obtaining Information about the Display, Image Formats, or Screens -->
 258 <!-- .XE -->
 259 <para>
 260 <!-- .LP -->
 261 The Xlib library provides a number of useful macros
 262 and corresponding functions that return data from the
 263 <type>Display</type>
 264 structure.
 265 The macros are used for C programming,
 266 and their corresponding function equivalents are for other language bindings.
 267 This section discusses the:
 268 </para>
 269 <itemizedlist>
 270   <listitem>
 271     <para>
 272 Display macros
 273     </para>
 274   </listitem>
 275   <listitem>
 276     <para>
 277 Image format functions and macros
 278     </para>
 279   </listitem>
 280   <listitem>
 281     <para>
 282 Screen information macros
 283     </para>
 284   </listitem>
 285 </itemizedlist>
 286 <para>
 287 <!-- .LP -->
 288 <indexterm ><primary>Display</primary><secondary>data structure</secondary></indexterm>
 289 All other members of the
 290 <type>Display</type>
 291 structure (that is, those for which no macros are defined) are private to Xlib
 292 and must not be used.
 293 Applications must never directly modify or inspect these private members of the
 294 <type>Display</type>
 295 structure.
 296 <!-- .NT Note -->
 297 The
 298 <xref linkend='XDisplayWidth' xrefstyle='select: title'/>,
 299 <xref linkend='XDisplayHeight' xrefstyle='select: title'/>,
 300 <xref linkend='XDisplayCells' xrefstyle='select: title'/>,
 301 <xref linkend='XDisplayPlanes' xrefstyle='select: title'/>,
 302 <xref linkend='XDisplayWidthMM' xrefstyle='select: title'/>,
 303 and
 304 <xref linkend='XDisplayHeightMM' xrefstyle='select: title'/>
 305 functions in the next sections are misnamed.
 306 These functions really should be named Screen<emphasis remap='I'>whatever</emphasis>
 307 and XScreen<emphasis remap='I'>whatever</emphasis>, not Display<emphasis remap='I'>whatever</emphasis> or XDisplay<emphasis remap='I'>whatever</emphasis>.
 308 Our apologies for the resulting confusion.
 309 <!-- .NE -->
 310 </para>
 311 <sect2 id='Display_Macros'>
 312 <title>Display Macros</title>
 313 <!-- .XS -->
 314 <!-- (SN Display Macros -->
 315 <!-- .XE -->
 316 <para>
 317 <!-- .LP -->
 318 Applications should not directly modify any part of the
 319 <type>Display</type>
 320 and
 321 <type>Screen</type>
 322 structures.
 323 The members should be considered read-only,
 324 although they may change as the result of other operations on the display.
 325 </para>
 326 <para>
 327 <!-- .LP  -->
 328 The following lists the C language macros,
 329 their corresponding function equivalents that are for other language bindings,
 330 and what data both can return.
 331 </para>
 332 <para>AllPlanes()</para>
 333 <para>XAllPlanes()</para>
 334 <para>
 335 <!-- .LP -->
 336 <!-- .eM -->
 337 <indexterm significance="preferred"><primary>AllPlanes</primary></indexterm>
 338 <indexterm significance="preferred"><primary>XAllPlanes</primary></indexterm>
 339 Both return a value with all bits set to 1 suitable for use in a plane argument to
 340 a procedure.
 341 </para>
 342 <para>
 343 <!-- .LP -->
 344 <!-- .sp -->
 345 Both
 346 <function>BlackPixel</function>
 347 and
 348 <function>WhitePixel</function>
 349 can be used in implementing a monochrome application.
 350 These pixel values are for permanently allocated entries in the default
 351 colormap.
 352 The actual <acronym>RGB</acronym> (red, green, and blue) values are settable on some screens
 353 and, in any case, may not actually be black or white.
 354 The names are intended to convey the expected relative intensity of the colors.
 355 <!-- .sM -->
 356 </para>
 357 <para>
 358 BlackPixel(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
 359 </para>
 360 <funcsynopsis id='XBlackPixel'>
 361 <funcprototype>
 362   <funcdef>unsigned long <function>XBlackPixel</function></funcdef>
 363   <paramdef>Display<parameter> *display</parameter></paramdef>
 364   <paramdef>int<parameter> screen_number</parameter></paramdef>
 365 </funcprototype>
 366 </funcsynopsis>
 367 <!-- .FN -->
 368 <variablelist>
 369   <varlistentry>
 370     <term>
 371       <emphasis remap='I'>display</emphasis>
 372     </term>
 373     <listitem>
 374       <para>
 375 Specifies the connection to the X server.
 376       </para>
 377     </listitem>
 378   </varlistentry>
 379   <varlistentry>
 380     <term>
 381       <emphasis remap='I'>screen_number</emphasis>
 382     </term>
 383     <listitem>
 384       <para>
 385 Specifies the appropriate screen number on the host server.
 386     </para>
 387   </listitem>
 388   </varlistentry>
 389 </variablelist>
 390 <para>
 391 <!-- .LP -->
 392 <!-- .eM -->
 393 <indexterm significance="preferred"><primary>BlackPixel</primary></indexterm>
 394 <indexterm significance="preferred"><primary>XBlackPixel</primary></indexterm>
 395 Both return the black pixel value for the specified screen.
 396 </para>
 397 <para>
 398 <!-- .LP -->
 399 <!-- .sp -->
 400 <!-- .sM -->
 401 </para>
 402 <para>
 403 WhitePixel(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
 404 </para>
 405 <funcsynopsis id='XWhitePixel'>
 406 <funcprototype>
 407   <funcdef>unsigned long <function>XWhitePixel</function></funcdef>
 408   <paramdef>Display<parameter> *display</parameter></paramdef>
 409   <paramdef>int<parameter> screen_number</parameter></paramdef>
 410 </funcprototype>
 411 </funcsynopsis>
 412 <!-- .FN -->
 413 <variablelist>
 414   <varlistentry>
 415     <term>
 416       <emphasis remap='I'>display</emphasis>
 417     </term>
 418     <listitem>
 419       <para>
 420 Specifies the connection to the X server.
 421       </para>
 422     </listitem>
 423   </varlistentry>
 424   <varlistentry>
 425     <term>
 426       <emphasis remap='I'>screen_number</emphasis>
 427     </term>
 428     <listitem>
 429       <para>
 430 Specifies the appropriate screen number on the host server.
 431     </para>
 432   </listitem>
 433   </varlistentry>
 434 </variablelist>
 435 <para>
 436 <!-- .LP -->
 437 <!-- .eM -->
 438 <indexterm significance="preferred"><primary>WhitePixel</primary></indexterm>
 439 <indexterm significance="preferred"><primary>XWhitePixel</primary></indexterm>
 440 Both return the white pixel value for the specified screen.
 441 </para>
 442 <para>
 443 <!-- .LP -->
 444 <!-- .sp -->
 445 <!-- .sM -->
 446 </para>
 447 <para>
 448 ConnectionNumber(<emphasis remap='I'>display</emphasis>)
 449 </para>
 450 <funcsynopsis id='XConnectionNumber'>
 451 <funcprototype>
 452   <funcdef>int <function>XConnectionNumber</function></funcdef>
 453   <paramdef>Display<parameter> *display</parameter></paramdef>
 454 </funcprototype>
 455 </funcsynopsis>
 456 <!-- .FN -->
 457 <variablelist>
 458   <varlistentry>
 459     <term>
 460       <emphasis remap='I'>display</emphasis>
 461     </term>
 462     <listitem>
 463       <para>
 464 Specifies the connection to the X server.
 465     </para>
 466   </listitem>
 467   </varlistentry>
 468 </variablelist>
 469
 470 <para>
 471 <!-- .LP -->
 472 <!-- .eM -->
 473 <indexterm significance="preferred"><primary>ConnectionNumber</primary></indexterm>
 474 <indexterm significance="preferred"><primary>XConnectionNumber</primary></indexterm>
 475 Both return a connection number for the specified display.
 476 On a <acronym>POSIX</acronym>-conformant system,
 477 this is the file descriptor of the connection.
 478 </para>
 479 <para>
 480 <!-- .LP -->
 481 <!-- .sp -->
 482 <!-- .sM -->
 483 </para>
 484 <para>
 485 DefaultColormap(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
 486 </para>
 487 <funcsynopsis id='XDefaultColormap'>
 488 <funcprototype>
 489   <funcdef>Colormap <function>XDefaultColormap</function></funcdef>
 490   <paramdef>Display<parameter> *display</parameter></paramdef>
 491   <paramdef>int<parameter> screen_number</parameter></paramdef>
 492 </funcprototype>
 493 </funcsynopsis>
 494 <!-- .FN -->
 495 <variablelist>
 496   <varlistentry>
 497     <term>
 498       <emphasis remap='I'>display</emphasis>
 499     </term>
 500     <listitem>
 501       <para>
 502 Specifies the connection to the X server.
 503       </para>
 504     </listitem>
 505   </varlistentry>
 506   <varlistentry>
 507     <term>
 508       <emphasis remap='I'>screen_number</emphasis>
 509     </term>
 510     <listitem>
 511       <para>
 512 Specifies the appropriate screen number on the host server.
 513     </para>
 514   </listitem>
 515   </varlistentry>
 516 </variablelist>
 517 <para>
 518 <!-- .LP -->
 519 <!-- .eM -->
 520 <indexterm significance="preferred"><primary>DefaultColormap</primary></indexterm>
 521 <indexterm significance="preferred"><primary>XDefaultColormap</primary></indexterm>
 522 Both return the default colormap ID for allocation on the specified screen.
 523 Most routine allocations of color should be made out of this colormap.
 524 </para>
 525 <para>
 526 <!-- .LP -->
 527 <!-- .sp -->
 528 <!-- .sM -->
 529 </para>
 530 <para>
 531 DefaultDepth(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
 532 </para>
 533 <funcsynopsis id='XDefaultDepth'>
 534 <funcprototype>
 535   <funcdef>int <function>XDefaultDepth</function></funcdef>
 536   <paramdef>Display<parameter> *display</parameter></paramdef>
 537   <paramdef>int<parameter> screen_number</parameter></paramdef>
 538 </funcprototype>
 539 </funcsynopsis>
 540 <!-- .FN -->
 541 <variablelist>
 542   <varlistentry>
 543     <term>
 544       <emphasis remap='I'>display</emphasis>
 545     </term>
 546     <listitem>
 547       <para>
 548 Specifies the connection to the X server.
 549       </para>
 550     </listitem>
 551   </varlistentry>
 552   <varlistentry>
 553     <term>
 554       <emphasis remap='I'>screen_number</emphasis>
 555     </term>
 556     <listitem>
 557       <para>
 558 Specifies the appropriate screen number on the host server.
 559     </para>
 560   </listitem>
 561   </varlistentry>
 562 </variablelist>
 563 <para>
 564 <!-- .LP -->
 565 <!-- .eM -->
 566 <indexterm significance="preferred"><primary>DefaultDepth</primary></indexterm>
 567 <indexterm significance="preferred"><primary>XDefaultDepth</primary></indexterm>
 568 Both return the depth (number of planes) of the default root window for the
 569 specified screen.
 570 Other depths may also be supported on this screen (see
 571 <xref linkend='XMatchVisualInfo' xrefstyle='select: title'/>).
 572 </para>
 573 <para>
 574 <!-- .LP -->
 575 <!-- .sp -->
 576 <indexterm significance="preferred"><primary>XListDepths</primary></indexterm>
 577 To determine the number of depths that are available on a given screen, use
 578 <function>XListDepths</function>.
 579 <!-- .sM -->
 580 </para>
 581 <para>
 582 DefaultGC(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
 583 </para>
 584 <funcsynopsis id='XDefaultGC'>
 585 <funcprototype>
 586   <funcdef>GC <function>XDefaultGC</function></funcdef>
 587   <paramdef>Display<parameter> *display</parameter></paramdef>
 588   <paramdef>int<parameter> screen_number</parameter></paramdef>
 589   <paramdef>int<parameter> *count_return</parameter></paramdef>
 590 </funcprototype>
 591 </funcsynopsis>
 592 <!-- .FN -->
 593 <variablelist>
 594   <varlistentry>
 595     <term>
 596       <emphasis remap='I'>display</emphasis>
 597     </term>
 598     <listitem>
 599       <para>
 600 Specifies the connection to the X server.
 601       </para>
 602     </listitem>
 603   </varlistentry>
 604   <varlistentry>
 605     <term>
 606       <emphasis remap='I'>screen_number</emphasis>
 607     </term>
 608     <listitem>
 609       <para>
 610 Specifies the appropriate screen number on the host server.
 611 <!-- .ds Cn depths -->
 612       </para>
 613     </listitem>
 614   </varlistentry>
 615   <varlistentry>
 616     <term>
 617       <emphasis remap='I'>count_return</emphasis>
 618     </term>
 619     <listitem>
 620       <para>
 621 Returns the number of (Cn.
 622     </para>
 623   </listitem>
 624   </varlistentry>
 625 </variablelist>
 626 <para>
 627 <!-- .LP -->
 628 <!-- .eM -->
 629 The
 630 <function>XListDepths</function>
 631 function returns the array of depths
 632 that are available on the specified screen.
 633 If the specified screen_number is valid and sufficient memory for the array
 634 can be allocated,
 635 <function>XListDepths</function>
 636 sets count_return to the number of available depths.
 637 Otherwise, it does not set count_return and returns NULL.
 638 To release the memory allocated for the array of depths, use
 639 <xref linkend='XFree' xrefstyle='select: title'/>.
 640 </para>
 641 <para>
 642 <!-- .LP -->
 643 <!-- .sp -->
 644 <!-- .sM -->
 645 </para>
 646 <para>
 647 DefaultGC(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
 648 </para>
 649 <funcsynopsis>
 650 <funcprototype>
 651   <funcdef>GC <function>XDefaultGC</function></funcdef>
 652   <paramdef>Display<parameter> *display</parameter></paramdef>
 653   <paramdef>int<parameter> screen_number</parameter></paramdef>
 654 </funcprototype>
 655 </funcsynopsis>
 656 <!-- .FN -->
 657 <variablelist>
 658   <varlistentry>
 659     <term>
 660       <emphasis remap='I'>display</emphasis>
 661     </term>
 662     <listitem>
 663       <para>
 664 Specifies the connection to the X server.
 665       </para>
 666     </listitem>
 667   </varlistentry>
 668   <varlistentry>
 669     <term>
 670       <emphasis remap='I'>screen_number</emphasis>
 671     </term>
 672     <listitem>
 673       <para>
 674 Specifies the appropriate screen number on the host server.
 675     </para>
 676   </listitem>
 677   </varlistentry>
 678 </variablelist>
 679 <para>
 680 <!-- .LP -->
 681 <!-- .eM -->
 682 <indexterm significance="preferred"><primary>DefaultGC</primary></indexterm>
 683 <indexterm significance="preferred"><primary>XDefaultGC</primary></indexterm>
 684 Both return the default graphics context for the root window of the
 685 specified screen.
 686 This GC is created for the convenience of simple applications
 687 and contains the default GC components with the foreground and
 688 background pixel values initialized to the black and white
 689 pixels for the screen, respectively.
 690 You can modify its contents freely because it is not used in any Xlib
 691 function.
 692 This GC should never be freed.
 693 </para>
 694 <para>
 695 <!-- .LP -->
 696 <!-- .sp -->
 697 <!-- .sM -->
 698 </para>
 699 <para>
 700 DefaultRootWindow(<emphasis remap='I'>display</emphasis>)
 701 </para>
 702 <funcsynopsis id='XDefaultRootWindow'>
 703 <funcprototype>
 704   <funcdef>Window <function>XDefaultRootWindow</function></funcdef>
 705   <paramdef>Display<parameter> *display</parameter></paramdef>
 706 </funcprototype>
 707 </funcsynopsis>
 708 <!-- .FN -->
 709 <variablelist>
 710   <varlistentry>
 711     <term>
 712       <emphasis remap='I'>display</emphasis>
 713     </term>
 714     <listitem>
 715       <para>
 716 Specifies the connection to the X server.
 717     </para>
 718   </listitem>
 719   </varlistentry>
 720 </variablelist>
 721 <para>
 722 <!-- .LP -->
 723 <!-- .eM -->
 724 <indexterm significance="preferred"><primary>DefaultRootWindow</primary></indexterm>
 725 <indexterm significance="preferred"><primary>XDefaultRootWindow</primary></indexterm>
 726 Both return the root window for the default screen.
 727 </para>
 728 <para>
 729 <!-- .LP -->
 730 <!-- .sp -->
 731 <!-- .sM -->
 732 </para>
 733 <para>
 734 DefaultScreenOfDisplay(<emphasis remap='I'>display</emphasis>)
 735 </para>
 736 <funcsynopsis id='XDefaultScreenOfDisplay'>
 737 <funcprototype>
 738   <funcdef>Screen *<function>XDefaultScreenOfDisplay</function></funcdef>
 739   <paramdef>Display<parameter> *display</parameter></paramdef>
 740 </funcprototype>
 741 </funcsynopsis>
 742 <!-- .FN -->
 743 <variablelist>
 744   <varlistentry>
 745     <term>
 746       <emphasis remap='I'>display</emphasis>
 747     </term>
 748     <listitem>
 749       <para>
 750 Specifies the connection to the X server.
 751     </para>
 752   </listitem>
 753   </varlistentry>
 754 </variablelist>
 755 <para>
 756 <!-- .LP -->
 757 <!-- .eM -->
 758 <indexterm significance="preferred"><primary>DefaultScreenOfDisplay</primary></indexterm>
 759 <indexterm significance="preferred"><primary>XDefaultScreenOfDisplay</primary></indexterm>
 760 Both return a pointer to the default screen.
 761 </para>
 762 <para>
 763 <!-- .LP -->
 764 <!-- .sp -->
 765 <!-- .sM -->
 766 </para>
 767 <para>
 768 ScreenOfDisplay(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
 769 </para>
 770 <funcsynopsis id='XScreenOfDisplay'>
 771 <funcprototype>
 772   <funcdef>Screen *<function>XScreenOfDisplay</function></funcdef>
 773   <paramdef>Display<parameter> *display</parameter></paramdef>
 774   <paramdef>int<parameter> screen_number</parameter></paramdef>
 775 </funcprototype>
 776 </funcsynopsis>
 777 <!-- .FN -->
 778 <variablelist>
 779   <varlistentry>
 780     <term>
 781       <emphasis remap='I'>display</emphasis>
 782     </term>
 783     <listitem>
 784       <para>
 785 Specifies the connection to the X server.
 786       </para>
 787     </listitem>
 788   </varlistentry>
 789   <varlistentry>
 790     <term>
 791       <emphasis remap='I'>screen_number</emphasis>
 792     </term>
 793     <listitem>
 794       <para>
 795 Specifies the appropriate screen number on the host server.
 796     </para>
 797   </listitem>
 798   </varlistentry>
 799 </variablelist>
 800 <para>
 801 <!-- .LP -->
 802 <!-- .eM -->
 803 <indexterm significance="preferred"><primary>ScreenOfDisplay</primary></indexterm>
 804 <indexterm significance="preferred"><primary>XScreenOfDisplay</primary></indexterm>
 805 Both return a pointer to the indicated screen.
 806 </para>
 807 <para>
 808 <!-- .LP -->
 809 <!-- .sp -->
 810 <!-- .sM -->
 811 </para>
 812 <para>
 813 DefaultScreen(<emphasis remap='I'>display</emphasis>)
 814 </para>
 815 <funcsynopsis id='XDefaultScreen'>
 816 <funcprototype>
 817   <funcdef>int <function>XDefaultScreen</function></funcdef>
 818   <paramdef>Display<parameter> *display</parameter></paramdef>
 819 </funcprototype>
 820 </funcsynopsis>
 821 <!-- .FN -->
 822 <variablelist>
 823   <varlistentry>
 824     <term>
 825       <emphasis remap='I'>display</emphasis>
 826     </term>
 827     <listitem>
 828       <para>
 829 Specifies the connection to the X server.
 830     </para>
 831   </listitem>
 832   </varlistentry>
 833 </variablelist>
 834 <para>
 835 <!-- .LP -->
 836 <!-- .eM -->
 837 <indexterm significance="preferred"><primary>DefaultScreen</primary></indexterm>
 838 <indexterm significance="preferred"><primary>XDefaultScreen</primary></indexterm>
 839 Both return the default screen number referenced by the
 840 <xref linkend='XOpenDisplay' xrefstyle='select: title'/>
 841 function.
 842 This macro or function should be used to retrieve the screen number
 843 in applications that will use only a single screen.
 844 </para>
 845 <para>
 846 <!-- .LP -->
 847 <!-- .sp -->
 848 <!-- .sM -->
 849 </para>
 850 <para>
 851 DefaultVisual(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
 852 </para>
 853 <funcsynopsis id='XDefaultVisual'>
 854 <funcprototype>
 855   <funcdef>Visual *<function>XDefaultVisual</function></funcdef>
 856   <paramdef>Display<parameter> *display</parameter></paramdef>
 857   <paramdef>int<parameter> screen_number</parameter></paramdef>
 858 </funcprototype>
 859 </funcsynopsis>
 860 <!-- .FN -->
 861 <variablelist>
 862   <varlistentry>
 863     <term>
 864       <emphasis remap='I'>display</emphasis>
 865     </term>
 866     <listitem>
 867       <para>
 868 Specifies the connection to the X server.
 869       </para>
 870     </listitem>
 871   </varlistentry>
 872   <varlistentry>
 873     <term>
 874       <emphasis remap='I'>screen_number</emphasis>
 875     </term>
 876     <listitem>
 877       <para>
 878 Specifies the appropriate screen number on the host server.
 879     </para>
 880   </listitem>
 881   </varlistentry>
 882 </variablelist>
 883 <para>
 884 <!-- .LP -->
 885 <!-- .eM -->
 886 <indexterm significance="preferred"><primary>DefaultVisual</primary></indexterm>
 887 <indexterm significance="preferred"><primary>XDefaultVisual</primary></indexterm>
 888 Both return the default visual type for the specified screen.
 889 For further information about visual types,
 890 see <link linkend="Visual_Types">section 3.1</link>.
 891 </para>
 892 <para>
 893 <!-- .LP -->
 894 <!-- .sp -->
 895 <!-- .sM -->
 896 </para>
 897 <para>
 898 DisplayCells(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
 899 </para>
 900 <funcsynopsis id='XDisplayCells'>
 901 <funcprototype>
 902   <funcdef>int <function>XDisplayCells</function></funcdef>
 903   <paramdef>Display<parameter> *display</parameter></paramdef>
 904   <paramdef>int<parameter> screen_number</parameter></paramdef>
 905 </funcprototype>
 906 </funcsynopsis>
 907 <!-- .FN -->
 908 <variablelist>
 909   <varlistentry>
 910     <term>
 911       <emphasis remap='I'>display</emphasis>
 912     </term>
 913     <listitem>
 914       <para>
 915 Specifies the connection to the X server.
 916       </para>
 917     </listitem>
 918   </varlistentry>
 919   <varlistentry>
 920     <term>
 921       <emphasis remap='I'>screen_number</emphasis>
 922     </term>
 923     <listitem>
 924       <para>
 925 Specifies the appropriate screen number on the host server.
 926     </para>
 927   </listitem>
 928   </varlistentry>
 929 </variablelist>
 930 <para>
 931 <!-- .LP -->
 932 <!-- .eM -->
 933 <indexterm significance="preferred"><primary>DisplayCells</primary></indexterm>
 934 <indexterm significance="preferred"><primary>XDisplayCells</primary></indexterm>
 935 Both return the number of entries in the default colormap.
 936 </para>
 937 <para>
 938 <!-- .LP -->
 939 <!-- .sp -->
 940 <!-- .sM -->
 941 </para>
 942 <para>
 943 DisplayPlanes(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
 944 </para>
 945 <funcsynopsis id='XDisplayPlanes'>
 946 <funcprototype>
 947   <funcdef>int <function>XDisplayPlanes</function></funcdef>
 948   <paramdef>Display<parameter> *display</parameter></paramdef>
 949   <paramdef>int<parameter> screen_number</parameter></paramdef>
 950 </funcprototype>
 951 </funcsynopsis>
 952 <!-- .FN -->
 953 <variablelist>
 954   <varlistentry>
 955     <term>
 956       <emphasis remap='I'>display</emphasis>
 957     </term>
 958     <listitem>
 959       <para>
 960 Specifies the connection to the X server.
 961       </para>
 962     </listitem>
 963   </varlistentry>
 964   <varlistentry>
 965     <term>
 966       <emphasis remap='I'>screen_number</emphasis>
 967     </term>
 968     <listitem>
 969       <para>
 970 Specifies the appropriate screen number on the host server.
 971     </para>
 972   </listitem>
 973   </varlistentry>
 974 </variablelist>
 975 <para>
 976 <!-- .LP -->
 977 <!-- .eM -->
 978 <indexterm significance="preferred"><primary>DisplayPlanes</primary></indexterm>
 979 <indexterm significance="preferred"><primary>XDisplayPlanes</primary></indexterm>
 980 Both return the depth of the root window of the specified screen.
 981 For an explanation of depth,
 982 see the glossary.
 983 </para>
 984 <para>
 985 <!-- .LP -->
 986 <!-- .sp -->
 987 <!-- .sM -->
 988 </para>
 989 <para>
 990 DisplayString(<emphasis remap='I'>display</emphasis>)
 991 </para>
 992 <funcsynopsis id='XDisplayString'>
 993 <funcprototype>
 994   <funcdef>char *<function>XDisplayString</function></funcdef>
 995   <paramdef>Display<parameter> *display</parameter></paramdef>
 996 </funcprototype>
 997 </funcsynopsis>
 998 <!-- .FN -->
 999 <variablelist>
1000   <varlistentry>
1001     <term>
1002       <emphasis remap='I'>display</emphasis>
1003     </term>
1004     <listitem>
1005       <para>
1006 Specifies the connection to the X server.
1007     </para>
1008   </listitem>
1009   </varlistentry>
1010 </variablelist>
1011 <para>
1012 <!-- .LP -->
1013 <!-- .eM -->
1014 <indexterm significance="preferred"><primary>DisplayString</primary></indexterm>
1015 <indexterm significance="preferred"><primary>XDisplayString</primary></indexterm>
1016 Both return the string that was passed to
1017 <xref linkend='XOpenDisplay' xrefstyle='select: title'/>
1018 when the current display was opened.
1019 On <acronym>POSIX</acronym>-conformant systems,
1020 if the passed string was NULL, these return the value of
1021 the DISPLAY environment variable when the current display was opened.
1022 <indexterm><primary><acronym>POSIX</acronym> System Call</primary><secondary>fork</secondary></indexterm>
1023 These are useful to applications that invoke the
1024 <function>fork</function>
1025 system call and want to open a new connection to the same display from the
1026 child process as well as for printing error messages.
1027 </para>
1028 <para>
1029 <!-- .LP -->
1030 <!-- .sp -->
1031 <!-- .sM -->
1032 </para>
1033 <para>
1034 LastKnownRequestProcessed(<emphasis remap='I'>display</emphasis>)
1035 </para>
1036 <funcsynopsis id='XLastKnownRequestProcessed'>
1037 <funcprototype>
1038   <funcdef>unsigned long <function>XLastKnownRequestProcessed</function></funcdef>
1039   <paramdef>Display<parameter> *display</parameter></paramdef>
1040 </funcprototype>
1041 </funcsynopsis>
1042 <!-- .FN -->
1043 <variablelist>
1044   <varlistentry>
1045     <term>
1046       <emphasis remap='I'>display</emphasis>
1047     </term>
1048     <listitem>
1049       <para>
1050 Specifies the connection to the X server.
1051     </para>
1052   </listitem>
1053   </varlistentry>
1054 </variablelist>
1055 <para>
1056 <!-- .LP -->
1057 <!-- .eM -->
1058 <indexterm significance="preferred"><primary>XExtendedMaxRequestSize</primary></indexterm>
1059 The
1060 <olink targetdoc='bigreq' targetptr='XExtendedMaxRequestSize'><function>XExtendedMaxRequestSize</function></olink>
1061 function returns zero if the specified display does not support an
1062 extended-length protocol encoding; otherwise,
1063 it returns the maximum request size (in 4-byte units) supported
1064 by the server using the extended-length encoding.
1065 The Xlib functions
1066 <xref linkend='XDrawLines' xrefstyle='select: title'/>,
1067 <xref linkend='XDrawArcs' xrefstyle='select: title'/>,
1068 <xref linkend='XFillPolygon' xrefstyle='select: title'/>,
1069 <xref linkend='XChangeProperty' xrefstyle='select: title'/>,
1070 <xref linkend='XSetClipRectangles' xrefstyle='select: title'/>,
1071 and
1072 <xref linkend='XSetRegion' xrefstyle='select: title'/>
1073 will use the extended-length encoding as necessary, if supported
1074 by the server.  Use of the extended-length encoding in other Xlib
1075 functions (for example,
1076 <xref linkend='XDrawPoints' xrefstyle='select: title'/>,
1077 <xref linkend='XDrawRectangles' xrefstyle='select: title'/>,
1078 <xref linkend='XDrawSegments' xrefstyle='select: title'/>,
1079 <xref linkend='XFillArcs' xrefstyle='select: title'/>,
1080 <xref linkend='XFillRectangles' xrefstyle='select: title'/>,
1081 <xref linkend='XPutImage' xrefstyle='select: title'/>)
1082 is permitted but not required; an Xlib implementation may choose to
1083 split the data across multiple smaller requests instead.
1084 </para>
1085 <para>
1086 <!-- .LP -->
1087 <!-- .sp -->
1088 <!-- .sM -->
1089 </para>
1090 <para>
1091 LastKnownRequestProcessed(<emphasis remap='I'>display</emphasis>)
1092 </para>
1093 <funcsynopsis>
1094 <funcprototype>
1095   <funcdef>unsigned long <function>XLastKnownRequestProcessed</function></funcdef>
1096   <paramdef>Display<parameter> *display</parameter></paramdef>
1097 </funcprototype>
1098 </funcsynopsis>
1099 <!-- .FN -->
1100 <variablelist>
1101   <varlistentry>
1102     <term>
1103       <emphasis remap='I'>display</emphasis>
1104     </term>
1105     <listitem>
1106       <para>
1107 Specifies the connection to the X server.
1108     </para>
1109   </listitem>
1110   </varlistentry>
1111 </variablelist>
1112 <para>
1113 <!-- .LP -->
1114 <!-- .eM -->
1115 <indexterm significance="preferred"><primary>XMaxRequestSize</primary></indexterm>
1116 The
1117 <function>XMaxRequestSize</function>
1118 function returns the maximum request size (in 4-byte units) supported
1119 by the server without using an extended-length protocol encoding.
1120 Single protocol requests to the server can be no larger than this size
1121 unless an extended-length protocol encoding is supported by the server.
1122 The protocol guarantees the size to be no smaller than 4096 units
1123 (16384 bytes).
1124 Xlib automatically breaks data up into multiple protocol requests
1125 as necessary for the following functions:
1126 <xref linkend='XDrawPoints' xrefstyle='select: title'/>,
1127 <xref linkend='XDrawRectangles' xrefstyle='select: title'/>,
1128 <xref linkend='XDrawSegments' xrefstyle='select: title'/>,
1129 <xref linkend='XFillArcs' xrefstyle='select: title'/>,
1130 <xref linkend='XFillRectangles' xrefstyle='select: title'/>,
1131 and
1132 <xref linkend='XPutImage' xrefstyle='select: title'/>.
1133 </para>
1134 <para>
1135 <!-- .LP -->
1136 <!-- .sp -->
1137 <!-- .sM -->
1138 </para>
1139 <para>
1140 LastKnownRequestProcessed(<emphasis remap='I'>display</emphasis>)
1141 </para>
1142 <funcsynopsis>
1143 <funcprototype>
1144   <funcdef>unsigned long <function>XLastKnownRequestProcessed</function></funcdef>
1145   <paramdef>Display<parameter> *display</parameter></paramdef>
1146 </funcprototype>
1147 </funcsynopsis>
1148 <!-- .FN -->
1149 <variablelist>
1150   <varlistentry>
1151     <term>
1152       <emphasis remap='I'>display</emphasis>
1153     </term>
1154     <listitem>
1155       <para>
1156 Specifies the connection to the X server.
1157     </para>
1158   </listitem>
1159   </varlistentry>
1160 </variablelist>
1161 <para>
1162 <!-- .LP -->
1163 <!-- .eM -->
1164 <indexterm significance="preferred"><primary>LastKnownRequestProcessed</primary></indexterm>
1165 <indexterm significance="preferred"><primary>XLastKnownRequestProcessed</primary></indexterm>
1166 Both extract the full serial number of the last request known by Xlib
1167 to have been processed by the X server.
1168 Xlib automatically sets this number when replies, events, and errors
1169 are received.
1170 </para>
1171 <para>
1172 <!-- .LP -->
1173 <!-- .sp -->
1174 <!-- .sM -->
1175 </para>
1176 <para>
1177 NextRequest(<emphasis remap='I'>display</emphasis>)
1178 </para>
1179 <funcsynopsis id='XNextRequest'>
1180 <funcprototype>
1181   <funcdef>unsigned long <function>XNextRequest</function></funcdef>
1182   <paramdef>Display<parameter> *display</parameter></paramdef>
1183 </funcprototype>
1184 </funcsynopsis>
1185 <!-- .FN -->
1186 <variablelist>
1187   <varlistentry>
1188     <term>
1189       <emphasis remap='I'>display</emphasis>
1190     </term>
1191     <listitem>
1192       <para>
1193 Specifies the connection to the X server.
1194     </para>
1195   </listitem>
1196   </varlistentry>
1197 </variablelist>
1198 <para>
1199 <!-- .LP -->
1200 <!-- .eM -->
1201 <indexterm significance="preferred"><primary>NextRequest</primary></indexterm>
1202 <indexterm significance="preferred"><primary>XNextRequest</primary></indexterm>
1203 Both extract the full serial number that is to be used for the next
1204 request.
1205 Serial numbers are maintained separately for each display connection.
1206 </para>
1207 <para>
1208 <!-- .LP -->
1209 <!-- .sp -->
1210 <!-- .sM -->
1211 </para>
1212 <para>
1213 ProtocolVersion(<emphasis remap='I'>display</emphasis>)
1214 </para>
1215 <funcsynopsis id='XProtocolVersion'>
1216 <funcprototype>
1217   <funcdef>int <function>XProtocolVersion</function></funcdef>
1218   <paramdef>Display<parameter> *display</parameter></paramdef>
1219 </funcprototype>
1220 </funcsynopsis>
1221 <!-- .FN -->
1222 <variablelist>
1223   <varlistentry>
1224     <term>
1225       <emphasis remap='I'>display</emphasis>
1226     </term>
1227     <listitem>
1228       <para>
1229 Specifies the connection to the X server.
1230     </para>
1231   </listitem>
1232   </varlistentry>
1233 </variablelist>
1234 <para>
1235 <!-- .LP -->
1236 <!-- .eM -->
1237 <indexterm significance="preferred"><primary>ProtocolVersion</primary></indexterm>
1238 <indexterm significance="preferred"><primary>XProtocolVersion</primary></indexterm>
1239 Both return the major version number (11) of the X protocol associated with
1240 the connected display.
1241 </para>
1242 <para>
1243 <!-- .LP -->
1244 <!-- .sp -->
1245 <!-- .sM -->
1246 </para>
1247 <para>
1248 ProtocolRevision(<emphasis remap='I'>display</emphasis>)
1249 </para>
1250 <funcsynopsis id='XProtocolRevision'>
1251 <funcprototype>
1252   <funcdef>int <function>XProtocolRevision</function></funcdef>
1253   <paramdef>Display<parameter> *display</parameter></paramdef>
1254 </funcprototype>
1255 </funcsynopsis>
1256 <!-- .FN -->
1257 <variablelist>
1258   <varlistentry>
1259     <term>
1260       <emphasis remap='I'>display</emphasis>
1261     </term>
1262     <listitem>
1263       <para>
1264 Specifies the connection to the X server.
1265     </para>
1266   </listitem>
1267   </varlistentry>
1268 </variablelist>
1269 <para>
1270 <!-- .LP -->
1271 <!-- .eM -->
1272 <indexterm significance="preferred"><primary>ProtocolRevision</primary></indexterm>
1273 <indexterm significance="preferred"><primary>XProtocolRevision</primary></indexterm>
1274 Both return the minor protocol revision number of the X server.
1275 </para>
1276 <para>
1277 <!-- .LP -->
1278 <!-- .sp -->
1279 <!-- .sM -->
1280 </para>
1281 <para>
1282 QLength(<emphasis remap='I'>display</emphasis>)
1283 </para>
1284 <funcsynopsis id='XQLength'>
1285 <funcprototype>
1286   <funcdef>int <function>XQLength</function></funcdef>
1287   <paramdef>Display<parameter> *display</parameter></paramdef>
1288 </funcprototype>
1289 </funcsynopsis>
1290 <!-- .FN -->
1291 <variablelist>
1292   <varlistentry>
1293     <term>
1294       <emphasis remap='I'>display</emphasis>
1295     </term>
1296     <listitem>
1297       <para>
1298 Specifies the connection to the X server.
1299     </para>
1300   </listitem>
1301   </varlistentry>
1302 </variablelist>
1303 <para>
1304 <!-- .LP -->
1305 <!-- .eM -->
1306 <indexterm significance="preferred"><primary>QLength</primary></indexterm>
1307 <indexterm significance="preferred"><primary>XQLength</primary></indexterm>
1308 Both return the length of the event queue for the connected display.
1309 Note that there may be more events that have not been read into
1310 the queue yet (see
1311 <xref linkend='XEventsQueued' xrefstyle='select: title'/>).
1312 </para>
1313 <para>
1314 <!-- .LP -->
1315 <!-- .sp -->
1316 <!-- .sM -->
1317 </para>
1318 <para>
1319 RootWindow(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
1320 </para>
1321 <funcsynopsis id='XRootWindow'>
1322 <funcprototype>
1323   <funcdef>Window <function>XRootWindow</function></funcdef>
1324   <paramdef>Display<parameter> *display</parameter></paramdef>
1325   <paramdef>int<parameter> screen_number</parameter></paramdef>
1326 </funcprototype>
1327 </funcsynopsis>
1328 <!-- .FN -->
1329 <variablelist>
1330   <varlistentry>
1331     <term>
1332       <emphasis remap='I'>display</emphasis>
1333     </term>
1334     <listitem>
1335       <para>
1336 Specifies the connection to the X server.
1337       </para>
1338     </listitem>
1339   </varlistentry>
1340   <varlistentry>
1341     <term>
1342       <emphasis remap='I'>screen_number</emphasis>
1343     </term>
1344     <listitem>
1345       <para>
1346 Specifies the appropriate screen number on the host server.
1347     </para>
1348   </listitem>
1349   </varlistentry>
1350 </variablelist>
1351 <para>
1352 <!-- .LP -->
1353 <!-- .eM -->
1354 <indexterm><primary>Window</primary><secondary>RootWindow</secondary></indexterm>
1355 <indexterm significance="preferred"><primary>RootWindow</primary></indexterm>
1356 <indexterm><primary>Window</primary><secondary>XRootWindow</secondary></indexterm>
1357 <indexterm significance="preferred"><primary>XRootWindow</primary></indexterm>
1358 Both return the root window.
1359 These are useful with functions that need a drawable of a particular screen
1360 and for creating top-level windows.
1361 </para>
1362 <para>
1363 <!-- .LP -->
1364 <!-- .sp -->
1365 <!-- .sM -->
1366 </para>
1367 <para>
1368 ScreenCount(<emphasis remap='I'>display</emphasis>)
1369 </para>
1370 <funcsynopsis id='XScreenCount'>
1371 <funcprototype>
1372   <funcdef>int <function>XScreenCount</function></funcdef>
1373   <paramdef>Display<parameter> *display</parameter></paramdef>
1374 </funcprototype>
1375 </funcsynopsis>
1376 <!-- .FN -->
1377 <variablelist>
1378   <varlistentry>
1379     <term>
1380       <emphasis remap='I'>display</emphasis>
1381     </term>
1382     <listitem>
1383       <para>
1384 Specifies the connection to the X server.
1385     </para>
1386   </listitem>
1387   </varlistentry>
1388 </variablelist>
1389 <para>
1390 <!-- .LP -->
1391 <!-- .eM -->
1392 <indexterm significance="preferred"><primary>ScreenCount</primary></indexterm>
1393 <indexterm significance="preferred"><primary>XScreenCount</primary></indexterm>
1394 Both return the number of available screens.
1395 </para>
1396 <para>
1397 <!-- .LP -->
1398 <!-- .sp -->
1399 <!-- .sM -->
1400 </para>
1401 <para>
1402 ServerVendor(<emphasis remap='I'>display</emphasis>)
1403 </para>
1404 <funcsynopsis id='XServerVendor'>
1405 <funcprototype>
1406   <funcdef>char *<function>XServerVendor</function></funcdef>
1407   <paramdef>Display<parameter> *display</parameter></paramdef>
1408 </funcprototype>
1409 </funcsynopsis>
1410 <!-- .FN -->
1411 <variablelist>
1412   <varlistentry>
1413     <term>
1414       <emphasis remap='I'>display</emphasis>
1415     </term>
1416     <listitem>
1417       <para>
1418 Specifies the connection to the X server.
1419     </para>
1420   </listitem>
1421   </varlistentry>
1422 </variablelist>
1423 <para>
1424 <!-- .LP -->
1425 <!-- .eM -->
1426 <indexterm significance="preferred"><primary>ServerVendor</primary></indexterm>
1427 <indexterm significance="preferred"><primary>XServerVendor</primary></indexterm>
1428 Both return a pointer to a null-terminated string that provides
1429 some identification of the owner of the X server implementation.
1430 If the data returned by the server is in the Latin Portable Character Encoding,
1431 then the string is in the Host Portable Character Encoding.
1432 Otherwise, the contents of the string are implementation-dependent.
1433 </para>
1434 <para>
1435 <!-- .LP -->
1436 <!-- .sp -->
1437 <!-- .sM -->
1438 </para>
1439 <para>
1440 VendorRelease(<emphasis remap='I'>display</emphasis>)
1441 </para>
1442 <funcsynopsis id='XVendorRelease'>
1443 <funcprototype>
1444   <funcdef>int <function>XVendorRelease</function></funcdef>
1445   <paramdef>Display<parameter> *display</parameter></paramdef>
1446 </funcprototype>
1447 </funcsynopsis>
1448 <!-- .FN -->
1449 <variablelist>
1450   <varlistentry>
1451     <term>
1452       <emphasis remap='I'>display</emphasis>
1453     </term>
1454     <listitem>
1455       <para>
1456 Specifies the connection to the X server.
1457     </para>
1458   </listitem>
1459   </varlistentry>
1460 </variablelist>
1461 <para>
1462 <!-- .LP -->
1463 <!-- .eM -->
1464 <indexterm significance="preferred"><primary>VendorRelease</primary></indexterm>
1465 <indexterm significance="preferred"><primary>XVendorRelease</primary></indexterm>
1466 Both return a number related to a vendor's release of the X server.
1467 </para>
1468 </sect2>
1469 <sect2 id="Image_Format_Functions_and_Macros">
1470 <title>Image Format Functions and Macros</title>
1471 <!-- .XS -->
1472 <!-- (SN Image Format Functions and Macros -->
1473 <!-- .XE -->
1474 <para>
1475 <!-- .LP -->
1476 Applications are required to present data to the X server
1477 in a format that the server demands.
1478 To help simplify applications,
1479 most of the work required to convert the data is provided by Xlib
1480 (see sections
1481 <link linkend="Transferring_Images_between_Client_and_Server">8.7</link> and
1482 <link linkend="Manipulating_Images">16.8</link>).
1483 </para>
1484 <para>
1485 <!-- .LP -->
1486 The
1487 <structname>XPixmapFormatValues</structname>
1488 structure provides an interface to the pixmap format information
1489 that is returned at the time of a connection setup.
1490 It contains:
1491 </para>
1492 <para>
1493 <!-- .LP -->
1494 <!-- .sM -->
1495 <literallayout class="monospaced">
1496 <!-- .TA .5i 3i -->
1497 <!-- .ta .5i 3i -->
1498 typedef struct {
1499         int depth;
1500         int bits_per_pixel;
1501         int scanline_pad;
1502 } XPixmapFormatValues;
1503 </literallayout>
1504 </para>
1505 <para>
1506 <!-- .LP -->
1507 <!-- .eM -->
1508 <!-- .sp -->
1509 To obtain the pixmap format information for a given display, use
1510 <function>XListPixmapFormats</function>.
1511 <indexterm significance="preferred"><primary>XListPixmapFormats</primary></indexterm>
1512 <!-- .sM -->
1513 </para>
1514 <para>
1515 ImageByteOrder(<emphasis remap='I'>display</emphasis>)
1516 </para>
1517 <funcsynopsis id='XImageByteOrder'>
1518 <funcprototype>
1519   <funcdef>int <function>XImageByteOrder</function></funcdef>
1520   <paramdef>Display<parameter> *display</parameter></paramdef>
1521   <paramdef>int<parameter> *count_return</parameter></paramdef>
1522 </funcprototype>
1523 </funcsynopsis>
1524 <!-- .FN -->
1525 <variablelist>
1526   <varlistentry>
1527     <term>
1528       <emphasis remap='I'>display</emphasis>
1529     </term>
1530     <listitem>
1531       <para>
1532 Specifies the connection to the X server.
1533 <!-- .ds Cn pixmap formats that are supported by the display -->
1534       </para>
1535     </listitem>
1536   </varlistentry>
1537   <varlistentry>
1538     <term>
1539       <emphasis remap='I'>count_return</emphasis>
1540     </term>
1541     <listitem>
1542       <para>
1543 Returns the number of (Cn.
1544     </para>
1545   </listitem>
1546   </varlistentry>
1547 </variablelist>
1548 <para>
1549 <!-- .LP -->
1550 <!-- .eM -->
1551 The
1552 <function>XListPixmapFormats</function>
1553 function returns an array of
1554 <structname>XPixmapFormatValues</structname>
1555 structures that describe the types of Z format images supported
1556 by the specified display.
1557 If insufficient memory is available,
1558 <function>XListPixmapFormats</function>
1559 returns NULL.
1560 To free the allocated storage for the
1561 <structname>XPixmapFormatValues</structname>
1562 structures, use
1563 <xref linkend='XFree' xrefstyle='select: title'/>.
1564 </para>
1565 <para>
1566 <!-- .LP  -->
1567 The following lists the C language macros,
1568 their corresponding function equivalents that are for other language bindings,
1569 and what data they both return for the specified server and screen.
1570 These are often used by toolkits as well as by simple applications.
1571 </para>
1572 <para>
1573 <!-- .LP -->
1574 <!-- .sp -->
1575 <!-- .sM -->
1576 </para>
1577 <para>
1578 ImageByteOrder(<emphasis remap='I'>display</emphasis>)
1579 </para>
1580 <funcsynopsis>
1581 <funcprototype>
1582   <funcdef>int <function>XImageByteOrder</function></funcdef>
1583   <paramdef>Display<parameter> *display</parameter></paramdef>
1584 </funcprototype>
1585 </funcsynopsis>
1586 <!-- .FN -->
1587 <variablelist>
1588   <varlistentry>
1589     <term>
1590       <emphasis remap='I'>display</emphasis>
1591     </term>
1592     <listitem>
1593       <para>
1594 Specifies the connection to the X server.
1595     </para>
1596   </listitem>
1597   </varlistentry>
1598 </variablelist>
1599 <para>
1600 <!-- .LP -->
1601 <!-- .eM -->
1602 <indexterm significance="preferred"><primary>ImageByteOrder</primary></indexterm>
1603 <indexterm significance="preferred"><primary>XImageByteOrder</primary></indexterm>
1604 Both specify the required byte order for images for each scanline unit in
1605 XY format (bitmap) or for each pixel value in
1606 Z format.
1607 The macro or function can return either
1608 <symbol>LSBFirst</symbol>
1609 or
1610 <symbol>MSBFirst</symbol>.
1611 </para>
1612 <para>
1613 <!-- .LP -->
1614 <!-- .sp -->
1615 <!-- .sM -->
1616 </para>
1617 <para>
1618 BitmapUnit(<emphasis remap='I'>display</emphasis>)
1619 </para>
1620 <funcsynopsis id='XBitmapUnit'>
1621 <funcprototype>
1622   <funcdef>int <function>XBitmapUnit</function></funcdef>
1623   <paramdef>Display<parameter> *display</parameter></paramdef>
1624 </funcprototype>
1625 </funcsynopsis>
1626 <!-- .FN -->
1627 <variablelist>
1628   <varlistentry>
1629     <term>
1630       <emphasis remap='I'>display</emphasis>
1631     </term>
1632     <listitem>
1633       <para>
1634 Specifies the connection to the X server.
1635     </para>
1636   </listitem>
1637   </varlistentry>
1638 </variablelist>
1639 <para>
1640 <!-- .LP -->
1641 <!-- .eM -->
1642 <indexterm significance="preferred"><primary>BitmapUnit</primary></indexterm>
1643 <indexterm significance="preferred"><primary>XBitmapUnit</primary></indexterm>
1644 Both return the size of a bitmap's scanline unit in bits.
1645 The scanline is calculated in multiples of this value.
1646 </para>
1647 <para>
1648 <!-- .LP -->
1649 <!-- .sp -->
1650 <!-- .sM -->
1651 </para>
1652 <para>
1653 BitmapBitOrder(<emphasis remap='I'>display</emphasis>)
1654 </para>
1655 <funcsynopsis id='XBitmapBitOrder'>
1656 <funcprototype>
1657   <funcdef>int <function>XBitmapBitOrder</function></funcdef>
1658   <paramdef>Display<parameter> *display</parameter></paramdef>
1659 </funcprototype>
1660 </funcsynopsis>
1661 <!-- .FN -->
1662 <variablelist>
1663   <varlistentry>
1664     <term>
1665       <emphasis remap='I'>display</emphasis>
1666     </term>
1667     <listitem>
1668       <para>
1669 Specifies the connection to the X server.
1670     </para>
1671   </listitem>
1672   </varlistentry>
1673 </variablelist>
1674 <para>
1675 <!-- .LP -->
1676 <!-- .eM -->
1677 <indexterm significance="preferred"><primary>BitmapBitOrder</primary></indexterm>
1678 <indexterm significance="preferred"><primary>XBitmapBitOrder</primary></indexterm>
1679 Within each bitmap unit, the left-most bit in the bitmap as displayed
1680 on the screen is either the least significant or most significant bit in the
1681 unit.
1682 This macro or function can return
1683 <symbol>LSBFirst</symbol>
1684 or
1685 <symbol>MSBFirst</symbol>.
1686 </para>
1687 <para>
1688 <!-- .LP -->
1689 <!-- .sp -->
1690 <!-- .sM -->
1691 </para>
1692 <para>
1693 BitmapPad(<emphasis remap='I'>display</emphasis>)
1694 </para>
1695 <funcsynopsis id='XBitmapPad'>
1696 <funcprototype>
1697   <funcdef>int <function>XBitmapPad</function></funcdef>
1698   <paramdef>Display<parameter> *display</parameter></paramdef>
1699 </funcprototype>
1700 </funcsynopsis>
1701 <!-- .FN -->
1702 <variablelist>
1703   <varlistentry>
1704     <term>
1705       <emphasis remap='I'>display</emphasis>
1706     </term>
1707     <listitem>
1708       <para>
1709 Specifies the connection to the X server.
1710     </para>
1711   </listitem>
1712   </varlistentry>
1713 </variablelist>
1714 <para>
1715 <!-- .LP -->
1716 <!-- .eM -->
1717 <indexterm significance="preferred"><primary>BitmapPad</primary></indexterm>
1718 <indexterm significance="preferred"><primary>XBitmapPad</primary></indexterm>
1719 Each scanline must be padded to a multiple of bits returned
1720 by this macro or function.
1721 </para>
1722 <para>
1723 <!-- .LP -->
1724 <!-- .sp -->
1725 <!-- .sM -->
1726 </para>
1727 <para>
1728 DisplayHeight(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
1729 </para>
1730 <funcsynopsis id='XDisplayHeight'>
1731 <funcprototype>
1732   <funcdef>int <function>XDisplayHeight</function></funcdef>
1733   <paramdef>Display<parameter> *display</parameter></paramdef>
1734   <paramdef>int<parameter> screen_number</parameter></paramdef>
1735 </funcprototype>
1736 </funcsynopsis>
1737 <!-- .FN -->
1738 <variablelist>
1739   <varlistentry>
1740     <term>
1741       <emphasis remap='I'>display</emphasis>
1742     </term>
1743     <listitem>
1744       <para>
1745 Specifies the connection to the X server.
1746       </para>
1747     </listitem>
1748   </varlistentry>
1749   <varlistentry>
1750     <term>
1751       <emphasis remap='I'>screen_number</emphasis>
1752     </term>
1753     <listitem>
1754       <para>
1755 Specifies the appropriate screen number on the host server.
1756     </para>
1757   </listitem>
1758   </varlistentry>
1759 </variablelist>
1760 <para>
1761 <!-- .LP -->
1762 <!-- .eM -->
1763 <indexterm significance="preferred"><primary>DisplayHeight</primary></indexterm>
1764 <indexterm significance="preferred"><primary>XDisplayHeight</primary></indexterm>
1765 Both return an integer that describes the height of the screen
1766 in pixels.
1767 </para>
1768 <para>
1769 <!-- .LP -->
1770 <!-- .sp -->
1771 <!-- .sM -->
1772 </para>
1773 <para>
1774 DisplayHeightMM(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
1775 </para>
1776 <funcsynopsis id='XDisplayHeightMM'>
1777 <funcprototype>
1778   <funcdef>int <function>XDisplayHeightMM</function></funcdef>
1779   <paramdef>Display<parameter> *display</parameter></paramdef>
1780   <paramdef>int<parameter> screen_number</parameter></paramdef>
1781 </funcprototype>
1782 </funcsynopsis>
1783 <!-- .FN -->
1784 <variablelist>
1785   <varlistentry>
1786     <term>
1787       <emphasis remap='I'>display</emphasis>
1788     </term>
1789     <listitem>
1790       <para>
1791 Specifies the connection to the X server.
1792       </para>
1793     </listitem>
1794   </varlistentry>
1795   <varlistentry>
1796     <term>
1797       <emphasis remap='I'>screen_number</emphasis>
1798     </term>
1799     <listitem>
1800       <para>
1801 Specifies the appropriate screen number on the host server.
1802     </para>
1803   </listitem>
1804   </varlistentry>
1805 </variablelist>
1806 <para>
1807 <!-- .LP -->
1808 <!-- .eM -->
1809 <indexterm significance="preferred"><primary>DisplayHeightMM</primary></indexterm>
1810 <indexterm significance="preferred"><primary>XDisplayHeightMM</primary></indexterm>
1811 Both return the height of the specified screen in millimeters.
1812 </para>
1813 <para>
1814 <!-- .LP -->
1815 <!-- .sp -->
1816 <!-- .sM -->
1817 </para>
1818 <para>
1819 DisplayWidth(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
1820 </para>
1821 <funcsynopsis id='XDisplayWidth'>
1822 <funcprototype>
1823   <funcdef>int <function>XDisplayWidth</function></funcdef>
1824   <paramdef>Display<parameter> *display</parameter></paramdef>
1825   <paramdef>int<parameter> screen_number</parameter></paramdef>
1826 </funcprototype>
1827 </funcsynopsis>
1828 <!-- .FN -->
1829 <variablelist>
1830   <varlistentry>
1831     <term>
1832       <emphasis remap='I'>display</emphasis>
1833     </term>
1834     <listitem>
1835       <para>
1836 Specifies the connection to the X server.
1837       </para>
1838     </listitem>
1839   </varlistentry>
1840   <varlistentry>
1841     <term>
1842       <emphasis remap='I'>screen_number</emphasis>
1843     </term>
1844     <listitem>
1845       <para>
1846 Specifies the appropriate screen number on the host server.
1847     </para>
1848   </listitem>
1849   </varlistentry>
1850 </variablelist>
1851 <para>
1852 <!-- .LP -->
1853 <!-- .eM -->
1854 <indexterm significance="preferred"><primary>DisplayWidth</primary></indexterm>
1855 <indexterm significance="preferred"><primary>XDisplayWidth</primary></indexterm>
1856 Both return the width of the screen in pixels.
1857 </para>
1858 <para>
1859 <!-- .LP -->
1860 <!-- .sp -->
1861 <!-- .sM -->
1862 </para>
1863 <para>
1864 DisplayWidthMM(<emphasis remap='I'>display</emphasis>, <emphasis remap='I'>screen_number</emphasis>)
1865 </para>
1866 <funcsynopsis id='XDisplayWidthMM'>
1867 <funcprototype>
1868   <funcdef>int <function>XDisplayWidthMM</function></funcdef>
1869   <paramdef>Display<parameter> *display</parameter></paramdef>
1870   <paramdef>int<parameter> screen_number</parameter></paramdef>
1871 </funcprototype>
1872 </funcsynopsis>
1873 <!-- .FN -->
1874 <variablelist>
1875   <varlistentry>
1876     <term>
1877       <emphasis remap='I'>display</emphasis>
1878     </term>
1879     <listitem>
1880       <para>
1881 Specifies the connection to the X server.
1882       </para>
1883     </listitem>
1884   </varlistentry>
1885   <varlistentry>
1886     <term>
1887       <emphasis remap='I'>screen_number</emphasis>
1888     </term>
1889     <listitem>
1890       <para>
1891 Specifies the appropriate screen number on the host server.
1892     </para>
1893   </listitem>
1894   </varlistentry>
1895 </variablelist>
1896 <para>
1897 <!-- .LP -->
1898 <!-- .eM -->
1899 <indexterm significance="preferred"><primary>DisplayWidthMM</primary></indexterm>
1900 <indexterm significance="preferred"><primary>XDisplayWidthMM</primary></indexterm>
1901 Both return the width of the specified screen in millimeters.
1902 </para>
1903 </sect2>
1904 <sect2 id="Screen_Information_Macros">
1905 <title>Screen Information Macros</title>
1906 <!-- .XS -->
1907 <!-- (SN Screen Information Macros -->
1908 <!-- .XE -->
1909 <para>
1910 <!-- .LP -->
1911 The following lists the C language macros,
1912 their corresponding function equivalents that are for other language bindings,
1913 and what data they both can return.
1914 These macros or functions all take a pointer to the appropriate screen
1915 structure.
1916 </para>
1917 <para>
1918 <!-- .LP -->
1919 <!-- .sp -->
1920 <!-- .sM -->
1921 </para>
1922 <para>
1923 BlackPixelOfScreen(<emphasis remap='I'>screen</emphasis>)
1924 </para>
1925 <funcsynopsis id='XBlackPixelOfScreen'>
1926 <funcprototype>
1927   <funcdef>unsigned long <function>XBlackPixelOfScreen</function></funcdef>
1928   <paramdef>Screen<parameter> *screen</parameter></paramdef>
1929 </funcprototype>
1930 </funcsynopsis>
1931 <!-- .FN -->
1932 <variablelist>
1933   <varlistentry>
1934     <term>
1935       <emphasis remap='I'>screen</emphasis>
1936     </term>
1937     <listitem>
1938       <para>
1939 Specifies the appropriate
1940 <type>Screen</type>
1941 structure.
1942     </para>
1943   </listitem>
1944   </varlistentry>
1945 </variablelist>
1946 <para>
1947 <!-- .LP -->
1948 <!-- .eM -->
1949 <indexterm significance="preferred"><primary>BlackPixelOfScreen</primary></indexterm>
1950 <indexterm significance="preferred"><primary>XBlackPixelOfScreen</primary></indexterm>
1951 Both return the black pixel value of the specified screen.
1952 </para>
1953 <para>
1954 <!-- .LP -->
1955 <!-- .sp -->
1956 <!-- .sM -->
1957 </para>
1958 <para>
1959 WhitePixelOfScreen(<emphasis remap='I'>screen</emphasis>)
1960 </para>
1961 <funcsynopsis id='XWhitePixelOfScreen'>
1962 <funcprototype>
1963   <funcdef>unsigned long <function>XWhitePixelOfScreen</function></funcdef>
1964   <paramdef>Screen<parameter> *screen</parameter></paramdef>
1965 </funcprototype>
1966 </funcsynopsis>
1967 <!-- .FN -->
1968 <variablelist>
1969   <varlistentry>
1970     <term>
1971       <emphasis remap='I'>screen</emphasis>
1972     </term>
1973     <listitem>
1974       <para>
1975 Specifies the appropriate
1976 <type>Screen</type>
1977 structure.
1978     </para>
1979   </listitem>
1980   </varlistentry>
1981 </variablelist>
1982 <para>
1983 <!-- .LP -->
1984 <!-- .eM -->
1985 <indexterm significance="preferred"><primary>WhitePixelOfScreen</primary></indexterm>
1986 <indexterm significance="preferred"><primary>XWhitePixelOfScreen</primary></indexterm>
1987 Both return the white pixel value of the specified screen.
1988 </para>
1989 <para>
1990 <!-- .LP -->
1991 <!-- .sp -->
1992 <!-- .sM -->
1993 </para>
1994 <para>
1995 CellsOfScreen(<emphasis remap='I'>screen</emphasis>)
1996 </para>
1997 <funcsynopsis id='XCellsOfScreen'>
1998 <funcprototype>
1999   <funcdef>int <function>XCellsOfScreen</function></funcdef>
2000   <paramdef>Screen<parameter> *screen</parameter></paramdef>
2001 </funcprototype>
2002 </funcsynopsis>
2003 <!-- .FN -->
2004 <variablelist>
2005   <varlistentry>
2006     <term>
2007       <emphasis remap='I'>screen</emphasis>
2008     </term>
2009     <listitem>
2010       <para>
2011 Specifies the appropriate
2012 <type>Screen</type>
2013 structure.
2014     </para>
2015   </listitem>
2016   </varlistentry>
2017 </variablelist>
2018 <para>
2019 <!-- .LP -->
2020 <!-- .eM -->
2021 <indexterm significance="preferred"><primary>CellsOfScreen</primary></indexterm>
2022 <indexterm significance="preferred"><primary>XCellsOfScreen</primary></indexterm>
2023 Both return the number of colormap cells in the default colormap
2024 of the specified screen.
2025 </para>
2026 <para>
2027 <!-- .LP -->
2028 <!-- .sp -->
2029 <!-- .sM -->
2030 </para>
2031 <para>
2032 DefaultColormapOfScreen(<emphasis remap='I'>screen</emphasis>)
2033 </para>
2034 <funcsynopsis id='XDefaultColormapOfScreen'>
2035 <funcprototype>
2036   <funcdef>Colormap <function>XDefaultColormapOfScreen</function></funcdef>
2037   <paramdef>Screen<parameter> *screen</parameter></paramdef>
2038 </funcprototype>
2039 </funcsynopsis>
2040 <!-- .FN -->
2041 <variablelist>
2042   <varlistentry>
2043     <term>
2044       <emphasis remap='I'>screen</emphasis>
2045     </term>
2046     <listitem>
2047       <para>
2048 Specifies the appropriate
2049 <type>Screen</type>
2050 structure.
2051     </para>
2052   </listitem>
2053   </varlistentry>
2054 </variablelist>
2055 <para>
2056 <!-- .LP -->
2057 <!-- .eM -->
2058 <indexterm significance="preferred"><primary>DefaultColormapOfScreen</primary></indexterm>
2059 <indexterm significance="preferred"><primary>XDefaultColormapOfScreen</primary></indexterm>
2060 Both return the default colormap of the specified screen.
2061 </para>
2062 <para>
2063 <!-- .LP -->
2064 <!-- .sp -->
2065 <!-- .sM -->
2066 </para>
2067 <para>
2068 DefaultDepthOfScreen(<emphasis remap='I'>screen</emphasis>)
2069 </para>
2070 <funcsynopsis id='XDefaultDepthOfScreen'>
2071 <funcprototype>
2072   <funcdef>int <function>XDefaultDepthOfScreen</function></funcdef>
2073   <paramdef>Screen<parameter> *screen</parameter></paramdef>
2074 </funcprototype>
2075 </funcsynopsis>
2076 <!-- .FN -->
2077 <variablelist>
2078   <varlistentry>
2079     <term>
2080       <emphasis remap='I'>screen</emphasis>
2081     </term>
2082     <listitem>
2083       <para>
2084 Specifies the appropriate
2085 <type>Screen</type>
2086 structure.
2087     </para>
2088   </listitem>
2089   </varlistentry>
2090 </variablelist>
2091 <para>
2092 <!-- .LP -->
2093 <!-- .eM -->
2094 <indexterm significance="preferred"><primary>DefaultDepthOfScreen</primary></indexterm>
2095 <indexterm significance="preferred"><primary>XDefaultDepthOfScreen</primary></indexterm>
2096 Both return the depth of the root window.
2097 </para>
2098 <para>
2099 <!-- .LP -->
2100 <!-- .sp -->
2101 <!-- .sM -->
2102 </para>
2103 <para>
2104 DefaultGCOfScreen(<emphasis remap='I'>screen</emphasis>)
2105 </para>
2106 <funcsynopsis id='XDefaultGCOfScreen'>
2107 <funcprototype>
2108   <funcdef>GC <function>XDefaultGCOfScreen</function></funcdef>
2109   <paramdef>Screen<parameter> *screen</parameter></paramdef>
2110 </funcprototype>
2111 </funcsynopsis>
2112 <!-- .FN -->
2113 <variablelist>
2114   <varlistentry>
2115     <term>
2116       <emphasis remap='I'>screen</emphasis>
2117     </term>
2118     <listitem>
2119       <para>
2120 Specifies the appropriate
2121 <type>Screen</type>
2122 structure.
2123     </para>
2124   </listitem>
2125   </varlistentry>
2126 </variablelist>
2127 <para>
2128 <!-- .LP -->
2129 <!-- .eM -->
2130 <indexterm significance="preferred"><primary>DefaultGCOfScreen</primary></indexterm>
2131 <indexterm significance="preferred"><primary>XDefaultGCOfScreen</primary></indexterm>
2132 Both return a default graphics context (GC) of the specified screen,
2133 which has the same depth as the root window of the screen.
2134 The GC must never be freed.
2135 </para>
2136 <para>
2137 <!-- .LP -->
2138 <!-- .sp -->
2139 <!-- .sM -->
2140 </para>
2141 <para>
2142 DefaultVisualOfScreen(<emphasis remap='I'>screen</emphasis>)
2143 </para>
2144 <funcsynopsis id='XDefaultVisualOfScreen'>
2145 <funcprototype>
2146   <funcdef>Visual *<function>XDefaultVisualOfScreen</function></funcdef>
2147   <paramdef>Screen<parameter> *screen</parameter></paramdef>
2148 </funcprototype>
2149 </funcsynopsis>
2150 <!-- .FN -->
2151 <variablelist>
2152   <varlistentry>
2153     <term>
2154       <emphasis remap='I'>screen</emphasis>
2155     </term>
2156     <listitem>
2157       <para>
2158 Specifies the appropriate
2159 <type>Screen</type>
2160 structure.
2161     </para>
2162   </listitem>
2163   </varlistentry>
2164 </variablelist>
2165 <para>
2166 <!-- .LP -->
2167 <!-- .eM -->
2168 <indexterm significance="preferred"><primary>DefaultVisualOfScreen</primary></indexterm>
2169 <indexterm significance="preferred"><primary>XDefaultVisualOfScreen</primary></indexterm>
2170 Both return the default visual of the specified screen.
2171 For information on visual types,
2172 see <link linkend="Visual_Types">section 3.1</link>.
2173 </para>
2174 <para>
2175 <!-- .LP -->
2176 <!-- .sp -->
2177 <!-- .sM -->
2178 </para>
2179 <para>
2180 DoesBackingStore(<emphasis remap='I'>screen</emphasis>)
2181 </para>
2182 <funcsynopsis id='XDoesBackingStore'>
2183 <funcprototype>
2184   <funcdef>int <function>XDoesBackingStore</function></funcdef>
2185   <paramdef>Screen<parameter> *screen</parameter></paramdef>
2186 </funcprototype>
2187 </funcsynopsis>
2188 <!-- .FN -->
2189 <variablelist>
2190   <varlistentry>
2191     <term>
2192       <emphasis remap='I'>screen</emphasis>
2193     </term>
2194     <listitem>
2195       <para>
2196 Specifies the appropriate
2197 <type>Screen</type>
2198 structure.
2199     </para>
2200   </listitem>
2201   </varlistentry>
2202 </variablelist>
2203 <para>
2204 <!-- .LP -->
2205 <!-- .eM -->
2206 <indexterm significance="preferred"><primary>DoesBackingStore</primary></indexterm>
2207 <indexterm significance="preferred"><primary>XDoesBackingStore</primary></indexterm>
2208 Both return a value indicating whether the screen supports backing
2209 stores.
2210 The value returned can be one of
2211 <symbol>WhenMapped</symbol>,
2212 <symbol>NotUseful</symbol>,
2213 or
2214 <symbol>Always</symbol>
2215 (see <link linkend="Backing_Store_Attribute">section 3.2.4</link>).
2216 </para>
2217 <para>
2218 <!-- .LP -->
2219 <!-- .sp -->
2220 <!-- .sM -->
2221 </para>
2222 <para>
2223 DoesSaveUnders(<emphasis remap='I'>screen</emphasis>)
2224 </para>
2225 <funcsynopsis id='XDoesSaveUnders'>
2226 <funcprototype>
2227   <funcdef>Bool <function>XDoesSaveUnders</function></funcdef>
2228   <paramdef>Screen<parameter> *screen</parameter></paramdef>
2229 </funcprototype>
2230 </funcsynopsis>
2231 <!-- .FN -->
2232 <variablelist>
2233   <varlistentry>
2234     <term>
2235       <emphasis remap='I'>screen</emphasis>
2236     </term>
2237     <listitem>
2238       <para>
2239 Specifies the appropriate
2240 <type>Screen</type>
2241 structure.
2242     </para>
2243   </listitem>
2244   </varlistentry>
2245 </variablelist>
2246 <para>
2247 <!-- .LP -->
2248 <!-- .eM -->
2249 <indexterm significance="preferred"><primary>DoesSaveUnders</primary></indexterm>
2250 <indexterm significance="preferred"><primary>XDoesSaveUnders</primary></indexterm>
2251 Both return a Boolean value indicating whether the
2252 screen supports save unders.
2253 If
2254 <symbol>True</symbol>,
2255 the screen supports save unders.
2256 If
2257 <symbol>False</symbol>,
2258 the screen does not support save unders
2259 (see <link linkend="Save_Under_Flag">section 3.2.5</link>).
2260 </para>
2261 <para>
2262 <!-- .LP -->
2263 <!-- .sp -->
2264 <!-- .sM -->
2265 </para>
2266 <para>
2267 DisplayOfScreen(<emphasis remap='I'>screen</emphasis>)
2268 </para>
2269 <funcsynopsis id='XDisplayOfScreen'>
2270 <funcprototype>
2271   <funcdef>Display *<function>XDisplayOfScreen</function></funcdef>
2272   <paramdef>Screen<parameter> *screen</parameter></paramdef>
2273 </funcprototype>
2274 </funcsynopsis>
2275 <!-- .FN -->
2276 <variablelist>
2277   <varlistentry>
2278     <term>
2279       <emphasis remap='I'>screen</emphasis>
2280     </term>
2281     <listitem>
2282       <para>
2283 Specifies the appropriate
2284 <type>Screen</type>
2285 structure.
2286     </para>
2287   </listitem>
2288   </varlistentry>
2289 </variablelist>
2290 <para>
2291 <!-- .LP -->
2292 <!-- .eM -->
2293 <indexterm significance="preferred"><primary>DisplayOfScreen</primary></indexterm>
2294 <indexterm significance="preferred"><primary>XDisplayOfScreen</primary></indexterm>
2295 Both return the display of the specified screen.
2296 </para>
2297 <para>
2298 <!-- .LP -->
2299 <!-- .sp -->
2300 <!-- .sM -->
2301 <indexterm significance="preferred"><primary>XScreenNumberOfScreen</primary></indexterm>
2302 </para>
2303 <para>
2304 EventMaskOfScreen(<emphasis remap='I'>screen</emphasis>)
2305 </para>
2306 <funcsynopsis id='XEventMaskOfScreen'>
2307 <funcprototype>
2308   <funcdef>long <function>XEventMaskOfScreen</function></funcdef>
2309   <paramdef>Screen<parameter> *screen</parameter></paramdef>
2310 </funcprototype>
2311 </funcsynopsis>
2312 <!-- .FN -->
2313 <variablelist>
2314   <varlistentry>
2315     <term>
2316       <emphasis remap='I'>screen</emphasis>
2317     </term>
2318     <listitem>
2319       <para>
2320 Specifies the appropriate
2321 <type>Screen</type>
2322 structure.
2323     </para>
2324   </listitem>
2325   </varlistentry>
2326 </variablelist>
2327 <para>
2328 <!-- .LP -->
2329 <!-- .eM -->
2330 The
2331 <function>XScreenNumberOfScreen</function>
2332 function returns the screen index number of the specified screen.
2333 </para>
2334 <para>
2335 <!-- .LP -->
2336 <!-- .sp -->
2337 <!-- .sM -->
2338 </para>
2339 <para>
2340 EventMaskOfScreen(<emphasis remap='I'>screen</emphasis>)
2341 </para>
2342 <funcsynopsis>
2343 <funcprototype>
2344   <funcdef>long <function>XEventMaskOfScreen</function></funcdef>
2345   <paramdef>Screen<parameter> *screen</parameter></paramdef>
2346 </funcprototype>
2347 </funcsynopsis>
2348 <!-- .FN -->
2349 <variablelist>
2350   <varlistentry>
2351     <term>
2352       <emphasis remap='I'>screen</emphasis>
2353     </term>
2354     <listitem>
2355       <para>
2356 Specifies the appropriate
2357 <type>Screen</type>
2358 structure.
2359     </para>
2360   </listitem>
2361   </varlistentry>
2362 </variablelist>
2363 <para>
2364 <!-- .LP -->
2365 <!-- .eM -->
2366 <indexterm significance="preferred"><primary>EventMaskOfScreen</primary></indexterm>
2367 <indexterm significance="preferred"><primary>XEventMaskOfScreen</primary></indexterm>
2368 Both return the event mask of the root window for the specified screen
2369 at connection setup time.
2370 </para>
2371 <para>
2372 <!-- .LP -->
2373 <!-- .sp -->
2374 <!-- .sM -->
2375 </para>
2376 <para>
2377 WidthOfScreen(<emphasis remap='I'>screen</emphasis>)
2378 </para>
2379 <funcsynopsis id='XWidthOfScreen'>
2380 <funcprototype>
2381   <funcdef>int <function>XWidthOfScreen</function></funcdef>
2382   <paramdef>Screen<parameter> *screen</parameter></paramdef>
2383 </funcprototype>
2384 </funcsynopsis>
2385 <!-- .FN -->
2386 <variablelist>
2387   <varlistentry>
2388     <term>
2389       <emphasis remap='I'>screen</emphasis>
2390     </term>
2391     <listitem>
2392       <para>
2393 Specifies the appropriate
2394 <type>Screen</type>
2395 structure.
2396     </para>
2397   </listitem>
2398   </varlistentry>
2399 </variablelist>
2400 <para>
2401 <!-- .LP -->
2402 <!-- .eM -->
2403 <indexterm significance="preferred"><primary>WidthOfScreen</primary></indexterm>
2404 <indexterm significance="preferred"><primary>XWidthOfScreen</primary></indexterm>
2405 Both return the width of the specified screen in pixels.
2406 </para>
2407 <para>
2408 <!-- .LP -->
2409 <!-- .sp -->
2410 <!-- .sM -->
2411 </para>
2412 <para>
2413 HeightOfScreen(<emphasis remap='I'>screen</emphasis>)
2414 </para>
2415 <funcsynopsis id='XHeightOfScreen'>
2416 <funcprototype>
2417   <funcdef>int <function>XHeightOfScreen</function></funcdef>
2418   <paramdef>Screen<parameter> *screen</parameter></paramdef>
2419 </funcprototype>
2420 </funcsynopsis>
2421 <!-- .FN -->
2422 <variablelist>
2423   <varlistentry>
2424     <term>
2425       <emphasis remap='I'>screen</emphasis>
2426     </term>
2427     <listitem>
2428       <para>
2429 Specifies the appropriate
2430 <type>Screen</type>
2431 structure.
2432     </para>
2433   </listitem>
2434   </varlistentry>
2435 </variablelist>
2436 <para>
2437 <!-- .LP -->
2438 <!-- .eM -->
2439 <indexterm significance="preferred"><primary>HeightOfScreen</primary></indexterm>
2440 <indexterm significance="preferred"><primary>XHeightOfScreen</primary></indexterm>
2441 Both return the height of the specified screen in pixels.
2442 </para>
2443 <para>
2444 <!-- .LP -->
2445 <!-- .sp -->
2446 <!-- .sM -->
2447 </para>
2448 <para>
2449 WidthMMOfScreen(<emphasis remap='I'>screen</emphasis>)
2450 </para>
2451 <funcsynopsis id='XWidthMMOfScreen'>
2452 <funcprototype>
2453   <funcdef>int <function>XWidthMMOfScreen</function></funcdef>
2454   <paramdef>Screen<parameter> *screen</parameter></paramdef>
2455 </funcprototype>
2456 </funcsynopsis>
2457 <!-- .FN -->
2458 <variablelist>
2459   <varlistentry>
2460     <term>
2461       <emphasis remap='I'>screen</emphasis>
2462     </term>
2463     <listitem>
2464       <para>
2465 Specifies the appropriate
2466 <type>Screen</type>
2467 structure.
2468     </para>
2469   </listitem>
2470   </varlistentry>
2471 </variablelist>
2472 <para>
2473 <!-- .LP -->
2474 <!-- .eM -->
2475 <indexterm significance="preferred"><primary>WidthMMOfScreen</primary></indexterm>
2476 <indexterm significance="preferred"><primary>XWidthMMOfScreen</primary></indexterm>
2477 Both return the width of the specified screen in millimeters.
2478 </para>
2479 <para>
2480 <!-- .LP -->
2481 <!-- .sp -->
2482 <!-- .sM -->
2483 </para>
2484 <para>
2485 HeightMMOfScreen(<emphasis remap='I'>screen</emphasis>)
2486 </para>
2487 <funcsynopsis id='XHeightMMOfScreen'>
2488 <funcprototype>
2489   <funcdef>int <function>XHeightMMOfScreen</function></funcdef>
2490   <paramdef>Screen<parameter> *screen</parameter></paramdef>
2491 </funcprototype>
2492 </funcsynopsis>
2493 <!-- .FN -->
2494 <variablelist>
2495   <varlistentry>
2496     <term>
2497       <emphasis remap='I'>screen</emphasis>
2498     </term>
2499     <listitem>
2500       <para>
2501 Specifies the appropriate
2502 <type>Screen</type>
2503 structure.
2504     </para>
2505   </listitem>
2506   </varlistentry>
2507 </variablelist>
2508 <para>
2509 <!-- .LP -->
2510 <!-- .eM -->
2511 <indexterm significance="preferred"><primary>HeightMMOfScreen</primary></indexterm>
2512 <indexterm significance="preferred"><primary>XHeightMMOfScreen</primary></indexterm>
2513 Both return the height of the specified screen in millimeters.
2514 </para>
2515 <para>
2516 <!-- .LP -->
2517 <!-- .sp -->
2518 <!-- .sM -->
2519 </para>
2520 <para>
2521 MaxCmapsOfScreen(<emphasis remap='I'>screen</emphasis>)
2522 </para>
2523 <funcsynopsis id='XMaxCmapsOfScreen'>
2524 <funcprototype>
2525   <funcdef>int <function>XMaxCmapsOfScreen</function></funcdef>
2526   <paramdef>Screen<parameter> *screen</parameter></paramdef>
2527 </funcprototype>
2528 </funcsynopsis>
2529 <!-- .FN -->
2530 <variablelist>
2531   <varlistentry>
2532     <term>
2533       <emphasis remap='I'>screen</emphasis>
2534     </term>
2535     <listitem>
2536       <para>
2537 Specifies the appropriate
2538 <type>Screen</type>
2539 structure.
2540     </para>
2541   </listitem>
2542   </varlistentry>
2543 </variablelist>
2544 <para>
2545 <!-- .LP -->
2546 <!-- .eM -->
2547 <indexterm significance="preferred"><primary>MaxCmapsOfScreen</primary></indexterm>
2548 <indexterm significance="preferred"><primary>XMaxCmapsOfScreen</primary></indexterm>
2549 Both return the maximum number of installed colormaps supported
2550 by the specified screen
2551 (see <link linkend="Managing_Installed_Colormaps">section 9.3</link>).
2552 </para>
2553 <para>
2554 <!-- .LP -->
2555 <!-- .sp -->
2556 <!-- .sM -->
2557 </para>
2558 <para>
2559 MinCmapsOfScreen(<emphasis remap='I'>screen</emphasis>)
2560 </para>
2561 <funcsynopsis id='XMinCmapsOfScreen'>
2562 <funcprototype>
2563   <funcdef>int <function>XMinCmapsOfScreen</function></funcdef>
2564   <paramdef>Screen<parameter> *screen</parameter></paramdef>
2565 </funcprototype>
2566 </funcsynopsis>
2567 <!-- .FN -->
2568 <variablelist>
2569   <varlistentry>
2570     <term>
2571       <emphasis remap='I'>screen</emphasis>
2572     </term>
2573     <listitem>
2574       <para>
2575 Specifies the appropriate
2576 <type>Screen</type>
2577 structure.
2578     </para>
2579   </listitem>
2580   </varlistentry>
2581 </variablelist>
2582 <para>
2583 <!-- .LP -->
2584 <!-- .eM -->
2585 <indexterm significance="preferred"><primary>MinCmapsOfScreen</primary></indexterm>
2586 <indexterm significance="preferred"><primary>XMinCmapsOfScreen</primary></indexterm>
2587 Both return the minimum number of installed colormaps supported
2588 by the specified screen
2589 (see <link linkend="Managing_Installed_Colormaps">section 9.3</link>).
2590 </para>
2591 <para>
2592 <!-- .LP -->
2593 <!-- .sp -->
2594 <!-- .sM -->
2595 </para>
2596 <para>
2597 PlanesOfScreen(<emphasis remap='I'>screen</emphasis>)
2598 </para>
2599 <funcsynopsis id='XPlanesOfScreen'>
2600 <funcprototype>
2601   <funcdef>int <function>XPlanesOfScreen</function></funcdef>
2602   <paramdef>Screen<parameter> *screen</parameter></paramdef>
2603 </funcprototype>
2604 </funcsynopsis>
2605 <!-- .FN -->
2606 <variablelist>
2607   <varlistentry>
2608     <term>
2609       <emphasis remap='I'>screen</emphasis>
2610     </term>
2611     <listitem>
2612       <para>
2613 Specifies the appropriate
2614 <type>Screen</type>
2615 structure.
2616     </para>
2617   </listitem>
2618   </varlistentry>
2619 </variablelist>
2620 <para>
2621 <!-- .LP -->
2622 <!-- .eM -->
2623 <indexterm significance="preferred"><primary>PlanesOfScreen</primary></indexterm>
2624 <indexterm significance="preferred"><primary>XPlanesOfScreen</primary></indexterm>
2625 Both return the depth of the root window.
2626 </para>
2627 <para>
2628 <!-- .LP -->
2629 <!-- .sp -->
2630 <!-- .sM -->
2631 </para>
2632 <para>
2633 RootWindowOfScreen(<emphasis remap='I'>screen</emphasis>)
2634 </para>
2635 <funcsynopsis id='XRootWindowOfScreen'>
2636 <funcprototype>
2637   <funcdef>Window <function>XRootWindowOfScreen</function></funcdef>
2638   <paramdef>Screen<parameter> *screen</parameter></paramdef>
2639 </funcprototype>
2640 </funcsynopsis>
2641 <!-- .FN -->
2642 <variablelist>
2643   <varlistentry>
2644     <term>
2645       <emphasis remap='I'>screen</emphasis>
2646     </term>
2647     <listitem>
2648       <para>
2649 Specifies the appropriate
2650 <type>Screen</type>
2651 structure.
2652     </para>
2653   </listitem>
2654   </varlistentry>
2655 </variablelist>
2656 <para>
2657 <!-- .LP -->
2658 <!-- .eM -->
2659 <indexterm significance="preferred"><primary>RootWindowOfScreen</primary></indexterm>
2660 <indexterm significance="preferred"><primary>XRootWindowOfScreen</primary></indexterm>
2661 Both return the root window of the specified screen.
2662 </para>
2663 </sect2>
2664 </sect1>
2665 <sect1 id="Generating_a_NoOperation_Protocol_Request">
2666 <title>Generating a NoOperation Protocol Request</title>
2667 <!-- .XS -->
2668 <!-- (SN Generating a NoOperation Protocol Request -->
2669 <!-- .XE -->
2670 <para>
2671 <!-- .LP -->
2672 To execute a
2673 <systemitem>NoOperation</systemitem>
2674 protocol request, use
2675 <xref linkend='XNoOp' xrefstyle='select: title'/>.
2676 <indexterm significance="preferred"><primary>XNoOp</primary></indexterm>
2677 <!-- .sM -->
2678 </para>
2679 <funcsynopsis id='XNoOp'>
2680 <funcprototype>
2681   <funcdef><function>XNoOp</function></funcdef>
2682   <paramdef>Display<parameter> *display</parameter></paramdef>
2683 </funcprototype>
2684 </funcsynopsis>
2685
2686 <variablelist>
2687   <varlistentry>
2688     <term><emphasis remap='I'>display</emphasis></term>
2689     <listitem>
2690       <para>Specifies the connection to the X server.</para>
2691     </listitem>
2692   </varlistentry>
2693 </variablelist>
2694 <para>
2695 <!-- .LP -->
2696 <!-- .eM -->
2697 The
2698 <xref linkend='XNoOp' xrefstyle='select: title'/>
2699 function sends a
2700 <systemitem>NoOperation</systemitem>
2701 protocol request to the X server,
2702 thereby exercising the connection.
2703 </para>
2704 </sect1>
2705 <sect1 id="Freeing_Client_Created_Data">
2706 <title>Freeing Client-Created Data</title>
2707 <!-- .XS -->
2708 <!-- (SN Freeing Client-Created Data -->
2709 <!-- .XE -->
2710 <para>
2711 <!-- .LP -->
2712 To free in-memory data that was created by an Xlib function, use
2713 <xref linkend='XFree' xrefstyle='select: title'/>.
2714 <indexterm significance="preferred"><primary>XFree</primary></indexterm>
2715 <!-- .sM -->
2716 </para>
2717 <funcsynopsis id='XFree'>
2718 <funcprototype>
2719   <funcdef>XFree</funcdef>
2720   <paramdef>void<parameter> *data</parameter></paramdef>
2721 </funcprototype>
2722 </funcsynopsis>
2723
2724 <!-- .FN -->
2725 <variablelist>
2726   <varlistentry>
2727     <term>
2728       <emphasis remap='I'>data</emphasis>
2729     </term>
2730     <listitem>
2731       <para>
2732 Specifies the data that is to be freed.
2733     </para>
2734   </listitem>
2735   </varlistentry>
2736 </variablelist>
2737 <para>
2738 <!-- .LP -->
2739 <!-- .eM -->
2740 The
2741 <xref linkend='XFree' xrefstyle='select: title'/>
2742 function is a general-purpose Xlib routine that frees the specified data.
2743 You must use it to free any objects that were allocated by Xlib,
2744 unless an alternate function is explicitly specified for the object.
2745 A NULL pointer cannot be passed to this function.
2746 </para>
2747 </sect1>
2748 <sect1 id="Closing_the_Display">
2749 <title>Closing the Display</title>
2750 <!-- .XS -->
2751 <!-- (SN Closing the Display -->
2752 <!-- .XE -->
2753 <para>
2754 <!-- .LP -->
2755 To close a display or disconnect from the X server, use
2756 <function>XCloseDisplay</function>.
2757 <indexterm significance="preferred"><primary>XCloseDisplay</primary></indexterm>
2758 </para>
2759 <para>
2760 <!-- .LP -->
2761 <!-- .sM -->
2762 </para>
2763 <funcsynopsis id='xclosedisplay'>
2764 <funcprototype>
2765   <funcdef>XCloseDisplay</funcdef>
2766   <paramdef>Display<parameter> *display</parameter></paramdef>
2767 </funcprototype>
2768 </funcsynopsis>
2769
2770 <!-- .FN -->
2771 <variablelist>
2772   <varlistentry>
2773     <term>
2774       <emphasis remap='I'>display</emphasis>
2775     </term>
2776     <listitem>
2777       <para>
2778 Specifies the connection to the X server.
2779     </para>
2780   </listitem>
2781   </varlistentry>
2782 </variablelist>
2783 <para>
2784 <!-- .LP -->
2785 <!-- .eM -->
2786 The
2787 <function>XCloseDisplay</function>
2788 function closes the connection to the X server for the display specified in the
2789 <type>Display</type>
2790 structure and destroys all windows, resource IDs
2791 (<type>Window</type>,
2792 <type>Font</type>,
2793 <type>Pixmap</type>,
2794 <type>Colormap</type>,
2795 <type>Cursor</type>,
2796 and
2797 <type>GContext</type>),
2798 or other resources that the client has created
2799 on this display, unless the close-down mode of the resource has been changed
2800 (see
2801 <xref linkend='XSetCloseDownMode' xrefstyle='select: title'/>).
2802 Therefore, these windows, resource IDs, and other resources should never be
2803 referenced again or an error will be generated.
2804 Before exiting, you should call
2805 <function>XCloseDisplay</function>
2806 explicitly so that any pending errors are reported as
2807 <function>XCloseDisplay</function>
2808 performs a final
2809 <xref linkend='XSync' xrefstyle='select: title'/>
2810 operation.
2811 <indexterm><primary>Resource IDs</primary></indexterm>
2812 <indexterm><primary>XCloseDisplay</primary></indexterm>
2813 </para>
2814 <para>
2815 <!-- .LP -->
2816 <function>XCloseDisplay</function>
2817 can generate a
2818 <errorname>BadGC</errorname>
2819 error.
2820 <!-- .sp -->
2821 </para>
2822 <para>
2823 <!-- .LP -->
2824 Xlib provides a function to permit the resources owned by a client
2825 to survive after the client's connection is closed.
2826 To change a client's close-down mode, use
2827 <xref linkend='XSetCloseDownMode' xrefstyle='select: title'/>.
2828 <indexterm significance="preferred"><primary>XSetCloseDownMode</primary></indexterm>
2829 <!-- .sM -->
2830 </para>
2831 <funcsynopsis id='XSetCloseDownMode'>
2832 <funcprototype>
2833   <funcdef>XSetCloseDownMode</funcdef>
2834   <paramdef>Display<parameter> *display</parameter></paramdef>
2835   <paramdef>int<parameter> close_mode</parameter></paramdef>
2836 </funcprototype>
2837 </funcsynopsis>
2838 <!-- .FN -->
2839 <variablelist>
2840   <varlistentry>
2841     <term>
2842       <emphasis remap='I'>display</emphasis>
2843     </term>
2844     <listitem>
2845       <para>
2846 Specifies the connection to the X server.
2847       </para>
2848     </listitem>
2849   </varlistentry>
2850   <varlistentry>
2851     <term>
2852       <emphasis remap='I'>close_mode</emphasis>
2853     </term>
2854     <listitem>
2855       <para>
2856 Specifies the client close-down mode.
2857 You can pass
2858 <symbol>DestroyAll</symbol>,
2859 <symbol>RetainPermanent</symbol>,
2860 or
2861 <symbol>RetainTemporary</symbol>.
2862     </para>
2863   </listitem>
2864   </varlistentry>
2865 </variablelist>
2866 <para>
2867 <!-- .LP -->
2868 <!-- .eM -->
2869 The
2870 <xref linkend='XSetCloseDownMode' xrefstyle='select: title'/>
2871 defines what will happen to the client's resources at connection close.
2872 A connection starts in
2873 <symbol>DestroyAll</symbol>
2874 mode.
2875 For information on what happens to the client's resources when the
2876 close_mode argument is
2877 <symbol>RetainPermanent</symbol>
2878 or
2879 <symbol>RetainTemporary</symbol>,
2880 see <link linkend='Using_X_Server_Connection_Close_Operations'>section 2.6</link>.
2881 </para>
2882 <para>
2883 <!-- .LP -->
2884 <xref linkend='XSetCloseDownMode' xrefstyle='select: title'/>
2885 can generate a
2886 <errorname>BadValue</errorname>
2887 error.
2888 </para>
2889 </sect1>
2890 <sect1 id='Using_X_Server_Connection_Close_Operations'>
2891 <title>Using X Server Connection Close Operations</title>
2892 <!-- .XS -->
2893 <!-- (SN Using X Server Connection Close Operations -->
2894 <!-- .XE -->
2895 <para>
2896 <!-- .LP -->
2897 When the X server's connection to a client is closed
2898 either by an explicit call to
2899 <function>XCloseDisplay</function>
2900 or by a process that exits, the X server performs the following
2901 automatic operations:
2902 </para>
2903 <itemizedlist>
2904   <listitem>
2905     <para>
2906 It disowns all selections owned by the client
2907 (see
2908 <xref linkend='XSetSelectionOwner' xrefstyle='select: title'/>).
2909     </para>
2910   </listitem>
2911   <listitem>
2912     <para>
2913 It performs an
2914 <xref linkend='XUngrabPointer' xrefstyle='select: title'/>
2915 and
2916 <xref linkend='XUngrabKeyboard' xrefstyle='select: title'/>
2917 if the client has actively grabbed the pointer
2918 or the keyboard.
2919     </para>
2920   </listitem>
2921   <listitem>
2922     <para>
2923 It performs an
2924 <xref linkend='XUngrabServer' xrefstyle='select: title'/>
2925 if the client has grabbed the server.
2926     </para>
2927   </listitem>
2928   <listitem>
2929     <para>
2930 It releases all passive grabs made by the client.
2931     </para>
2932   </listitem>
2933   <listitem>
2934     <para>
2935 It marks all resources (including colormap entries) allocated
2936 by the client either as permanent or temporary,
2937 depending on whether the close-down mode is
2938 <symbol>RetainPermanent</symbol>
2939 or
2940 <symbol>RetainTemporary</symbol>.
2941 However, this does not prevent other client applications from explicitly
2942 destroying the resources (see
2943 <xref linkend='XSetCloseDownMode' xrefstyle='select: title'/>).
2944     </para>
2945   </listitem>
2946 </itemizedlist>
2947 <para>
2948 <!-- .LP -->
2949 When the close-down mode is
2950 <symbol>DestroyAll</symbol>,
2951 the X server destroys all of a client's resources as follows:
2952 </para>
2953 <itemizedlist>
2954   <listitem>
2955     <para>
2956 It examines each window in the client's save-set to determine if it is an inferior
2957 (subwindow) of a window created by the client.
2958 (The save-set is a list of other clients' windows
2959 that are referred to as save-set windows.)
2960 If so, the X server reparents the save-set window to the closest ancestor so
2961 that the save-set window is not an inferior of a window created by the client.
2962 The reparenting leaves unchanged the absolute coordinates (with respect to
2963 the root window) of the upper-left outer corner of the save-set
2964 window.
2965     </para>
2966   </listitem>
2967   <listitem>
2968     <para>
2969 It performs a
2970 <systemitem>MapWindow</systemitem>
2971 request on the save-set window if the save-set window is unmapped.
2972 The X server does this even if the save-set window was not an inferior of
2973 a window created by the client.
2974     </para>
2975   </listitem>
2976   <listitem>
2977     <para>
2978 It destroys all windows created by the client.
2979     </para>
2980   </listitem>
2981   <listitem>
2982     <para>
2983 It performs the appropriate free request on each nonwindow resource created by
2984 the client in the server (for example,
2985 <type>Font</type>,
2986 <type>Pixmap</type>,
2987 <type>Cursor</type>,
2988 <type>Colormap</type>,
2989 and
2990 <type>GContext</type>).
2991     </para>
2992   </listitem>
2993   <listitem>
2994     <para>
2995 It frees all colors and colormap entries allocated by a client application.
2996     </para>
2997   </listitem>
2998 </itemizedlist>
2999 <para>
3000 <!-- .LP -->
3001 Additional processing occurs when the last connection to the X server closes.
3002 An X server goes through a cycle of having no connections and having some
3003 connections.
3004 When the last connection to the X server closes as a result of a connection
3005 closing with the close_mode of
3006 <symbol>DestroyAll</symbol>,
3007 the X server does the following:
3008 </para>
3009 <itemizedlist>
3010   <listitem>
3011     <para>
3012 It resets its state as if it had just been
3013 started.
3014 The X server begins by destroying all lingering resources from
3015 clients that have terminated in
3016 <symbol>RetainPermanent</symbol>
3017 or
3018 <symbol>RetainTemporary</symbol>
3019 mode.
3020     </para>
3021   </listitem>
3022   <listitem>
3023     <para>
3024 It deletes all but the predefined atom identifiers.
3025     </para>
3026   </listitem>
3027   <listitem>
3028     <para>
3029 It deletes all properties on all root windows
3030 (see <link linkend="Properties_and_Atoms">section 4.3</link>).
3031     </para>
3032   </listitem>
3033   <listitem>
3034     <para>
3035 It resets all device maps and attributes
3036 (for example, key click, bell volume, and acceleration)
3037 as well as the access control list.
3038     </para>
3039   </listitem>
3040   <listitem>
3041     <para>
3042 It restores the standard root tiles and cursors.
3043     </para>
3044   </listitem>
3045   <listitem>
3046     <para>
3047 It restores the default font path.
3048     </para>
3049   </listitem>
3050   <listitem>
3051     <para>
3052 It restores the input focus to state
3053 <symbol>PointerRoot</symbol>.
3054     </para>
3055   </listitem>
3056 </itemizedlist>
3057 <para>
3058 <!-- .LP -->
3059 However, the X server does not reset if you close a connection with a close-down
3060 mode set to
3061 <symbol>RetainPermanent</symbol>
3062 or
3063 <symbol>RetainTemporary</symbol>.
3064 </para>
3065 </sect1>
3066 <sect1 id="Using_Xlib_with_Threads">
3067 <title>Using Xlib with Threads</title>
3068 <!-- .XS -->
3069 <!-- (SN Using Xlib with Threads -->
3070 <!-- .XE -->
3071 <para>
3072 <!-- .LP -->
3073 On systems that have threads, support may be provided to permit
3074 multiple threads to use Xlib concurrently.
3075 </para>
3076 <para>
3077 <!-- .LP -->
3078 <!-- .sp -->
3079 To initialize support for concurrent threads, use
3080 <function>XInitThreads</function>.
3081 <indexterm significance="preferred"><primary>XInitThreads</primary></indexterm>
3082 <!-- .sM -->
3083 </para>
3084 <para>Status XInitThreads();</para>
3085 <!-- .FN -->
3086 <para>
3087 <!-- .LP -->
3088 <!-- .eM -->
3089 The
3090 <function>XInitThreads</function>
3091 function initializes Xlib support for concurrent threads.
3092 This function must be the first Xlib function a
3093 multi-threaded program calls, and it must complete
3094 before any other Xlib call is made.
3095 This function returns a nonzero status if initialization was
3096 successful; otherwise, it returns zero.
3097 On systems that do not support threads, this function always returns zero.
3098 </para>
3099 <para>
3100 <!-- .LP -->
3101 It is only necessary to call this function if multiple threads
3102 might use Xlib concurrently.  If all calls to Xlib functions
3103 are protected by some other access mechanism (for example,
3104 a mutual exclusion lock in a toolkit or through explicit client
3105 programming), Xlib thread initialization is not required.
3106 It is recommended that single-threaded programs not call this function.
3107
3108 </para>
3109 <para>
3110 <!-- .LP -->
3111 <!-- .sp -->
3112 To lock a display across several Xlib calls, use
3113 <function>XLockDisplay</function>.
3114 <indexterm significance="preferred"><primary>XLockDisplay</primary></indexterm>
3115 <!-- .sM -->
3116 </para>
3117 <funcsynopsis id='xlockdisplay'>
3118 <funcprototype>
3119   <funcdef>XLockDisplay</funcdef>
3120   <paramdef>Display<parameter> *display</parameter></paramdef>
3121 </funcprototype>
3122 </funcsynopsis>
3123
3124 <variablelist>
3125   <varlistentry>
3126     <term>
3127       <emphasis remap='I'>display</emphasis>
3128     </term>
3129     <listitem>
3130       <para>
3131 Specifies the connection to the X server.
3132     </para>
3133   </listitem>
3134   </varlistentry>
3135 </variablelist>
3136 <para>
3137 <!-- .LP -->
3138 <!-- .eM -->
3139 The
3140 <function>XLockDisplay</function>
3141 function locks out all other threads from using the specified display.
3142 Other threads attempting to use the display will block until
3143 the display is unlocked by this thread.
3144 Nested calls to
3145 <function>XLockDisplay</function>
3146 work correctly; the display will not actually be unlocked until
3147 <xref linkend='XUnlockDisplay' xrefstyle='select: title'/>
3148 has been called the same number of times as
3149 <function>XLockDisplay</function>.
3150 This function has no effect unless Xlib was successfully initialized
3151 for threads using
3152 <function>XInitThreads</function>.
3153 </para>
3154 <para>
3155 <!-- .LP -->
3156 <!-- .sp -->
3157 To unlock a display, use
3158 <xref linkend='XUnlockDisplay' xrefstyle='select: title'/>.
3159 <indexterm significance="preferred"><primary>XUnlockDisplay</primary></indexterm>
3160 <!-- .sM -->
3161 </para>
3162 <funcsynopsis id='XUnlockDisplay'>
3163 <funcprototype>
3164   <funcdef>XUnlockDisplay</funcdef>
3165   <paramdef>Display<parameter> *display</parameter></paramdef>
3166 </funcprototype>
3167 </funcsynopsis>
3168 <!-- .FN -->
3169 <variablelist>
3170   <varlistentry>
3171     <term>
3172       <emphasis remap='I'>display</emphasis>
3173     </term>
3174     <listitem>
3175       <para>
3176 Specifies the connection to the X server.
3177     </para>
3178   </listitem>
3179   </varlistentry>
3180 </variablelist>
3181 <para>
3182 <!-- .LP -->
3183 <!-- .eM -->
3184 The
3185 <xref linkend='XUnlockDisplay' xrefstyle='select: title'/>
3186 function allows other threads to use the specified display again.
3187 Any threads that have blocked on the display are allowed to continue.
3188 Nested locking works correctly; if
3189 <function>XLockDisplay</function>
3190 has been called multiple times by a thread, then
3191 <xref linkend='XUnlockDisplay' xrefstyle='select: title'/>
3192 must be called an equal number of times before the display is
3193 actually unlocked.
3194 This function has no effect unless Xlib was successfully initialized
3195 for threads using
3196 <function>XInitThreads</function>.
3197 </para>
3198 </sect1>
3199 <sect1 id="Using_Internal_Connections">
3200 <title>Using Internal Connections</title>
3201 <!-- .XS -->
3202 <!-- (SN Using Internal Connections -->
3203 <!-- .XE -->
3204 <para>
3205 <!-- .LP -->
3206 In addition to the connection to the X server, an Xlib implementation
3207 may require connections to other kinds of servers (for example, to
3208 input method servers as described in
3209 <link linkend='Locales_and_Internationalized_Text_Functions'>chapter 13</link>).
3210 Toolkits and clients
3211 that use multiple displays, or that use displays in combination with
3212 other inputs, need to obtain these additional connections to correctly
3213 block until input is available and need to process that input
3214 when it is available.  Simple clients that use a single display and
3215 block for input in an Xlib event function do not need to use these
3216 facilities.
3217 </para>
3218 <para>
3219 <!-- .LP -->
3220 To track internal connections for a display, use
3221 <xref linkend='XAddConnectionWatch' xrefstyle='select: title'/>.
3222 </para>
3223 <funcsynopsis id='xconnectionwatch'>
3224 <funcprototype>
3225   <funcdef>type void XConnectionWatchProc</funcdef>
3226   <paramdef>Display<parameter> *display</parameter></paramdef>
3227   <paramdef>XPointer<parameter> client_data</parameter></paramdef>
3228   <paramdef>int<parameter> fd</parameter></paramdef>
3229   <paramdef>Bool<parameter> opening</parameter></paramdef>
3230   <paramdef>XPointer<parameter> *watch_data</parameter></paramdef>
3231 </funcprototype>
3232 </funcsynopsis>
3233
3234 <funcsynopsis id='XAddConnectionWatch'>
3235 <funcprototype>
3236   <funcdef>Status XAddConnectionWatch</funcdef>
3237   <paramdef>Display<parameter> *display</parameter></paramdef>
3238   <paramdef>XWatchProc<parameter> procedure</parameter></paramdef>
3239   <paramdef>XPointer<parameter> client_data</parameter></paramdef>
3240 </funcprototype>
3241 </funcsynopsis>
3242
3243 <variablelist>
3244   <varlistentry>
3245     <term>
3246       <emphasis remap='I'>display</emphasis>
3247     </term>
3248     <listitem>
3249       <para>
3250 Specifies the connection to the X server.
3251       </para>
3252     </listitem>
3253   </varlistentry>
3254   <varlistentry>
3255     <term>
3256       <emphasis remap='I'>procedure</emphasis>
3257     </term>
3258     <listitem>
3259       <para>
3260 Specifies the procedure to be called.
3261       </para>
3262     </listitem>
3263   </varlistentry>
3264   <varlistentry>
3265     <term>
3266       <emphasis remap='I'>client_data</emphasis>
3267     </term>
3268     <listitem>
3269       <para>
3270 Specifies the additional client data.
3271     </para>
3272   </listitem>
3273   </varlistentry>
3274 </variablelist>
3275 <para>
3276 <!-- .LP -->
3277 <!-- .eM -->
3278 The
3279 <xref linkend='XAddConnectionWatch' xrefstyle='select: title'/>
3280 function registers a procedure to be called each time Xlib opens or closes an
3281 internal connection for the specified display.  The procedure is passed the
3282 display, the specified client_data, the file descriptor for the connection,
3283 a Boolean indicating whether the connection is being opened or closed, and a
3284 pointer to a location for private watch data.  If opening is
3285 <symbol>True</symbol>,
3286 the procedure can store a pointer to private data in the location pointed
3287 to by watch_data;
3288 when the procedure is later called for this same connection and opening is
3289 <symbol>False</symbol>,
3290 the location pointed to by watch_data will hold this same private data pointer.
3291 </para>
3292 <para>
3293 <!-- .LP -->
3294 This function can be called at any time after a display is opened.
3295 If internal connections already exist, the registered procedure will
3296 immediately be called for each of them, before
3297 <xref linkend='XAddConnectionWatch' xrefstyle='select: title'/>
3298 returns.
3299 <xref linkend='XAddConnectionWatch' xrefstyle='select: title'/>
3300 returns a nonzero status if the procedure is successfully registered;
3301 otherwise, it returns zero.
3302 </para>
3303 <para>
3304 <!-- .LP -->
3305 The registered procedure should not call any Xlib functions.
3306 If the procedure directly or indirectly causes the state of internal
3307 connections or watch procedures to change, the result is not defined.
3308 If Xlib has been initialized for threads, the procedure is called with
3309 the display locked and the result of a call by the procedure to any
3310 Xlib function that locks the display is not defined unless the executing
3311 thread has externally locked the display using
3312 <function>XLockDisplay</function>.
3313 </para>
3314 <para>
3315 <!-- .LP -->
3316 <!-- .sp -->
3317 To stop tracking internal connections for a display, use
3318 <function>XRemoveConnectionWatch</function>.
3319 <indexterm significance="preferred"><primary>XRemoveConnectionWatch</primary></indexterm>
3320 <!-- .sM -->
3321 </para>
3322 <para>
3323 ()
3324 </para>
3325 <funcsynopsis id='xremoveconnectionwatch'>
3326 <funcprototype>
3327   <funcdef>Status <function>XRemoveConnectionWatch</function></funcdef>
3328   <paramdef>Display<parameter> *display</parameter></paramdef>
3329   <paramdef>XWatchProc<parameter> procedure</parameter></paramdef>
3330   <paramdef>XPointer<parameter> client_data</parameter></paramdef>
3331 </funcprototype>
3332 </funcsynopsis>
3333 <!-- .FN -->
3334 <variablelist>
3335   <varlistentry>
3336     <term>
3337       <emphasis remap='I'>display</emphasis>
3338     </term>
3339     <listitem>
3340       <para>
3341 Specifies the connection to the X server.
3342       </para>
3343     </listitem>
3344   </varlistentry>
3345   <varlistentry>
3346     <term>
3347       <emphasis remap='I'>procedure</emphasis>
3348     </term>
3349     <listitem>
3350       <para>
3351 Specifies the procedure to be called.
3352       </para>
3353     </listitem>
3354   </varlistentry>
3355   <varlistentry>
3356     <term>
3357       <emphasis remap='I'>client_data</emphasis>
3358     </term>
3359     <listitem>
3360       <para>
3361 Specifies the additional client data.
3362     </para>
3363   </listitem>
3364   </varlistentry>
3365 </variablelist>
3366 <para>
3367 <!-- .LP -->
3368 <!-- .eM -->
3369 The
3370 <function>XRemoveConnectionWatch</function>
3371 function removes a previously registered connection watch procedure.
3372 The client_data must match the client_data used when the procedure
3373 was initially registered.
3374
3375 </para>
3376 <para>
3377 <!-- .LP -->
3378 <!-- .sp -->
3379 To process input on an internal connection, use
3380 <xref linkend='XProcessInternalConnection' xrefstyle='select: title'/>.
3381 <indexterm significance="preferred"><primary>XProcessInternalConnection</primary></indexterm>
3382 <!-- .sM -->
3383 </para>
3384 <para>
3385 ()
3386 </para>
3387 <funcsynopsis id='XProcessInternalConnection'>
3388 <funcprototype>
3389   <funcdef>void <function>XProcessInternalConnection</function></funcdef>
3390   <paramdef>Display<parameter> *display</parameter></paramdef>
3391   <paramdef>int<parameter> fd</parameter></paramdef>
3392 </funcprototype>
3393 </funcsynopsis>
3394 <!-- .FN -->
3395 <variablelist>
3396   <varlistentry>
3397     <term>
3398       <emphasis remap='I'>display</emphasis>
3399     </term>
3400     <listitem>
3401       <para>
3402 Specifies the connection to the X server.
3403       </para>
3404     </listitem>
3405   </varlistentry>
3406   <varlistentry>
3407     <term>
3408       <emphasis remap='I'>fd</emphasis>
3409     </term>
3410     <listitem>
3411       <para>
3412 Specifies the file descriptor.
3413     </para>
3414   </listitem>
3415   </varlistentry>
3416 </variablelist>
3417 <para>
3418 <!-- .LP -->
3419 <!-- .eM -->
3420 The
3421 <xref linkend='XProcessInternalConnection' xrefstyle='select: title'/>
3422 function processes input available on an internal connection.
3423 This function should be called for an internal connection only
3424 after an operating system facility (for example,
3425 <function>select</function>
3426 or
3427 <function>poll</function>)
3428 has indicated that input is available; otherwise,
3429 the effect is not defined.
3430 </para>
3431 <para>
3432 <!-- .LP -->
3433 <!-- .sp -->
3434 To obtain all of the current internal connections for a display, use
3435 <xref linkend='XInternalConnectionNumbers' xrefstyle='select: title'/>.
3436 <indexterm significance="preferred"><primary>XInternalConnectionNumbers</primary></indexterm>
3437 <!-- .sM -->
3438 </para>
3439 <para>
3440 ()
3441 </para>
3442 <funcsynopsis id='XInternalConnectionNumbers'>
3443 <funcprototype>
3444   <funcdef>Status <function>XInternalConnectionNumbers</function></funcdef>
3445   <paramdef>Display<parameter> *display</parameter></paramdef>
3446   <paramdef>int **<parameter> fd</parameter></paramdef>
3447   <paramdef>int *<parameter> count_return</parameter></paramdef>
3448 </funcprototype>
3449 </funcsynopsis>
3450 <!-- .FN -->
3451 <variablelist>
3452   <varlistentry>
3453     <term>
3454       <emphasis remap='I'>display</emphasis>
3455     </term>
3456     <listitem>
3457       <para>
3458 Specifies the connection to the X server.
3459       </para>
3460     </listitem>
3461   </varlistentry>
3462   <varlistentry>
3463     <term>
3464       <emphasis remap='I'>fd_return</emphasis>
3465     </term>
3466     <listitem>
3467       <para>
3468 Returns the file descriptors.
3469 <!-- .ds Cn file descriptors -->
3470       </para>
3471     </listitem>
3472   </varlistentry>
3473   <varlistentry>
3474     <term>
3475       <emphasis remap='I'>count_return</emphasis>
3476     </term>
3477     <listitem>
3478       <para>
3479 Returns the number of (Cn.
3480     </para>
3481   </listitem>
3482   </varlistentry>
3483 </variablelist>
3484 <para>
3485 <!-- .LP -->
3486 <!-- .eM -->
3487 The
3488 <xref linkend='XInternalConnectionNumbers' xrefstyle='select: title'/>
3489 function returns a list of the file descriptors for all internal
3490 connections currently open for the specified display.
3491 When the allocated list is no longer needed,
3492 free it by using
3493 <xref linkend='XFree' xrefstyle='select: title'/>.
3494 This functions returns a nonzero status if the list is successfully allocated;
3495 otherwise, it returns zero.
3496 </para>
3497 </sect1>
3498 </chapter>