OpenBSD manual page server

NAME

xtrans — X Transport Interface

THE X TRANSPORT INTERFACE

Designed by Stuart Anderson (NCR) with help from Ralph Mor (X Consortium)

Note

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.

PURPOSES AND GOALS

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.

This interface should solve the problem of multiple ‘#ifdef TRANSPORT’ and ‘#ifdef PLATFORM’ statements scattered throughout the source tree.

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.

OVERVIEW OF THE INTERFACE

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.

This API does not provide an abstraction for select() or poll(). 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.

DEFINITION OF ADDRESS SPECIFICATION FORMAT

Addresses are specified in the following syntax,

protocol/host:port

where protocol specifies a protocol family or an alias for a protocol family. A definition of common protocol families is given in a later section.

The host part specifies the name of a host or other transport dependent entity that could be interpreted as a Network Service Access Point (NSAP).

The port 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.

INTERNAL DATA STRUCTURES

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.

typedef struct _Xtransport {
    const char *TransName;
    int  flags;
    XtransConnInfo (*OpenCOTSClient)(
     struct _Xtransport *,    /* transport */
     const char *,            /* protocol */
     const char *,            /* host */
     const char *             /* port */
    );
    XtransConnInfo (*OpenCOTSServer)(
     struct _Xtransport *,    /* transport */
     const char *,            /* protocol */
     const char *,            /* host */
     const char *             /* port */
    );
    XtransConnInfo (*OpenCLTSClient)(
     struct _Xtransport *,    /* transport */
     const char *,            /* protocol */
     const char *,            /* host */
 const char *             /* port */
    );
    XtransConnInfo (*OpenCLTSServer)(
     struct _Xtransport *,    /* transport */
     const char *,            /* protocol */
     const char *,            /* host */
     const char *             /* port */
    );
    int     (*SetOption)(
     XtransConnInfo,          /* connection */
     int,               /* option */
     int               /* arg */
    );
    int     (*CreateListener)(
     XtransConnInfo,          /* connection */
     const char *,            /* port */
     int                      /* flags */
    );
    int     (*ResetListener)(
     XtransConnInfo          /* connection */
    );
    XtransConnInfo (*Accept)(
     XtransConnInfo          /* connection */
    );
    int     (*Connect)(
     XtransConnInfo,          /* connection */
     const char *,            /* host */
     const 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;

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;
};

EXPOSED TRANSPORT INDEPENDENT API

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.

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 _X11TransOpenCOTSClient().

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.

TRANSPORT OPTION DEFINITION

The following options are defined for the TRANS(SetOption)() (TRANSSetOption) function. If an OS or transport does not support any of these options, then it will silently ignore the option.

• TRANS_NONBLOCKING

  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.

• TRANS_CLOSEONEXEC

  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.

HIDDEN TRANSPORT DEPENDENT API

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 ‘#ifdef SUNSYSV’ should be handled inside these functions.

• XtransConnInfo * OpenCOTSClient(struct _Xtransport * thistrans, const char * protocol, const char * host, const char * port);

  This function creates a Connection-Oriented Transport. The parameter thistrans points to an Xtransport entry in the transport table. The parameters protocol, host, and port, point to strings containing the corresponding parts of the address that was passed into TRANS(OpenCOTSClient)() (TRANSOpenCOTSClient). 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.

• XtransConnInfo * OpenCOTSServer(struct _Xtransport * thistrans, const char * protocol, const char * host, const char * port);

  This function creates a Connection-Oriented Transport. The parameter thistrans points to an Xtransport entry in the transport table. The parameters protocol, host, and port point to strings containing the corresponding parts of the address that was passed into TRANS(OpenCOTSServer)() (TRANSOpenCOTSServer). This function must allocate and initialize the contents of the XtransConnInfo structure that is returned by this function. This function will open the transport.

• XtransConnInfo * OpenCLTSClient(struct _Xtransport * thistrans, const char * protocol, const char * host, const char * port);

  This function creates a Connection-Less Transport. The parameter thistrans points to an Xtransport entry in the transport table. The parameters protocol, host, and port point to strings containing the corresponding parts of the address that was passed into TRANS(OpenCLTSClient)() (TRANSOpenCLTSClient). 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.

• XtransConnInfo * OpenCLTSServer(struct _Xtransport * thistrans, const char * protocol, const char * host, const char * port);

  This function creates a Connection-Less Transport. The parameter thistrans points to an Xtransport entry in the transport table. The parameters protocol, host, and port point to strings containing the corresponding parts of the address that was passed into TRANS(OpenCLTSServer)() (TRANSOpenCLTSServer). This function must allocate and initialize the contents of the XtransConnInfo structure that is returned by this function. This function will open the transport.

• int SetOption(struct _Xtransport * thistrans, int option, int arg);

  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.

• int CreateListener(struct _Xtransport * thistrans, const char *port, int flags);

  This function takes a transport endpoint opened for a server, and sets it up to listen for incoming connection requests. The parameter port contains the port portion of the address that was passed to the Open function. The parameter flags should be set to ADDR_IN_USE_ALLOWED 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.

• int ResetListener(struct _Xtransport * thistrans);

  This function resets the transport for listening.

• XtransConnInfo Accept(struct _Xtransport * thistrans);

  This function creates a new transport endpoint as a result of an incoming connection request. The parameter thistrans 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

• int Connect(struct _Xtransport * thistrans, const char * host, const char * port);

  This function establishes a connection to a server. The parameters host and port describe the server to which the connection should be established. The connection will be established so that Read() and Write() call can be made.

• int BytesReadable(struct _Xtransport * thistrans, BytesReadable_t * pend);

  This function replaces the BytesReadable() macro. This allows each transport to have its own mechanism for determining how much data is ready to be read.

• int Read(struct _Xtransport * thistrans, char * buf, int size);

  This function reads size bytes into buf from the connection.

• int Write(struct _Xtransport * thistrans, char * buf, int size);

  This function writes size bytes from buf to the connection.

• int Readv(struct _Xtransport * thistrans, struct iovec * buf, int size);

  This function performs a readv() on the connection.

• int Writev(struct _Xtransport * thistrans, struct iovec * buf, int size);

  This function performs a writev() on the connection.

• int Disconnect(struct _Xtransport * thistrans);

  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.

• int Close(struct _Xtransport * thistrans);

  This function will break the connection, and close the endpoint.

CONFIGURATION

The implementation of each transport can be platform specific. It is expected that existing connection types such as TCPCONN, UNIXCONN, LOCALCONN, and STREAMSCONN will be replaced with flags for each possible transport type.

In X11R6, the below flags to enable transport types were set in ConnectionFlags in the vendor.cf or site.def config files.

In X11R7 modular releases, these flags are set when running configure scripts which include the XTRANS_CONNECTION_FLAGS() macro from xtrans.m4.

Table Row

• ‘#define’
• configure flag
• Description

Table Row

• TCPCONN
• --enable-tcp-transport
• Enables the INET (IPv4) Domain Socket based transport

Table Row

• IPv6
• --enable-ipv6
• Extends TCPCONN to enable IPv6 Socket based transport

Table Row

• UNIXCONN
• --enable-unix-transport
• Enables the UNIX Domain Socket based transport

Table Row

• STREAMSCONN
• Not available in X11R7
• Enables the TLI based transports

Table Row

• LOCALCONN
• --enable-local-transport
• Enables the SYSV Local connection transports

Table Row

• DNETCONN
• Not available in X11R7
• Enables the DECnet transports

TRANSPORT SPECIFIC DEFINITIONS

Table Row

• Protocol Family
• Address Component

Table Row

• protocol
• host
• port

Table Row

• Internet
• inet inet6 tcp udp
• name of an internet addressable host
• string containing the name of a service or a valid port number. Example: "xserver0", "7100"

Table Row

• DECnet
• decnet
• name of a DECnet addressable host
• string containing the complete name of the object. Example: "X$X0"

Table Row

• NETware
• ipx
• name of a NETware addressable host
• Not sure of the specifics yet.

Table Row

• OSI
• osi
• name of an OSI adressable host.
• Not sure of the specifics yet.

Table Row

• Local
• local pts named sco isc
• (ignored)
• String containing the port name, ie "xserver0", "fontserver0".

IMPLEMENTATION NOTES

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.

In X11R6, all of the source code for this interface was located in xc/lib/xtrans.

In X11R7, all of the source code for this interface is delivered via the lib/libxtrans modular package from X.Org, and is installed under ~ ${prefix}/X11/Xtrans so that other modules may find it when they build.

All functions names in the source are of the format TRANS(func)(). The TRANS() macro is defined as

#define TRANS(func) _PROTOCOLTrans##func

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

All libraries and servers that use the X Transport Interface should have a new file called ~ TRANSPORTtrans.c. This file will include the transports based on the configuration flags provided by the configure script. Below is an example xfstrans.c for the font server.

#include "config.h"
#define FONT_t 1
#define TRANS_REOPEN 1
#define TRANS_SERVER 1
#include <X11/Xtrans/transport.c>

The source files for this interface are listed below.

Xtrans.h

Function prototypes and defines for the Transport Independent API.

Xtransint.h

Used by the interface implementation only. Contains the internal data structures.

Xtranssock.c

Socket implementation of the Transport Dependent API.

Xtranstli.c

TLI implementation of the Transport Dependent API.

Xtransdnet.c

DECnet implementation of the Transport Dependent API.

Xtranslocal.c

Implementation of the Transport Dependent API for SYSV Local connections.

Xtrans.c

Exposed Transport Independent API Functions.

Xtransutil.c

Collection of Utility functions that use the X Transport Interface.

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

AUTHORS

X Consortium Standard

Stuart Anderson, NCR Corporation
Ralph Mor, X Consortium
Alan Coopersmith, Oracle Corp. X Version 11, Release 6 Version 1.2 Copyright © 1993, 1994 NCR Corporation - Dayton, Ohio, USA