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