aboutsummaryrefslogtreecommitdiff
path: root/X11/xtrans/doc/xtrans.xml
blob: 0fb62eb05d34ea0fb5bd5b80f3d09683962547ef (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
                      "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[
<!ENTITY % defs SYSTEM "defs.ent"> %defs;
]>

<!-- lifted from troff+ms+XMan by doclifter -->
<book id="xtrans">

<bookinfo>
   <title>X Transport Interface</title>
   <subtitle>X Consortium Standard</subtitle>
   <releaseinfo>X Version 11, Release &fullrelvers;</releaseinfo>
   <authorgroup>
      <author>
         <firstname>Stuart</firstname><surname>Anderson</surname>
         <affiliation><orgname>NCR Corporation</orgname></affiliation>
      </author>
   </authorgroup>
   <othercredit><firstname>Ralph</firstname><surname>Mor</surname>
   <affiliation><orgname>X Consortium</orgname></affiliation>
   </othercredit>
   <othercredit><firstname>Alan</firstname><surname>Coopersmith</surname>
   <affiliation><orgname>Oracle Corp.</orgname></affiliation>
   </othercredit>
   <releaseinfo>Version 0.7</releaseinfo>

<legalnotice>
<para role="multiLicensing">
Copyright &copy; 1993, 1994 NCR Corporation - Dayton, Ohio, USA
</para>

<para>
All Rights Reserved
</para>

<para>
Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted, provided
that the above copyright notice appear in all copies and that both that
copyright notice and this permission notice appear in supporting
documentation, and that the name NCR not be used in advertising
or publicity pertaining to distribution of the software without specific,
written prior permission.  NCR makes no representations about the
suitability of this software for any purpose.  It is provided "as is"
without express or implied warranty.
</para>

<para>
NCR DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN
NO EVENT SHALL NCR BE LIABLE FOR ANY SPECIAL, INDIRECT OR
CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
</para>

</legalnotice>

<legalnotice>
<para role="multiLicensing">
Copyright &copy; 1993, 1994, 2002 The Open Group
</para>

<para>
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the &ldquo;Software&rdquo;), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
</para>

<para>
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
</para>

<para>
THE SOFTWARE IS PROVIDED &ldquo;AS IS&rdquo;, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
</para>

<para>
Except as contained in this notice, the name of The Open Group shall not be
used in advertising or otherwise to promote the sale, use or other dealings
in this Software without prior written authorization from The Open Group.
</para>

<para>
X Window System is a trademark of The Open Group, Inc.
</para>

</legalnotice>

</bookinfo>

<preface><title>The X Transport Interface</title>
<para>
Designed by Stuart Anderson (NCR) with help from Ralph Mor (X Consortium)
</para>

<note><para>
This documentation does not completely match the implementation in R6
(as a result of some late changes made in the code). Specifically, support
was added for font server cloning, and conditional compliation was introduced
for client vs. server code.
</para></note>
</preface>

<chapter id='purposes_and_goals'>
<title>Purposes and Goals</title>

<para>The X Transport Interface is intended to combine all system and
transport specific code into a single place in the source tree. This API
should be used by all libraries, clients and servers of the X Window System.
Use of this API should allow the addition of new types of transports and
support for new platforms without making any changes to the source except
in the X Transport Interface code.</para>
<para>This interface should solve the problem of multiple
<code>#ifdef TRANSPORT</code> and <code>#ifdef PLATFORM</code>
statements scattered throughout the source tree.</para>
<para>This interface should provide enough functionality to support all
types of protocols, including connection oriented protocols such as X11 and
FS, and connection-less oriented protocols such as XDMCP.</para>

</chapter>

<chapter id='overview_of_the_interface'>
<title>Overview of the Interface</title>

<para>
The interface provides an API for use by applications. The functions in
this API perform work that is common to all transports and systems, such
as parsing an address into a host and port number. The functions in this
API call transport specific functions that are contained in a table whose
contents are defined at compile time. This table contains an entry for each
type of transport. Each entry is a record containing mostly pointers to
function that implements the interface for the given transport.
</para>
<para>
This API does not provide an abstraction for <function>select()</function>
or <function>poll()</function>.
These functions are themselves transport independent, so an additional
interface is not needed for these functions. It is also unclear how such
an interface would affect performance.
</para>
</chapter>

<chapter id='definition_of_address_specification_format'>
<title>Definition of Address Specification Format</title>

<para>
Addresses are specified in the following syntax,

<synopsis>
<replaceable>protocol</replaceable>/<replaceable>host</replaceable>:<replaceable>port</replaceable>
</synopsis>

where <replaceable>protocol</replaceable> specifies a protocol family
or an alias for a protocol family. A definition of common protocol
families is given in a later section.
</para>
<para>
The <replaceable>host</replaceable> part specifies the name of a host or other
transport dependent entity that could be interpreted as a Network Service Access Point
(NSAP).
</para>
<para>
The <replaceable>port</replaceable> part specifies the name of a Transport Service
Access Point (TSAP). The format of the TSAP is defined by the underlying transport
implementation, but it is represented using a string format when it is
part of an address.
</para>
</chapter>

<chapter id='internal_data_structures'>
<title>Internal Data Structures</title>
<para>
There are two major data structures associated with the transport
independent portion of this interface.  Additional data structures
may be used internally by each transport.
</para>
<sect1 id="xtransport">
<title>Xtransport</title>
<para>
Each transport supported has an entry in the transport table. The transport
table is an array of Xtransport records. Each record contains all the entry
points for a single transport. This record is defined as:
</para>

<synopsis>
typedef struct _Xtransport {

    char *TransName;
    int  flags;

    XtransConnInfo (*OpenCOTSClient)(
    struct _Xtransport *,     /* transport */
    char     *,     /* protocol */
    char     *,     /* host */
    char     *      /* port */
    );

    XtransConnInfo (*OpenCOTSServer)(
    struct _Xtransport *,     /* transport */
    char *,     /* protocol */
    char *,     /* host */
    char *      /* port */
    );

    XtransConnInfo (*OpenCLTSClient)(
    struct _Xtransport *,     /* transport */
    char *,               /* protocol */
    char *,               /* host */
    char *               /* port */
    );

    XtransConnInfo (*OpenCLTSServer)(
     struct _Xtransport *,   /* transport */
     char *,     /* protocol */
     char *,     /* host */
     char *     /* port */
    );

    int     (*SetOption)(
     XtransConnInfo,          /* connection */
     int,               /* option */
     int               /* arg */
    );

    int     (*CreateListener)(
     XtransConnInfo,          /* connection */
     char *,               /* port */
     int               /* flags */
    );

    int     (*ResetListener)(
     XtransConnInfo          /* connection */
    );

    XtransConnInfo (*Accept)(
     XtransConnInfo          /* connection */
    );

    int     (*Connect)(
     XtransConnInfo,          /* connection */
     char *,               /* host */
     char *               /* port */
    );

    int     (*BytesReadable)(
     XtransConnInfo,          /* connection */
     BytesReadable_t *     /* pend */
    );

    int     (*Read)(
     XtransConnInfo,          /* connection */
     char *,               /* buf */
     int               /* size */
    );

    int     (*Write)(
     XtransConnInfo,          /* connection */
     char *,               /* buf */
     int               /* size */
    );

    int     (*Readv)(
     XtransConnInfo,          /* connection */
     struct iovec *,          /* buf */
     int               /* size */
    );

    int     (*Writev)(
     XtransConnInfo,          /* connection */
     struct iovec *,          /* buf */
     int               /* size */
    );

    int     (*Disconnect)(
     XtransConnInfo          /* connection */
    );

    int     (*Close)(
     XtransConnInfo          /* connection */
    );

} Xtransport;
</synopsis>

<para>
The <structfield>flags</structfield> field can contain an OR of
the following masks:
<variablelist>
  <varlistentry>
    <term><symbol>TRANS_ALIAS</symbol></term>
    <listitem><para>
indicates that this record is providing an alias, and should
not be used to create a listener.
      </para></listitem>
  </varlistentry>
  <varlistentry>
    <term><symbol>TRANS_LOCAL</symbol></term>
    <listitem><para>
indicates that this is a <symbol>LOCALCONN</symbol> transport.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term><symbol>TRANS_ABSTRACT</symbol></term>
    <listitem><para>
indicates that a local connection transport uses the abstract socket namespace.
    </para></listitem>
  </varlistentry>
</variablelist>
</para>

<para>
Some additional flags may be set in the <structfield>flags</structfield>
field by the library while it is running:
<variablelist>
  <varlistentry>
    <term><symbol>TRANS_DISABLED</symbol></term>
    <listitem><para>
indicates that this transport has been disabled.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term><symbol>TRANS_NOLISTEN</symbol></term>
    <listitem><para>
indicates that servers should not open new listeners using this transport.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term><symbol>TRANS_NOUNLINK</symbol></term>
    <listitem><para>
set by a transport backend to indicate that the endpoints for its connection
should not be unlinked.
    </para></listitem>
  </varlistentry>
</variablelist>
</para>
</sect1>

<sect1 id="xtransconninfo">
<title>XtransConnInfo</title>
<para>
Each connection will have an opaque <structname>XtransConnInfo</structname>
transport connection
object allocated for it. This record contains information specific to the
connection. The record is defined as:

<synopsis>
typedef struct _XtransConnInfo *XtransConnInfo;

struct _XtransConnInfo {
    struct _Xtransport     *transptr;
    char     *priv;
    int          flags;
    int          fd;
    int          family;
    char     *addr;
    int          addrlen;
    char     *peeraddr;
    int          peeraddrlen;
};
</synopsis>
</para>
</sect1>
</chapter>

<chapter id='exposed_transport_independent_api'>
<title>Exposed Transport Independent API</title>

<para>
This API is included in each library and server that uses it. The API may
be used by the library, but it is not added to the public API for that
library. This interface is simply an implementation facilitator. This API
contains a low level set of core primitives, and a few utility functions
that are built on top of the primitives.  The utility functions exist to
provide a more familiar interface that can be used to port existing code.
</para>
<para>
A macro is defined in Xtrans.h for TRANS(func) that creates a unique function
name depending on where the code is compiled. For example, when built for
Xlib, TRANS(OpenCOTSClient) becomes <function>_X11TransOpenCOTSClient</function>.
</para>
<para>
All failures are considered fatal, and the connection should be closed
and re-established if desired. In most cases, however, the value of
errno will be available for debugging purposes.
</para>
<sect1 id="core_interface_api">
<title>Core Interface API</title>
<itemizedlist mark='bullet'>
  <listitem>
    <para>
XtransConnInfo TRANS(OpenCOTSClient)(char *address)
    </para>
    <para>
This function creates a Connection-Oriented Transport that is
suitable for use by a client. The parameter <parameter>address</parameter>
contains the full address of the server to which this endpoint will be connected.  This
functions returns an opaque transport connection object on success, or
NULL on failure.
    </para>
  </listitem>
  <listitem>
    <para>
XtransConnInfo TRANS(OpenCOTSServer)(char *address)
    </para>
    <para>
This function creates a Connection-Oriented Transport that is suitable
for use by a server. The parameter <parameter>address</parameter> contains the
full address to which this server will be bound. This functions returns an opaque
transport connection object on success, or NULL on failure.
    </para>
  </listitem>
  <listitem>
    <para>
XtransConnInfo TRANS(OpenCLTSClient)(char *address)
    </para>
    <para>
This function creates a Connection-Less Transport that is suitable for
use by a client. The parameter <parameter>address</parameter> contains the
full address of the server to which this endpoint will be connected. This functions
returns an opaque transport connection object on success, or NULL on failure.
    </para>
  </listitem>
  <listitem>
    <para>
XtransConnInfo TRANS(OpenCLTSServer)(char *address)
    </para>
    <para>
This function creates a Connection-Less Transport that is suitable for
use by a server. The parameter <parameter>address</parameter> contains the
full address to which this server will be bound. This functions returns an opaque
transport connection object on success, or NULL on failure.
    </para>
  </listitem>
  <listitem>
    <para>
int TRANS(SetOption)(XtransConnInfo connection, int option, int arg)
    </para>
    <para>
This function sets transport options, similar to the way
<function>setsockopt()</function> and <function>ioctl()</function> work.
The parameter <parameter>connection</parameter> is an endpoint
that was obtained from _XTransOpen*() functions. The parameter
<parameter>option</parameter> contains the option that will be set. The actual
values for option are defined in a later section. The parameter
<parameter>arg</parameter> can be used to pass in an additional value that may
be required by some options. This function return 0 on
success and -1 on failure.
    </para>
    <note><para>
Based on current usage, the complimentary function
<function>TRANS(GetOption)</function> is not necessary.
    </para></note>
  </listitem>
  <listitem>
    <para>
int TRANS(CreateListener)(XtransConnInfo connection, char *port, int flags)
    </para>
    <para>
This function sets up the server endpoint for listening. The parameter
<parameter>connection</parameter> is an endpoint that was obtained from
<function>TRANS(OpenCOTSServer)()</function> or
<function>TRANS(OpenCLTSServer)()</function>. The parameter
<parameter>port</parameter> specifies the
port to which this endpoint should be bound for listening. If port is NULL,
then the transport may attempt to allocate any available TSAP for this
connection. If the transport cannot support this, then this function will
return a failure. The <parameter>flags</parameter> parameter can be set
to <symbol>ADDR_IN_USE_ALLOWED</symbol> to allow the call to the underlying
binding function to fail with a <errorname>EADDRINUSE</errorname> error
without causing the <function>TRANS(CreateListener)</function>
function itself to fail. This function return 0 on success and -1 on failure.
    </para>
  </listitem>
  <listitem>
    <para>
int TRANS(ResetListener)(XtransConnInfo connection)
    </para>
    <para>
When a server is restarted, certain listen ports may need to be reset.
For example, unix domain needs to check that the file used for
communication has not been deleted. If it has, it must be recreated.
The parameter <parameter>connection</parameter> is an opened and bound
endpoint that was obtained from <function>TRANS(OpenCOTSServer)()</function>
and passed to <function>TRANS(CreateListener)()</function>.
This function will return one of the following values:
<symbol>TRANS_RESET_NOOP</symbol>,
<symbol>TRANS_RESET_NEW_FD</symbol>, or
<symbol>TRANS_RESET_FAILURE</symbol>.
    </para>
  </listitem>
  <listitem>
    <para>
XtransConnInfo TRANS(Accept)(XtransConnInfo connection)
    </para>
    <para>
Once a connection indication is received, this function can be called to
accept the connection. The parameter <parameter>connection</parameter> is
an opened and bound endpoint that was obtained from
<function>TRANS(OpenCOTSServer)()</function> and passed to
<function>TRANS(CreateListener)()</function>. This function will return a
new opaque transport connection object upon success, NULL otherwise.
    </para>
  </listitem>
  <listitem>
    <para>
int TRANS(Connect)(XtransConnInfo connection, char *address)
    </para>
    <para>
This function creates a connection to a server. The parameter
<parameter>connection</parameter> is an endpoint that was obtained
from <function>TRANS(OpenCOTSClient)()</function>. The parameter
<parameter>address</parameter> specifies the TSAP to which this endpoint
should connect. If the
protocol is included in the address, it will be ignored. This function
return 0 on success and -1 on failure.
    </para>
  </listitem>
  <listitem>
    <para>
int TRANS(BytesReadable)(XtransConnInfo connection, BytesReadable_t *pend);
    </para>
    <para>
This function provides the same functionality as the BytesReadable macro.
    </para>
  </listitem>
  <listitem>
    <para>
int TRANS(Read)(XtransConnInfo connection, char *buf, int size)
    </para>
    <para>
This function will return the number of bytes requested on a COTS
connection, and will return the minimum of the number bytes requested or
the size of the incoming packet on a CLTS connection.
    </para>
  </listitem>
  <listitem>
    <para>
int TRANS(Write)(XtransConnInfo connection, char *buf, int size)
    </para>
    <para>
This function will write the requested number of bytes on a COTS
connection, and will send a packet of the requested size on a CLTS connection.
    </para>
  </listitem>
  <listitem>
    <para>
int TRANS(Readv)(XtransConnInfo connection, struct iovec *buf, int size)
    </para>
    <para>
Similar to <function>TRANS(Read)()</function>.
    </para>
  </listitem>
  <listitem>
    <para>
  int TRANS(Writev)(XtransConnInfo connection, struct iovec *buf, int size)
    </para>
    <para>
Similar to <function>TRANS(Write)()</function>.
    </para>
  </listitem>
  <listitem>
    <para>
int TRANS(Disconnect)(XtransConnInfo connection)
    </para>
    <para>
This function is used when an orderly disconnect is desired. This function
breaks the connection on the transport. It is similar to the socket function
<function>shutdown()</function>.
    </para>
  </listitem>
  <listitem>
    <para>
int TRANS(Close)(XtransConnInfo connection)
    </para>
    <para>
This function closes the transport, unbinds it, and frees all resources that
was associated with the transport. If a <function>TRANS(Disconnect)</function>
call was not made on the connection, a disorderly disconnect may occur.
    </para>
  </listitem>
  <listitem>
    <para>
int TRANS(IsLocal)(XtransConnInfo connection)
    </para>
    <para>
Returns TRUE if it is a local transport.
    </para>
  </listitem>
  <listitem>
    <para>
int TRANS(GetMyAddr)(XtransConnInfo connection, int *familyp, int *addrlenp,
Xtransaddr **addrp)
    </para>
    <para>
This function is similar to
<function>getsockname()</function>.
This function will allocate space for the address, so it must be freed by
the caller. Not all transports will have a valid address until a connection
is established.  This function should not be used until the connection is
established with
<function>Connect()</function> or
<function>Accept()</function>.
    </para>
  </listitem>
  <listitem>
    <para>
int TRANS(GetPeerAddr)(XtransConnInfo connection, int *familyp, int *addrlenp,
Xtransaddr **addrp)
    </para>
    <para>
This function is similar to
<function>getpeername()</function>.
This function will allocate space for the address, so it must be freed by
the caller. Not all transports will have a valid address until a connection
is established.  This function should not be used until the connection is
established with
<function>Connect()</function> or
<function>Accept()</function>.
    </para>
  </listitem>
  <listitem>
    <para>
int TRANS(GetConnectionNumber)(XtransConnInfo connection)
    </para>
    <para>
Returns the file descriptor associated with this transport.
    </para>
  </listitem>
  <listitem>
    <para>
int TRANS(MakeAllCOTSServerListeners)(char *port, int *partial_ret,
int *count_ret, XtransConnInfo **connections_ret)
    </para>
    <para>
This function should be used by most servers. It will try to establish
a COTS server endpoint for each transport listed in the transport table.
<parameter>partial_ret</parameter> will be set to <symbol>True</symbol> if
only a partial network could be created. <parameter>count_ret</parameter> is
the number of transports returned, and <parameter>connections_ret</parameter>
is the list of transports.
    </para>
  </listitem>
  <listitem>
    <para>
int TRANS(MakeAllCLTSServerListeners)( char *port, int *partial_ret,
int *count_ret, XtransConnInfo **connections_ret)
    </para>
    <para>
This function should be used by most servers. It will try to establish a
CLTS server endpoint for each transport listed in the transport table.
<parameter>partial_ret</parameter> will be set to <symbol>True</symbol> if
only a partial network could be created. <parameter>count_ret</parameter> is
the number of transports returned, and <parameter>connections_ret</parameter>
is the list of transports.
    </para>
  </listitem>
</itemizedlist>
</sect1>

<sect1 id="utility_api">
<title>Utility API</title>
<para>
This section describes a few useful functions that have been implemented on
top of the Core Interface API.  These functions are being provided as a
convenience.
</para>
<itemizedlist mark='bullet'>
  <listitem>
    <para>
int TRANS(ConvertAddress)(int *familyp, int *addrlenp, Xtransaddr *addrp)
    </para>
    <para>
This function converts a sockaddr based address to an X authorization based
address (ie AF_INET, AF_UNIX to the X protocol definition (ie FamilyInternet,
FamilyLocal)).
    </para>
  </listitem>
</itemizedlist>
</sect1>
</chapter>

<chapter id="transport_option_definition">
<title>Transport Option Definition</title>
<para>
The following options are defined for the
<function>TRANS(SetOption)()</function>
 function. If an OS or transport does not support any of these options,
then it will silently ignore the option.
</para>

<itemizedlist mark='bullet'>
  <listitem>
    <para>
<symbol>TRANS_NONBLOCKING</symbol>
    </para>
    <para>
This option controls the blocking mode of the connection. If the argument
is set to 1, then the connection will be set to blocking. If the argument
is set to 0, then the connection will be set to non- blocking.
    </para>
  </listitem>
  <listitem>
    <para>
<symbol>TRANS_CLOSEONEXEC</symbol>
    </para>
    <para>
This option determines what will happen to the connection when an exec is
encountered. If the argument is set to 1, then the connection will be
closed when an exec occurs. If the argument is set to 0, then the
connection will not be closed when an exec occurs.
    </para>
  </listitem>
</itemizedlist>
</chapter>

<chapter id="hidden_transport_dependent_api">
<title>Hidden Transport Dependent API</title>
<para>
The hidden transport dependent functions are placed in the Xtransport record.
These function are similar to the Exposed Transport Independent API, but
some of the parameters and return values are slightly different.  Stuff like
the <code>#ifdef SUNSYSV</code> should be handled inside these functions.
</para>

<itemizedlist mark='bullet'>
  <listitem>
    <para>
XtransConnInfo *OpenCOTSClient (
struct _Xtransport *thistrans, char *protocol, char *host, char *port)
    </para>
    <para>
This function creates a Connection-Oriented Transport. The parameter
<parameter>thistrans</parameter>
points to an Xtransport entry in the transport table. The parameters
<parameter>protocol</parameter>,
<parameter>host</parameter>,  and
<parameter>port</parameter>, point to strings containing the corresponding
parts of the address that was passed into <function>TRANS(OpenCOTSClient)()</function>.
This function must allocate and initialize the contents of the XtransConnInfo
structure that is returned by this function. This function will open the
transport, and bind it into the transport namespace if applicable. The local
address portion of the XtransConnInfo structure will also be filled in by
this function.
    </para>
  </listitem>
  <listitem>
    <para>
XtransConnInfo *OpenCOTSServer (
struct _Xtransport *thistrans, char *protocol, char *host, char *port)
    </para>
    <para>
This function creates a Connection-Oriented Transport. The parameter
<parameter>thistrans</parameter>
points to an Xtransport entry in the transport table. The
parameters
<parameter>protocol</parameter>,
<parameter>host</parameter>, and
<parameter>port</parameter> point to strings containing the
corresponding parts of the address that was passed into
<function>TRANS(OpenCOTSClient)()</function>.
This function must allocate and initialize the contents of the
XtransConnInfo structure that is returned by this function. This function
will open the transport.
    </para>
  </listitem>
  <listitem>
    <para>
XtransConnInfo *OpenCLTSClient (
struct _Xtransport *thistrans, char *protocol, char *host, char *port)
    </para>
    <para>
This function creates a Connection-Less Transport. The parameter
<parameter>thistrans</parameter>
points to an Xtransport entry in the transport table. The parameters
<parameter>protocol</parameter>,
<parameter>host</parameter>, and
<parameter>port</parameter> point to strings containing the
corresponding parts of the address that was passed into
<function>TRANS(OpenCOTSClient)()</function>.
This function must allocate and initialize the contents of the XtransConnInfo
structure that is returned by this function. This function will open the
transport, and bind it into the transport namespace if applicable. The
local address portion of the XtransConnInfo structure will also be filled
in by this function.
    </para>
  </listitem>
  <listitem>
    <para>
XtransConnInfo *OpenCLTSServer (
struct _Xtransport *thistrans, char *protocol, char *host, char *port)
    </para>
    <para>
This function creates a Connection-Less Transport. The parameter
<parameter>thistrans</parameter>
points to an Xtransport entry in the transport table. The  parameters
<parameter>protocol</parameter>,
<parameter>host</parameter>, and
<parameter>port</parameter> point to strings containing the
corresponding parts of the address that was passed into
<function>TRANS(OpenCOTSClient)()</function>.
This function must allocate and initialize the contents of the
XtransConnInfo structure that is returned by this function. This
function will open the transport.
    </para>
  </listitem>
  <listitem>
    <para>
int SetOption (struct _Xtransport *thistrans, int option, int arg)
    </para>
    <para>
This function provides a transport dependent way of implementing the
options defined by the X Transport Interface. In the current prototype,
this function is not being used, because all of the options defined so far
are transport independent. This function will have to be used if a radically
different transport type is added, or a transport dependent option is defined.
    </para>
  </listitem>
  <listitem>
    <para>
int CreateListener (struct _Xtransport *thistrans, char *port, int flags )
    </para>
    <para>
This function takes a transport endpoint opened for a server, and sets it
up to listen for incoming connection requests. The parameter
<parameter>port</parameter>
contains the port portion of the address that was passed to the Open function.
The parameter <parameter>flags</parameter> should be set to
<symbol>ADDR_IN_USE_ALLOWED</symbol> if the underlying transport endpoint
may be already bound and this should not be considered
as an error. Otherwise flags should be set to 0. This is used by IPv6 code,
where the same socket can be bound to both an IPv6 address and then to a
IPv4 address.  This function will bind the transport into the transport
name space if applicable, and fill in the local address portion of the
XtransConnInfo structure. The transport endpoint will then be set to
listen for incoming connection requests.
    </para>
  </listitem>
  <listitem>
    <para>
int ResetListener (struct _Xtransport *thistrans)
    </para>
    <para>
This function resets the transport for listening.
    </para>
  </listitem>
  <listitem>
    <para>
 XtransConnInfo Accept(struct _Xtransport *thistrans)
    </para>
    <para>
This function creates a new transport endpoint as a result of an
incoming connection request. The parameter
<parameter>thistrans</parameter> is the endpoint
that was opened for listening by the server. The new endpoint is
opened and bound into the transport’s namespace. A XtransConnInfo
structure describing the new endpoint is returned from this function
    </para>
  </listitem>
  <listitem>
    <para>
int Connect(struct _Xtransport *thistrans, char *host, char *port )
    </para>
    <para>
This function establishes a connection to a server. The parameters
<parameter>host</parameter>  and
<parameter>port</parameter>
describe the server to which the connection should be
established. The connection will be established so that
<function>Read()</function> and
<function>Write()</function> call can be made.
    </para>
  </listitem>
  <listitem>
    <para>
int BytesReadable(struct _Xtransport *thistrans, BytesReadable_t *pend )
    </para>
    <para>
This function replaces the
<function>BytesReadable()</function>
macro. This allows each transport to have it’s own mechanism for determining
how much data is ready to be read.
    </para>
  </listitem>
  <listitem>
    <para>
int Read(struct _Xtransport *thistrans, char *buf, int size )
    </para>
    <para>
This function reads size bytes into buf from the connection.
    </para>
  </listitem>
  <listitem>
    <para>
int Write(struct _Xtransport *thistrans, char *buf, int size )
    </para>
    <para>
This function writes size bytes from buf to the connection.
    </para>
  </listitem>
  <listitem>
    <para>
int Readv(struct _Xtransport *thistrans, struct iovec *buf, int size )
    </para>
    <para>
This function performs a <function>readv()</function> on the connection.
    </para>
  </listitem>
  <listitem>
    <para>
int Writev(struct _Xtransport *thistrans, struct iovec *buf, int size )
    </para>
    <para>
This function performs a <function>writev()</function> on the connection.
    </para>
  </listitem>
  <listitem>
    <para>
int Disconnect(struct _Xtransport *thistrans)
    </para>
    <para>
This function initiates an orderly shutdown of a connection. If a
transport does not distinguish between orderly and disorderly
disconnects, then a call to this function will have no affect.
    </para>
  </listitem>
  <listitem>
    <para>
int Close(struct _Xtransport *thistrans)
    </para>
    <para>
This function will break the connection, and close the endpoint.
    </para>
  </listitem>
</itemizedlist>
</chapter>
<chapter id="configuration">
<title>Configuration</title>

<para>
The implementation of each transport can be platform specific. It is expected
that existing connection types such as <symbol>TCPCONN</symbol>,
<symbol>UNIXCONN</symbol>, <symbol>LOCALCONN</symbol>, and
<symbol>STREAMSCONN</symbol> will be replaced with flags for each
possible transport type.
</para>
<para>
In X11R6, the below flags to enable transport types were set in
<symbol>ConnectionFlags</symbol> in the <filename>vendor.cf</filename> or
<filename>site.def</filename> config files.
</para>
<para>
In X11R7 modular releases, these flags are set when running
<filename>configure</filename> scripts which include the
<function>XTRANS_CONNECTION_FLAGS</function> macro from
<filename>xtrans.m4</filename>.
</para>
<informaltable pgwide='0' frame='none'>
  <tgroup cols='3' align='left'>
    <colspec colname='define' align='center'/>
    <colspec colname='enable'/>
    <colspec colname='desc'/>
    <thead>
      <row>
	<entry><code>#define</code></entry>
	<entry>configure flag</entry>
	<entry>Description</entry>
      </row>
    </thead>
    <tbody>
      <row>
	<entry><symbol>TCPCONN</symbol></entry>
	<entry><option>--enable-tcp-transport</option></entry>
	<entry>
	Enables the INET (IPv4) Domain Socket based transport
	</entry>
      </row>
      <row>
	<entry><symbol>IPv6</symbol></entry>
	<entry><option>--enable-ipv6</option></entry>
	<entry>
	Extends <symbol>TCPCONN</symbol> to enable IPv6 Socket based transport
	</entry>
      </row>
      <row>
	<entry><symbol>UNIXCONN</symbol></entry>
	<entry><option>--enable-unix-transport</option></entry>
	<entry>
	Enables the UNIX Domain Socket based transport
	</entry>
      </row>
      <row>
	<entry><symbol>STREAMSCONN</symbol></entry>
	<entry><emphasis>Not available in X11R7</emphasis></entry>
	<entry>
	Enables the TLI based transports
	</entry>
      </row>
      <row>
	<entry><symbol>LOCALCONN</symbol></entry>
	<entry><option>--enable-local-transport</option></entry>
	<entry>
	Enables the SYSV Local connection transports
	</entry>
      </row>
      <row>
	<entry><symbol>DNETCONN</symbol></entry>
	<entry><emphasis>Not available in X11R7</emphasis></entry>
	<entry>
	Enables the DECnet transports
	</entry>
      </row>
    </tbody>
  </tgroup>
</informaltable>


</chapter>

<chapter id="transport_specific_definitions">
<title>Transport Specific Definitions</title>

<informaltable pgwide='0' frame='none'>
  <tgroup cols='4' align='center'>
    <colspec colname='c1'/>
    <colspec colname='c2'/>
    <colspec colname='c3'/>
    <colspec colname='c4'/>
    <thead>
      <row>
        <entry morerows="1" align='center'>Protocol Family</entry>
        <entry namest="c2" nameend="c4"  align='center'>Address Component</entry>
      </row>
      <row>
        <entry align='center'>protocol</entry>
        <entry align='center'>host</entry>
        <entry align='center'>port</entry>
      </row>
    </thead>
    <tbody>
      <row>
        <entry align='center'>Internet</entry>
        <entry align='center'>inet inet6 tcp udp</entry>
        <entry align='center'>name of an internet addressable host</entry>
        <entry align='center'>string containing the name of a service or a valid port number.  Example: "xserver0", "7100"</entry>
      </row>
      <row>
        <entry align='center'>DECnet</entry>
        <entry align='center'>decnet</entry>
        <entry align='center'>name of a DECnet addressable host</entry>
        <entry align='center'>string containing the complete name of the object.  Example: "X$X0"</entry>
      </row>
      <row>
        <entry align='center'>NETware</entry>
        <entry align='center'>ipx</entry>
        <entry align='center'>name of a NETware addressable host</entry>
        <entry align='center'>Not sure of the specifics yet.</entry>
      </row>
      <row>
        <entry align='center'>OSI</entry>
        <entry align='center'>osi</entry>
        <entry align='center'>name of an OSI adressable host.</entry>
        <entry align='center'>Not sure of the specifics yet.</entry>
      </row>
      <row>
        <entry align='center'>Local</entry>
        <entry align='center'>local pts named sco isc</entry>
        <entry align='center'>(ignored)</entry>
        <entry align='center'>String containing the port name, ie "xserver0", "fontserver0".</entry>
      </row>
    </tbody>
  </tgroup>
</informaltable>

</chapter>

<chapter id="implementation_notes">
<title>Implementation Notes</title>
<para>
This section refers to the prototype implementation that is being developed
concurrently with this document. This prototype has been able to flush out many
details and problems as the specification was being developed.
</para>
<para>
In X11R6, all of the source code for this interface was located in
<filename>xc/lib/xtrans</filename>.
</para>
<para>
In X11R7, all of the source code for this interface is delivered via
the <systemitem>lib/libxtrans</systemitem> modular package from X.Org,
and is installed under
<filename><replaceable>${prefix}</replaceable>/X11/Xtrans</filename>
so that other modules may find it when they build.
</para>
<para>
All functions names in the source are of the format
<function>TRANS(func)()</function>. The
<function>TRANS()</function>
macro is defined as
<programlisting language="C">
#if (__STDC__ &amp;&amp; !defined(UNIXCPP)) || defined(ANSICPP)
#define TRANS(func) _PROTOCOLTrans##func
#else
#define TRANS(func) _PROTOCOLTrans/**/func
#endif
</programlisting>
</para>

<para>
<symbol>PROTOCOL</symbol> will be uniquely defined in each directory
where this code is compiled.
<symbol>PROTOCOL</symbol> will be defined to be the name of the protocol
that is implemented by the library or server, such as X11, FS, and ICE.
</para>

<para>
All libraries and servers that use the X Transport Interface should have a new
file called <filename><replaceable>TRANSPORT</replaceable>trans.c</filename>.
This file will include the transports based on the configuration flags
provided by the <filename>configure</filename> script. Below is an
example <filename>xfstrans.c</filename> for the font server.
</para>

<programlisting language="C">
#include "config.h"

#define FONT_t 1
#define TRANS_REOPEN 1
#define TRANS_SERVER 1

#include &lt;X11/Xtrans/transport.c&gt;
</programlisting>
<para>
The source files for this interface are listed below.
</para>

<variablelist>
  <varlistentry>
    <term><filename>Xtrans.h</filename></term>
    <listitem><para>
Function prototypes and defines for the Transport Independent API.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term><filename>Xtransint.h</filename></term>
    <listitem><para>
Used by the interface implementation only.
Contains the internal data structures.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term><filename>Xtranssock.c</filename></term>
    <listitem><para>
Socket implementation of the Transport Dependent API.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term><filename>Xtranstli.c</filename></term>
    <listitem><para>
TLI implementation of the Transport Dependent API.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term><filename>Xtransdnet.c</filename></term>
    <listitem><para>
DECnet implementation of the Transport Dependent API.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term><filename>Xtranslocal.c</filename></term>
    <listitem><para>
Implementation of the Transport Dependent API for SYSV Local connections.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term><filename>Xtrans.c</filename></term>
    <listitem><para>
Exposed Transport Independent API Functions.
    </para></listitem>
  </varlistentry>
  <varlistentry>
    <term><filename>Xtransutil.c</filename></term>
    <listitem><para>
Collection of Utility functions that use the X Transport Interface.
    </para></listitem>
  </varlistentry>
</variablelist>


<para>
The file <filename>Xtransint.h</filename> contains much of the transport
related code that was previously in <filename>Xlibint.h</filename> and
<filename>Xlibnet.h</filename>.
This will make the definitions available for all transport users. This
should also obsolete the equivalent code in other libraries.
</para>

</chapter>
</book>