doc/xtrans.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
   3                       "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
   4 [
   5 <!ENTITY % defs SYSTEM "defs.ent"> %defs;
   6 ]>
   7
   8 <!-- lifted from troff+ms+XMan by doclifter -->
   9 <book id="xtrans">
  10
  11 <bookinfo>
  12    <title>X Transport Interface</title>
  13    <subtitle>X Consortium Standard</subtitle>
  14    <authorgroup>
  15      <author>
  16        <firstname>Stuart</firstname><surname>Anderson</surname>
  17        <affiliation><orgname>NCR Corporation</orgname></affiliation>
  18      </author>
  19      <othercredit><firstname>Ralph</firstname><surname>Mor</surname>
  20        <affiliation><orgname>X Consortium</orgname></affiliation>
  21      </othercredit>
  22      <othercredit><firstname>Alan</firstname><surname>Coopersmith</surname>
  23        <affiliation><orgname>Oracle Corp.</orgname></affiliation>
  24      </othercredit>
  25    </authorgroup>
  26    <releaseinfo>X Version 11, Release &fullrelvers;</releaseinfo>
  27    <releaseinfo>Version 0.7</releaseinfo>
  28    <copyright><year>1993</year><year>1994</year>
  29      <holder>NCR Corporation - Dayton, Ohio, USA</holder>
  30    </copyright>
  31
  32 <legalnotice>
  33 <para>
  34 All Rights Reserved
  35 </para>
  36 <para>
  37 Permission to use, copy, modify, and distribute this software and its
  38 documentation for any purpose and without fee is hereby granted, provided
  39 that the above copyright notice appear in all copies and that both that
  40 copyright notice and this permission notice appear in supporting
  41 documentation, and that the name NCR not be used in advertising
  42 or publicity pertaining to distribution of the software without specific,
  43 written prior permission.  NCR makes no representations about the
  44 suitability of this software for any purpose.  It is provided "as is"
  45 without express or implied warranty.
  46 </para>
  47 <para>
  48 NCR DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
  49 INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN
  50 NO EVENT SHALL NCR BE LIABLE FOR ANY SPECIAL, INDIRECT OR
  51 CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
  52 OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
  53 NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
  54 CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  55 </para>
  56 </legalnotice>
  57
  58 <legalnotice>
  59 <para role="multiLicensing">
  60 Copyright &copy; 1993, 1994, 2002 The Open Group
  61 </para>
  62 <para>
  63 Permission is hereby granted, free of charge, to any person obtaining a copy
  64 of this software and associated documentation files (the &ldquo;Software&rdquo;), to deal
  65 in the Software without restriction, including without limitation the rights
  66 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  67 copies of the Software, and to permit persons to whom the Software is
  68 furnished to do so, subject to the following conditions:
  69 </para>
  70 <para>
  71 The above copyright notice and this permission notice shall be included in
  72 all copies or substantial portions of the Software.
  73 </para>
  74 <para>
  75 THE SOFTWARE IS PROVIDED &ldquo;AS IS&rdquo;, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  76 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  77 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
  78 OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
  79 AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  80 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  81 </para>
  82 <para>
  83 Except as contained in this notice, the name of The Open Group shall not be
  84 used in advertising or otherwise to promote the sale, use or other dealings
  85 in this Software without prior written authorization from The Open Group.
  86 </para>
  87 <para>
  88 X Window System is a trademark of The Open Group, Inc.
  89 </para>
  90 </legalnotice>
  91 </bookinfo>
  92
  93 <preface><title>The X Transport Interface</title>
  94 <para>
  95 Designed by Stuart Anderson (NCR) with help from Ralph Mor (X Consortium)
  96 </para>
  97
  98 <note><para>
  99 This documentation does not completely match the implementation in R6
 100 (as a result of some late changes made in the code). Specifically, support
 101 was added for font server cloning, and conditional compliation was introduced
 102 for client vs. server code.
 103 </para></note>
 104 </preface>
 105
 106 <chapter id='Purposes_and_Goals'>
 107 <title>Purposes and Goals</title>
 108
 109 <para>The X Transport Interface is intended to combine all system and
 110 transport specific code into a single place in the source tree. This API
 111 should be used by all libraries, clients and servers of the X Window System.
 112 Use of this API should allow the addition of new types of transports and
 113 support for new platforms without making any changes to the source except
 114 in the X Transport Interface code.</para>
 115 <para>This interface should solve the problem of multiple
 116 <code>#ifdef TRANSPORT</code> and <code>#ifdef PLATFORM</code>
 117 statements scattered throughout the source tree.</para>
 118 <para>This interface should provide enough functionality to support all
 119 types of protocols, including connection oriented protocols such as X11 and
 120 FS, and connection-less oriented protocols such as XDMCP.</para>
 121
 122 </chapter>
 123
 124 <chapter id='Overview_of_the_Interface'>
 125 <title>Overview of the Interface</title>
 126
 127 <para>
 128 The interface provides an API for use by applications. The functions in
 129 this API perform work that is common to all transports and systems, such
 130 as parsing an address into a host and port number. The functions in this
 131 API call transport specific functions that are contained in a table whose
 132 contents are defined at compile time. This table contains an entry for each
 133 type of transport. Each entry is a record containing mostly pointers to
 134 function that implements the interface for the given transport.
 135 </para>
 136 <para>
 137 This API does not provide an abstraction for <function>select()</function>
 138 or <function>poll()</function>.
 139 These functions are themselves transport independent, so an additional
 140 interface is not needed for these functions. It is also unclear how such
 141 an interface would affect performance.
 142 </para>
 143 </chapter>
 144
 145 <chapter id='Definition_of_Address_Specification_Format'>
 146 <title>Definition of Address Specification Format</title>
 147
 148 <para>
 149 Addresses are specified in the following syntax,
 150
 151 <synopsis>
 152 <replaceable>protocol</replaceable>/<replaceable>host</replaceable>:<replaceable>port</replaceable>
 153 </synopsis>
 154
 155 where <replaceable>protocol</replaceable> specifies a protocol family
 156 or an alias for a protocol family. A definition of common protocol
 157 families is given in a later section.
 158 </para>
 159 <para>
 160 The <replaceable>host</replaceable> part specifies the name of a host or other
 161 transport dependent entity that could be interpreted as a Network Service Access Point
 162 (NSAP).
 163 </para>
 164 <para>
 165 The <replaceable>port</replaceable> part specifies the name of a Transport Service
 166 Access Point (TSAP). The format of the TSAP is defined by the underlying transport
 167 implementation, but it is represented using a string format when it is
 168 part of an address.
 169 </para>
 170 </chapter>
 171
 172 <chapter id='Internal_Data_Structures'>
 173 <title>Internal Data Structures</title>
 174 <para>
 175 There are two major data structures associated with the transport
 176 independent portion of this interface.  Additional data structures
 177 may be used internally by each transport.
 178 </para>
 179 <sect1 id='Xtransport'>
 180 <title>Xtransport</title>
 181 <para>
 182 Each transport supported has an entry in the transport table. The transport
 183 table is an array of Xtransport records. Each record contains all the entry
 184 points for a single transport. This record is defined as:
 185 </para>
 186
 187 <synopsis>
 188 typedef struct _Xtransport {
 189
 190     char *TransName;
 191     int  flags;
 192
 193     XtransConnInfo (*OpenCOTSClient)(
 194     struct _Xtransport *,     /* transport */
 195     char     *,     /* protocol */
 196     char     *,     /* host */
 197     char     *      /* port */
 198     );
 199
 200     XtransConnInfo (*OpenCOTSServer)(
 201     struct _Xtransport *,     /* transport */
 202     char *,     /* protocol */
 203     char *,     /* host */
 204     char *      /* port */
 205     );
 206
 207     XtransConnInfo (*OpenCLTSClient)(
 208     struct _Xtransport *,     /* transport */
 209     char *,               /* protocol */
 210     char *,               /* host */
 211     char *               /* port */
 212     );
 213
 214     XtransConnInfo (*OpenCLTSServer)(
 215      struct _Xtransport *,   /* transport */
 216      char *,     /* protocol */
 217      char *,     /* host */
 218      char *     /* port */
 219     );
 220
 221     int     (*SetOption)(
 222      XtransConnInfo,          /* connection */
 223      int,               /* option */
 224      int               /* arg */
 225     );
 226
 227     int     (*CreateListener)(
 228      XtransConnInfo,          /* connection */
 229      char *,               /* port */
 230      int               /* flags */
 231     );
 232
 233     int     (*ResetListener)(
 234      XtransConnInfo          /* connection */
 235     );
 236
 237     XtransConnInfo (*Accept)(
 238      XtransConnInfo          /* connection */
 239     );
 240
 241     int     (*Connect)(
 242      XtransConnInfo,          /* connection */
 243      char *,               /* host */
 244      char *               /* port */
 245     );
 246
 247     int     (*BytesReadable)(
 248      XtransConnInfo,          /* connection */
 249      BytesReadable_t *     /* pend */
 250     );
 251
 252     int     (*Read)(
 253      XtransConnInfo,          /* connection */
 254      char *,               /* buf */
 255      int               /* size */
 256     );
 257
 258     int     (*Write)(
 259      XtransConnInfo,          /* connection */
 260      char *,               /* buf */
 261      int               /* size */
 262     );
 263
 264     int     (*Readv)(
 265      XtransConnInfo,          /* connection */
 266      struct iovec *,          /* buf */
 267      int               /* size */
 268     );
 269
 270     int     (*Writev)(
 271      XtransConnInfo,          /* connection */
 272      struct iovec *,          /* buf */
 273      int               /* size */
 274     );
 275
 276     int     (*Disconnect)(
 277      XtransConnInfo          /* connection */
 278     );
 279
 280     int     (*Close)(
 281      XtransConnInfo          /* connection */
 282     );
 283
 284 } Xtransport;
 285 </synopsis>
 286
 287 <para>
 288 The <structfield>flags</structfield> field can contain an OR of
 289 the following masks:
 290 <variablelist>
 291   <varlistentry>
 292     <term><symbol>TRANS_ALIAS</symbol></term>
 293     <listitem><para>
 294 indicates that this record is providing an alias, and should
 295 not be used to create a listener.
 296       </para></listitem>
 297   </varlistentry>
 298   <varlistentry>
 299     <term><symbol>TRANS_LOCAL</symbol></term>
 300     <listitem><para>
 301 indicates that this is a <symbol>LOCALCONN</symbol> transport.
 302     </para></listitem>
 303   </varlistentry>
 304   <varlistentry>
 305     <term><symbol>TRANS_ABSTRACT</symbol></term>
 306     <listitem><para>
 307 indicates that a local connection transport uses the abstract socket namespace.
 308     </para></listitem>
 309   </varlistentry>
 310 </variablelist>
 311 </para>
 312
 313 <para>
 314 Some additional flags may be set in the <structfield>flags</structfield>
 315 field by the library while it is running:
 316 <variablelist>
 317   <varlistentry>
 318     <term><symbol>TRANS_DISABLED</symbol></term>
 319     <listitem><para>
 320 indicates that this transport has been disabled.
 321     </para></listitem>
 322   </varlistentry>
 323   <varlistentry>
 324     <term><symbol>TRANS_NOLISTEN</symbol></term>
 325     <listitem><para>
 326 indicates that servers should not open new listeners using this transport.
 327     </para></listitem>
 328   </varlistentry>
 329   <varlistentry>
 330     <term><symbol>TRANS_NOUNLINK</symbol></term>
 331     <listitem><para>
 332 set by a transport backend to indicate that the endpoints for its connection
 333 should not be unlinked.
 334     </para></listitem>
 335   </varlistentry>
 336 </variablelist>
 337 </para>
 338 </sect1>
 339
 340 <sect1 id='XtransConnInfo'>
 341 <title>XtransConnInfo</title>
 342 <para>
 343 Each connection will have an opaque <structname>XtransConnInfo</structname>
 344 transport connection
 345 object allocated for it. This record contains information specific to the
 346 connection. The record is defined as:
 347
 348 <synopsis>
 349 typedef struct _XtransConnInfo *XtransConnInfo;
 350
 351 struct _XtransConnInfo {
 352     struct _Xtransport     *transptr;
 353     char     *priv;
 354     int          flags;
 355     int          fd;
 356     int          family;
 357     char     *addr;
 358     int          addrlen;
 359     char     *peeraddr;
 360     int          peeraddrlen;
 361 };
 362 </synopsis>
 363 </para>
 364 </sect1>
 365 </chapter>
 366
 367 <chapter id='Exposed_Transport_Independent_API'>
 368 <title>Exposed Transport Independent API</title>
 369
 370 <para>
 371 This API is included in each library and server that uses it. The API may
 372 be used by the library, but it is not added to the public API for that
 373 library. This interface is simply an implementation facilitator. This API
 374 contains a low level set of core primitives, and a few utility functions
 375 that are built on top of the primitives.  The utility functions exist to
 376 provide a more familiar interface that can be used to port existing code.
 377 </para>
 378 <para>
 379 A macro is defined in Xtrans.h for TRANS(func) that creates a unique function
 380 name depending on where the code is compiled. For example, when built for
 381 Xlib, TRANS(OpenCOTSClient) becomes <function>_X11TransOpenCOTSClient</function>.
 382 </para>
 383 <para>
 384 All failures are considered fatal, and the connection should be closed
 385 and re-established if desired. In most cases, however, the value of
 386 errno will be available for debugging purposes.
 387 </para>
 388 <sect1 id='Core_Interface_API'>
 389 <title>Core Interface API</title>
 390 <itemizedlist mark='bullet'>
 391   <listitem>
 392     <para>
 393 XtransConnInfo TRANS(OpenCOTSClient)(char *address)
 394     </para>
 395     <para>
 396 This function creates a Connection-Oriented Transport that is
 397 suitable for use by a client. The parameter <parameter>address</parameter>
 398 contains the full address of the server to which this endpoint will be connected.  This
 399 functions returns an opaque transport connection object on success, or
 400 NULL on failure.
 401     </para>
 402   </listitem>
 403   <listitem>
 404     <para>
 405 XtransConnInfo TRANS(OpenCOTSServer)(char *address)
 406     </para>
 407     <para>
 408 This function creates a Connection-Oriented Transport that is suitable
 409 for use by a server. The parameter <parameter>address</parameter> contains the
 410 full address to which this server will be bound. This functions returns an opaque
 411 transport connection object on success, or NULL on failure.
 412     </para>
 413   </listitem>
 414   <listitem>
 415     <para>
 416 XtransConnInfo TRANS(OpenCLTSClient)(char *address)
 417     </para>
 418     <para>
 419 This function creates a Connection-Less Transport that is suitable for
 420 use by a client. The parameter <parameter>address</parameter> contains the
 421 full address of the server to which this endpoint will be connected. This functions
 422 returns an opaque transport connection object on success, or NULL on failure.
 423     </para>
 424   </listitem>
 425   <listitem>
 426     <para>
 427 XtransConnInfo TRANS(OpenCLTSServer)(char *address)
 428     </para>
 429     <para>
 430 This function creates a Connection-Less Transport that is suitable for
 431 use by a server. The parameter <parameter>address</parameter> contains the
 432 full address to which this server will be bound. This functions returns an opaque
 433 transport connection object on success, or NULL on failure.
 434     </para>
 435   </listitem>
 436   <listitem>
 437     <para>
 438 int TRANS(SetOption)(XtransConnInfo connection, int option, int arg)
 439     </para>
 440     <para>
 441 This function sets transport options, similar to the way
 442 <function>setsockopt()</function> and <function>ioctl()</function> work.
 443 The parameter <parameter>connection</parameter> is an endpoint
 444 that was obtained from _XTransOpen*() functions. The parameter
 445 <parameter>option</parameter> contains the option that will be set. The actual
 446 values for option are defined in a later section. The parameter
 447 <parameter>arg</parameter> can be used to pass in an additional value that may
 448 be required by some options. This function return 0 on
 449 success and -1 on failure.
 450     </para>
 451     <note><para>
 452 Based on current usage, the complimentary function
 453 <function>TRANS(GetOption)</function> is not necessary.
 454     </para></note>
 455   </listitem>
 456   <listitem>
 457     <para>
 458 int TRANS(CreateListener)(XtransConnInfo connection, char *port, int flags)
 459     </para>
 460     <para>
 461 This function sets up the server endpoint for listening. The parameter
 462 <parameter>connection</parameter> is an endpoint that was obtained from
 463 <function>TRANS(OpenCOTSServer)()</function> or
 464 <function>TRANS(OpenCLTSServer)()</function>. The parameter
 465 <parameter>port</parameter> specifies the
 466 port to which this endpoint should be bound for listening. If port is NULL,
 467 then the transport may attempt to allocate any available TSAP for this
 468 connection. If the transport cannot support this, then this function will
 469 return a failure. The <parameter>flags</parameter> parameter can be set
 470 to <symbol>ADDR_IN_USE_ALLOWED</symbol> to allow the call to the underlying
 471 binding function to fail with a <errorname>EADDRINUSE</errorname> error
 472 without causing the <function>TRANS(CreateListener)</function>
 473 function itself to fail. This function return 0 on success and -1 on failure.
 474     </para>
 475   </listitem>
 476   <listitem>
 477     <para>
 478 int TRANS(ResetListener)(XtransConnInfo connection)
 479     </para>
 480     <para>
 481 When a server is restarted, certain listen ports may need to be reset.
 482 For example, unix domain needs to check that the file used for
 483 communication has not been deleted. If it has, it must be recreated.
 484 The parameter <parameter>connection</parameter> is an opened and bound
 485 endpoint that was obtained from <function>TRANS(OpenCOTSServer)()</function>
 486 and passed to <function>TRANS(CreateListener)()</function>.
 487 This function will return one of the following values:
 488 <symbol>TRANS_RESET_NOOP</symbol>,
 489 <symbol>TRANS_RESET_NEW_FD</symbol>, or
 490 <symbol>TRANS_RESET_FAILURE</symbol>.
 491     </para>
 492   </listitem>
 493   <listitem>
 494     <para>
 495 XtransConnInfo TRANS(Accept)(XtransConnInfo connection)
 496     </para>
 497     <para>
 498 Once a connection indication is received, this function can be called to
 499 accept the connection. The parameter <parameter>connection</parameter> is
 500 an opened and bound endpoint that was obtained from
 501 <function>TRANS(OpenCOTSServer)()</function> and passed to
 502 <function>TRANS(CreateListener)()</function>. This function will return a
 503 new opaque transport connection object upon success, NULL otherwise.
 504     </para>
 505   </listitem>
 506   <listitem>
 507     <para>
 508 int TRANS(Connect)(XtransConnInfo connection, char *address)
 509     </para>
 510     <para>
 511 This function creates a connection to a server. The parameter
 512 <parameter>connection</parameter> is an endpoint that was obtained
 513 from <function>TRANS(OpenCOTSClient)()</function>. The parameter
 514 <parameter>address</parameter> specifies the TSAP to which this endpoint
 515 should connect. If the
 516 protocol is included in the address, it will be ignored. This function
 517 return 0 on success and -1 on failure.
 518     </para>
 519   </listitem>
 520   <listitem>
 521     <para>
 522 int TRANS(BytesReadable)(XtransConnInfo connection, BytesReadable_t *pend);
 523     </para>
 524     <para>
 525 This function provides the same functionality as the BytesReadable macro.
 526     </para>
 527   </listitem>
 528   <listitem>
 529     <para>
 530 int TRANS(Read)(XtransConnInfo connection, char *buf, int size)
 531     </para>
 532     <para>
 533 This function will return the number of bytes requested on a COTS
 534 connection, and will return the minimum of the number bytes requested or
 535 the size of the incoming packet on a CLTS connection.
 536     </para>
 537   </listitem>
 538   <listitem>
 539     <para>
 540 int TRANS(Write)(XtransConnInfo connection, char *buf, int size)
 541     </para>
 542     <para>
 543 This function will write the requested number of bytes on a COTS
 544 connection, and will send a packet of the requested size on a CLTS connection.
 545     </para>
 546   </listitem>
 547   <listitem>
 548     <para>
 549 int TRANS(Readv)(XtransConnInfo connection, struct iovec *buf, int size)
 550     </para>
 551     <para>
 552 Similar to <function>TRANS(Read)()</function>.
 553     </para>
 554   </listitem>
 555   <listitem>
 556     <para>
 557   int TRANS(Writev)(XtransConnInfo connection, struct iovec *buf, int size)
 558     </para>
 559     <para>
 560 Similar to <function>TRANS(Write)()</function>.
 561     </para>
 562   </listitem>
 563   <listitem>
 564     <para>
 565 int TRANS(Disconnect)(XtransConnInfo connection)
 566     </para>
 567     <para>
 568 This function is used when an orderly disconnect is desired. This function
 569 breaks the connection on the transport. It is similar to the socket function
 570 <function>shutdown()</function>.
 571     </para>
 572   </listitem>
 573   <listitem>
 574     <para>
 575 int TRANS(Close)(XtransConnInfo connection)
 576     </para>
 577     <para>
 578 This function closes the transport, unbinds it, and frees all resources that
 579 was associated with the transport. If a <function>TRANS(Disconnect)</function>
 580 call was not made on the connection, a disorderly disconnect may occur.
 581     </para>
 582   </listitem>
 583   <listitem>
 584     <para>
 585 int TRANS(IsLocal)(XtransConnInfo connection)
 586     </para>
 587     <para>
 588 Returns TRUE if it is a local transport.
 589     </para>
 590   </listitem>
 591   <listitem>
 592     <para>
 593 int TRANS(GetMyAddr)(XtransConnInfo connection, int *familyp, int *addrlenp,
 594 Xtransaddr **addrp)
 595     </para>
 596     <para>
 597 This function is similar to
 598 <function>getsockname()</function>.
 599 This function will allocate space for the address, so it must be freed by
 600 the caller. Not all transports will have a valid address until a connection
 601 is established.  This function should not be used until the connection is
 602 established with
 603 <function>Connect()</function> or
 604 <function>Accept()</function>.
 605     </para>
 606   </listitem>
 607   <listitem>
 608     <para>
 609 int TRANS(GetPeerAddr)(XtransConnInfo connection, int *familyp, int *addrlenp,
 610 Xtransaddr **addrp)
 611     </para>
 612     <para>
 613 This function is similar to
 614 <function>getpeername()</function>.
 615 This function will allocate space for the address, so it must be freed by
 616 the caller. Not all transports will have a valid address until a connection
 617 is established.  This function should not be used until the connection is
 618 established with
 619 <function>Connect()</function> or
 620 <function>Accept()</function>.
 621     </para>
 622   </listitem>
 623   <listitem>
 624     <para>
 625 int TRANS(GetConnectionNumber)(XtransConnInfo connection)
 626     </para>
 627     <para>
 628 Returns the file descriptor associated with this transport.
 629     </para>
 630   </listitem>
 631   <listitem>
 632     <para>
 633 int TRANS(MakeAllCOTSServerListeners)(char *port, int *partial_ret,
 634 int *count_ret, XtransConnInfo **connections_ret)
 635     </para>
 636     <para>
 637 This function should be used by most servers. It will try to establish
 638 a COTS server endpoint for each transport listed in the transport table.
 639 <parameter>partial_ret</parameter> will be set to <symbol>True</symbol> if
 640 only a partial network could be created. <parameter>count_ret</parameter> is
 641 the number of transports returned, and <parameter>connections_ret</parameter>
 642 is the list of transports.
 643     </para>
 644   </listitem>
 645   <listitem>
 646     <para>
 647 int TRANS(MakeAllCLTSServerListeners)( char *port, int *partial_ret,
 648 int *count_ret, XtransConnInfo **connections_ret)
 649     </para>
 650     <para>
 651 This function should be used by most servers. It will try to establish a
 652 CLTS server endpoint for each transport listed in the transport table.
 653 <parameter>partial_ret</parameter> will be set to <symbol>True</symbol> if
 654 only a partial network could be created. <parameter>count_ret</parameter> is
 655 the number of transports returned, and <parameter>connections_ret</parameter>
 656 is the list of transports.
 657     </para>
 658   </listitem>
 659 </itemizedlist>
 660 </sect1>
 661
 662 <sect1 id='Utility_API'>
 663 <title>Utility API</title>
 664 <para>
 665 This section describes a few useful functions that have been implemented on
 666 top of the Core Interface API.  These functions are being provided as a
 667 convenience.
 668 </para>
 669 <itemizedlist mark='bullet'>
 670   <listitem>
 671     <para>
 672 int TRANS(ConvertAddress)(int *familyp, int *addrlenp, Xtransaddr *addrp)
 673     </para>
 674     <para>
 675 This function converts a sockaddr based address to an X authorization based
 676 address (ie AF_INET, AF_UNIX to the X protocol definition (ie FamilyInternet,
 677 FamilyLocal)).
 678     </para>
 679   </listitem>
 680 </itemizedlist>
 681 </sect1>
 682 </chapter>
 683
 684 <chapter id='Transport_Option_Definition'>
 685 <title>Transport Option Definition</title>
 686 <para>
 687 The following options are defined for the
 688 <function>TRANS(SetOption)()</function>
 689  function. If an OS or transport does not support any of these options,
 690 then it will silently ignore the option.
 691 </para>
 692
 693 <itemizedlist mark='bullet'>
 694   <listitem>
 695     <para>
 696 <symbol>TRANS_NONBLOCKING</symbol>
 697     </para>
 698     <para>
 699 This option controls the blocking mode of the connection. If the argument
 700 is set to 1, then the connection will be set to blocking. If the argument
 701 is set to 0, then the connection will be set to non- blocking.
 702     </para>
 703   </listitem>
 704   <listitem>
 705     <para>
 706 <symbol>TRANS_CLOSEONEXEC</symbol>
 707     </para>
 708     <para>
 709 This option determines what will happen to the connection when an exec is
 710 encountered. If the argument is set to 1, then the connection will be
 711 closed when an exec occurs. If the argument is set to 0, then the
 712 connection will not be closed when an exec occurs.
 713     </para>
 714   </listitem>
 715 </itemizedlist>
 716 </chapter>
 717
 718 <chapter id='Hidden_Transport_Dependent_API'>
 719 <title>Hidden Transport Dependent API</title>
 720 <para>
 721 The hidden transport dependent functions are placed in the Xtransport record.
 722 These function are similar to the Exposed Transport Independent API, but
 723 some of the parameters and return values are slightly different.  Stuff like
 724 the <code>#ifdef SUNSYSV</code> should be handled inside these functions.
 725 </para>
 726
 727 <itemizedlist mark='bullet'>
 728   <listitem>
 729     <para>
 730 XtransConnInfo *OpenCOTSClient (
 731 struct _Xtransport *thistrans, char *protocol, char *host, char *port)
 732     </para>
 733     <para>
 734 This function creates a Connection-Oriented Transport. The parameter
 735 <parameter>thistrans</parameter>
 736 points to an Xtransport entry in the transport table. The parameters
 737 <parameter>protocol</parameter>,
 738 <parameter>host</parameter>,  and
 739 <parameter>port</parameter>, point to strings containing the corresponding
 740 parts of the address that was passed into <function>TRANS(OpenCOTSClient)()</function>.
 741 This function must allocate and initialize the contents of the XtransConnInfo
 742 structure that is returned by this function. This function will open the
 743 transport, and bind it into the transport namespace if applicable. The local
 744 address portion of the XtransConnInfo structure will also be filled in by
 745 this function.
 746     </para>
 747   </listitem>
 748   <listitem>
 749     <para>
 750 XtransConnInfo *OpenCOTSServer (
 751 struct _Xtransport *thistrans, char *protocol, char *host, char *port)
 752     </para>
 753     <para>
 754 This function creates a Connection-Oriented Transport. The parameter
 755 <parameter>thistrans</parameter>
 756 points to an Xtransport entry in the transport table. The
 757 parameters
 758 <parameter>protocol</parameter>,
 759 <parameter>host</parameter>, and
 760 <parameter>port</parameter> point to strings containing the
 761 corresponding parts of the address that was passed into
 762 <function>TRANS(OpenCOTSClient)()</function>.
 763 This function must allocate and initialize the contents of the
 764 XtransConnInfo structure that is returned by this function. This function
 765 will open the transport.
 766     </para>
 767   </listitem>
 768   <listitem>
 769     <para>
 770 XtransConnInfo *OpenCLTSClient (
 771 struct _Xtransport *thistrans, char *protocol, char *host, char *port)
 772     </para>
 773     <para>
 774 This function creates a Connection-Less Transport. The parameter
 775 <parameter>thistrans</parameter>
 776 points to an Xtransport entry in the transport table. The parameters
 777 <parameter>protocol</parameter>,
 778 <parameter>host</parameter>, and
 779 <parameter>port</parameter> point to strings containing the
 780 corresponding parts of the address that was passed into
 781 <function>TRANS(OpenCOTSClient)()</function>.
 782 This function must allocate and initialize the contents of the XtransConnInfo
 783 structure that is returned by this function. This function will open the
 784 transport, and bind it into the transport namespace if applicable. The
 785 local address portion of the XtransConnInfo structure will also be filled
 786 in by this function.
 787     </para>
 788   </listitem>
 789   <listitem>
 790     <para>
 791 XtransConnInfo *OpenCLTSServer (
 792 struct _Xtransport *thistrans, char *protocol, char *host, char *port)
 793     </para>
 794     <para>
 795 This function creates a Connection-Less Transport. The parameter
 796 <parameter>thistrans</parameter>
 797 points to an Xtransport entry in the transport table. The  parameters
 798 <parameter>protocol</parameter>,
 799 <parameter>host</parameter>, and
 800 <parameter>port</parameter> point to strings containing the
 801 corresponding parts of the address that was passed into
 802 <function>TRANS(OpenCOTSClient)()</function>.
 803 This function must allocate and initialize the contents of the
 804 XtransConnInfo structure that is returned by this function. This
 805 function will open the transport.
 806     </para>
 807   </listitem>
 808   <listitem>
 809     <para>
 810 int SetOption (struct _Xtransport *thistrans, int option, int arg)
 811     </para>
 812     <para>
 813 This function provides a transport dependent way of implementing the
 814 options defined by the X Transport Interface. In the current prototype,
 815 this function is not being used, because all of the options defined so far
 816 are transport independent. This function will have to be used if a radically
 817 different transport type is added, or a transport dependent option is defined.
 818     </para>
 819   </listitem>
 820   <listitem>
 821     <para>
 822 int CreateListener (struct _Xtransport *thistrans, char *port, int flags )
 823     </para>
 824     <para>
 825 This function takes a transport endpoint opened for a server, and sets it
 826 up to listen for incoming connection requests. The parameter
 827 <parameter>port</parameter>
 828 contains the port portion of the address that was passed to the Open function.
 829 The parameter <parameter>flags</parameter> should be set to
 830 <symbol>ADDR_IN_USE_ALLOWED</symbol> if the underlying transport endpoint
 831 may be already bound and this should not be considered
 832 as an error. Otherwise flags should be set to 0. This is used by IPv6 code,
 833 where the same socket can be bound to both an IPv6 address and then to a
 834 IPv4 address.  This function will bind the transport into the transport
 835 name space if applicable, and fill in the local address portion of the
 836 XtransConnInfo structure. The transport endpoint will then be set to
 837 listen for incoming connection requests.
 838     </para>
 839   </listitem>
 840   <listitem>
 841     <para>
 842 int ResetListener (struct _Xtransport *thistrans)
 843     </para>
 844     <para>
 845 This function resets the transport for listening.
 846     </para>
 847   </listitem>
 848   <listitem>
 849     <para>
 850  XtransConnInfo Accept(struct _Xtransport *thistrans)
 851     </para>
 852     <para>
 853 This function creates a new transport endpoint as a result of an
 854 incoming connection request. The parameter
 855 <parameter>thistrans</parameter> is the endpoint
 856 that was opened for listening by the server. The new endpoint is
 857 opened and bound into the transport’s namespace. A XtransConnInfo
 858 structure describing the new endpoint is returned from this function
 859     </para>
 860   </listitem>
 861   <listitem>
 862     <para>
 863 int Connect(struct _Xtransport *thistrans, char *host, char *port )
 864     </para>
 865     <para>
 866 This function establishes a connection to a server. The parameters
 867 <parameter>host</parameter>  and
 868 <parameter>port</parameter>
 869 describe the server to which the connection should be
 870 established. The connection will be established so that
 871 <function>Read()</function> and
 872 <function>Write()</function> call can be made.
 873     </para>
 874   </listitem>
 875   <listitem>
 876     <para>
 877 int BytesReadable(struct _Xtransport *thistrans, BytesReadable_t *pend )
 878     </para>
 879     <para>
 880 This function replaces the
 881 <function>BytesReadable()</function>
 882 macro. This allows each transport to have it’s own mechanism for determining
 883 how much data is ready to be read.
 884     </para>
 885   </listitem>
 886   <listitem>
 887     <para>
 888 int Read(struct _Xtransport *thistrans, char *buf, int size )
 889     </para>
 890     <para>
 891 This function reads size bytes into buf from the connection.
 892     </para>
 893   </listitem>
 894   <listitem>
 895     <para>
 896 int Write(struct _Xtransport *thistrans, char *buf, int size )
 897     </para>
 898     <para>
 899 This function writes size bytes from buf to the connection.
 900     </para>
 901   </listitem>
 902   <listitem>
 903     <para>
 904 int Readv(struct _Xtransport *thistrans, struct iovec *buf, int size )
 905     </para>
 906     <para>
 907 This function performs a <function>readv()</function> on the connection.
 908     </para>
 909   </listitem>
 910   <listitem>
 911     <para>
 912 int Writev(struct _Xtransport *thistrans, struct iovec *buf, int size )
 913     </para>
 914     <para>
 915 This function performs a <function>writev()</function> on the connection.
 916     </para>
 917   </listitem>
 918   <listitem>
 919     <para>
 920 int Disconnect(struct _Xtransport *thistrans)
 921     </para>
 922     <para>
 923 This function initiates an orderly shutdown of a connection. If a
 924 transport does not distinguish between orderly and disorderly
 925 disconnects, then a call to this function will have no affect.
 926     </para>
 927   </listitem>
 928   <listitem>
 929     <para>
 930 int Close(struct _Xtransport *thistrans)
 931     </para>
 932     <para>
 933 This function will break the connection, and close the endpoint.
 934     </para>
 935   </listitem>
 936 </itemizedlist>
 937 </chapter>
 938 <chapter id='Configuration'>
 939 <title>Configuration</title>
 940
 941 <para>
 942 The implementation of each transport can be platform specific. It is expected
 943 that existing connection types such as <symbol>TCPCONN</symbol>,
 944 <symbol>UNIXCONN</symbol>, <symbol>LOCALCONN</symbol>, and
 945 <symbol>STREAMSCONN</symbol> will be replaced with flags for each
 946 possible transport type.
 947 </para>
 948 <para>
 949 In X11R6, the below flags to enable transport types were set in
 950 <symbol>ConnectionFlags</symbol> in the <filename>vendor.cf</filename> or
 951 <filename>site.def</filename> config files.
 952 </para>
 953 <para>
 954 In X11R7 modular releases, these flags are set when running
 955 <filename>configure</filename> scripts which include the
 956 <function>XTRANS_CONNECTION_FLAGS</function> macro from
 957 <filename>xtrans.m4</filename>.
 958 </para>
 959
 960 <informaltable frame='topbot'>
 961   <tgroup cols='3' align='left' colsep='0' rowsep='0'>
 962     <colspec colname='define' colwidth='1.0*' />
 963     <colspec colname='enable' colwidth='2.0*' />
 964     <colspec colname='desc'   colwidth='2.0*'/>
 965     <thead>
 966       <row rowsep='1'>
 967         <entry><code>#define</code></entry>
 968         <entry>configure flag</entry>
 969         <entry>Description</entry>
 970       </row>
 971     </thead>
 972     <tbody>
 973       <row>
 974         <entry><symbol>TCPCONN</symbol></entry>
 975         <entry><option>--enable-tcp-transport</option></entry>
 976         <entry>
 977         Enables the INET (IPv4) Domain Socket based transport
 978         </entry>
 979       </row>
 980       <row>
 981         <entry><symbol>IPv6</symbol></entry>
 982         <entry><option>--enable-ipv6</option></entry>
 983         <entry>
 984         Extends <symbol>TCPCONN</symbol> to enable IPv6 Socket based transport
 985         </entry>
 986       </row>
 987       <row>
 988         <entry><symbol>UNIXCONN</symbol></entry>
 989         <entry><option>--enable-unix-transport</option></entry>
 990         <entry>
 991         Enables the UNIX Domain Socket based transport
 992         </entry>
 993       </row>
 994       <row>
 995         <entry><symbol>STREAMSCONN</symbol></entry>
 996         <entry><emphasis>Not available in X11R7</emphasis></entry>
 997         <entry>
 998         Enables the TLI based transports
 999         </entry>
1000       </row>
1001       <row>
1002         <entry><symbol>LOCALCONN</symbol></entry>
1003         <entry><option>--enable-local-transport</option></entry>
1004         <entry>
1005         Enables the SYSV Local connection transports
1006         </entry>
1007       </row>
1008       <row>
1009         <entry><symbol>DNETCONN</symbol></entry>
1010         <entry><emphasis>Not available in X11R7</emphasis></entry>
1011         <entry>
1012         Enables the DECnet transports
1013         </entry>
1014       </row>
1015     </tbody>
1016   </tgroup>
1017 </informaltable>
1018
1019
1020 </chapter>
1021
1022 <chapter id='Transport_Specific_Definitions'>
1023 <title>Transport Specific Definitions</title>
1024
1025 <informaltable frame='all' colsep='1' rowsep='1'>
1026   <tgroup cols='4' align='center'>
1027     <colspec colname='c1' colwidth='1.0*'/>
1028     <colspec colname='c2' colwidth='1.0*'/>
1029     <colspec colname='c3' colwidth='3.0*'/>
1030     <colspec colname='c4' colwidth='2.0*'/>
1031     <thead>
1032       <row>
1033         <entry morerows="1">Protocol Family</entry>
1034         <entry namest="c2" nameend="c4"  align='center'>Address Component</entry>
1035       </row>
1036       <row>
1037         <entry align='center'>protocol</entry>
1038         <entry align='center'>host</entry>
1039         <entry align='center'>port</entry>
1040       </row>
1041     </thead>
1042     <tbody>
1043       <row>
1044         <entry>Internet</entry>
1045         <entry>inet inet6 tcp udp</entry>
1046         <entry>name of an internet addressable host</entry>
1047         <entry>string containing the name of a service or a valid port number.  Example: "xserver0", "7100"</entry>
1048       </row>
1049       <row>
1050         <entry>DECnet</entry>
1051         <entry>decnet</entry>
1052         <entry>name of a DECnet addressable host</entry>
1053         <entry>string containing the complete name of the object.  Example: "X$X0"</entry>
1054       </row>
1055       <row>
1056         <entry>NETware</entry>
1057         <entry>ipx</entry>
1058         <entry>name of a NETware addressable host</entry>
1059         <entry>Not sure of the specifics yet.</entry>
1060       </row>
1061       <row>
1062         <entry>OSI</entry>
1063         <entry>osi</entry>
1064         <entry>name of an OSI adressable host.</entry>
1065         <entry>Not sure of the specifics yet.</entry>
1066       </row>
1067       <row>
1068         <entry>Local</entry>
1069         <entry>local pts named sco isc</entry>
1070         <entry>(ignored)</entry>
1071         <entry>String containing the port name, ie "xserver0", "fontserver0".</entry>
1072       </row>
1073     </tbody>
1074   </tgroup>
1075 </informaltable>
1076
1077 </chapter>
1078
1079 <chapter id='Implementation_Notes'>
1080 <title>Implementation Notes</title>
1081 <para>
1082 This section refers to the prototype implementation that is being developed
1083 concurrently with this document. This prototype has been able to flush out many
1084 details and problems as the specification was being developed.
1085 </para>
1086 <para>
1087 In X11R6, all of the source code for this interface was located in
1088 <filename>xc/lib/xtrans</filename>.
1089 </para>
1090 <para>
1091 In X11R7, all of the source code for this interface is delivered via
1092 the <systemitem>lib/libxtrans</systemitem> modular package from X.Org,
1093 and is installed under
1094 <filename><replaceable>${prefix}</replaceable>/X11/Xtrans</filename>
1095 so that other modules may find it when they build.
1096 </para>
1097 <para>
1098 All functions names in the source are of the format
1099 <function>TRANS(func)()</function>. The
1100 <function>TRANS()</function>
1101 macro is defined as
1102 <programlisting language="C">
1103 #if (__STDC__ &amp;&amp; !defined(UNIXCPP)) || defined(ANSICPP)
1104 #define TRANS(func) _PROTOCOLTrans##func
1105 #else
1106 #define TRANS(func) _PROTOCOLTrans/**/func
1107 #endif
1108 </programlisting>
1109 </para>
1110
1111 <para>
1112 <symbol>PROTOCOL</symbol> will be uniquely defined in each directory
1113 where this code is compiled.
1114 <symbol>PROTOCOL</symbol> will be defined to be the name of the protocol
1115 that is implemented by the library or server, such as X11, FS, and ICE.
1116 </para>
1117
1118 <para>
1119 All libraries and servers that use the X Transport Interface should have a new
1120 file called <filename><replaceable>TRANSPORT</replaceable>trans.c</filename>.
1121 This file will include the transports based on the configuration flags
1122 provided by the <filename>configure</filename> script. Below is an
1123 example <filename>xfstrans.c</filename> for the font server.
1124 </para>
1125
1126 <programlisting language="C">
1127 #include "config.h"
1128
1129 #define FONT_t 1
1130 #define TRANS_REOPEN 1
1131 #define TRANS_SERVER 1
1132
1133 #include &lt;X11/Xtrans/transport.c&gt;
1134 </programlisting>
1135 <para>
1136 The source files for this interface are listed below.
1137 </para>
1138
1139 <variablelist>
1140   <varlistentry>
1141     <term><filename>Xtrans.h</filename></term>
1142     <listitem><para>
1143 Function prototypes and defines for the Transport Independent API.
1144     </para></listitem>
1145   </varlistentry>
1146   <varlistentry>
1147     <term><filename>Xtransint.h</filename></term>
1148     <listitem><para>
1149 Used by the interface implementation only.
1150 Contains the internal data structures.
1151     </para></listitem>
1152   </varlistentry>
1153   <varlistentry>
1154     <term><filename>Xtranssock.c</filename></term>
1155     <listitem><para>
1156 Socket implementation of the Transport Dependent API.
1157     </para></listitem>
1158   </varlistentry>
1159   <varlistentry>
1160     <term><filename>Xtranstli.c</filename></term>
1161     <listitem><para>
1162 TLI implementation of the Transport Dependent API.
1163     </para></listitem>
1164   </varlistentry>
1165   <varlistentry>
1166     <term><filename>Xtransdnet.c</filename></term>
1167     <listitem><para>
1168 DECnet implementation of the Transport Dependent API.
1169     </para></listitem>
1170   </varlistentry>
1171   <varlistentry>
1172     <term><filename>Xtranslocal.c</filename></term>
1173     <listitem><para>
1174 Implementation of the Transport Dependent API for SYSV Local connections.
1175     </para></listitem>
1176   </varlistentry>
1177   <varlistentry>
1178     <term><filename>Xtrans.c</filename></term>
1179     <listitem><para>
1180 Exposed Transport Independent API Functions.
1181     </para></listitem>
1182   </varlistentry>
1183   <varlistentry>
1184     <term><filename>Xtransutil.c</filename></term>
1185     <listitem><para>
1186 Collection of Utility functions that use the X Transport Interface.
1187     </para></listitem>
1188   </varlistentry>
1189 </variablelist>
1190
1191
1192 <para>
1193 The file <filename>Xtransint.h</filename> contains much of the transport
1194 related code that was previously in <filename>Xlibint.h</filename> and
1195 <filename>Xlibnet.h</filename>.
1196 This will make the definitions available for all transport users. This
1197 should also obsolete the equivalent code in other libraries.
1198 </para>
1199
1200 </chapter>
1201 </book>