From 3c4e0455425d5afd546c4a3f2cc9f8c7e60f2fca Mon Sep 17 00:00:00 2001 From: Alan Coopersmith Date: Sun, 27 Jan 2013 21:39:34 -0800 Subject: Docs: convert function synopses to docbook funcsynopsis markup Also add some cross-reference links and various other markup improvements. Signed-off-by: Alan Coopersmith --- doc/xtrans.xml | 561 ++++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 360 insertions(+), 201 deletions(-) (limited to 'doc') diff --git a/doc/xtrans.xml b/doc/xtrans.xml index 12dbe3c..10da846 100644 --- a/doc/xtrans.xml +++ b/doc/xtrans.xml @@ -24,7 +24,7 @@ X Version 11, Release &fullrelvers; - Version 0.7 + Version 1.2 19931994 NCR Corporation - Dayton, Ohio, USA @@ -378,7 +378,8 @@ 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. +Xlib, TRANS(OpenCOTSClient) becomes +_X11TransOpenCOTSClient. All failures are considered fatal, and the connection should be closed @@ -389,64 +390,85 @@ errno will be available for debugging purposes. Core Interface API - -XtransConnInfo TRANS(OpenCOTSClient)(char *address) - + + + XtransConnInfo TRANS(OpenCOTSClient) + char *address + + This function creates a Connection-Oriented Transport that is suitable for use by a client. The parameter address -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. +contains the full address of the server to which this endpoint will be +connected. This function returns an opaque transport connection object on +success, or NULL on failure. - -XtransConnInfo TRANS(OpenCOTSServer)(char *address) - + + + XtransConnInfo TRANS(OpenCOTSServer) + char *address + + This function creates a Connection-Oriented Transport that is suitable for use by a server. The parameter address 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. +full address to which this server will be bound. This function returns an +opaque transport connection object on success, or NULL +on failure. - -XtransConnInfo TRANS(OpenCLTSClient)(char *address) - + + + XtransConnInfo TRANS(OpenCLTSClient) + char *address + + This function creates a Connection-Less Transport that is suitable for use by a client. The parameter address 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. +full address of the server to which this endpoint will be connected. This +function returns an opaque transport connection object on success, or +NULL on failure. - -XtransConnInfo TRANS(OpenCLTSServer)(char *address) - + + + XtransConnInfo TRANS(OpenCLTSServer) + char *address + + This function creates a Connection-Less Transport that is suitable for use by a server. The parameter address 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. +full address to which this server will be bound. This function returns an +opaque transport connection object on success, or NULL +on failure. - -int TRANS(SetOption)(XtransConnInfo connection, int option, int arg) - + + + int TRANS(SetOption) + XtransConnInfo connection + int option + int arg + + This function sets transport options, similar to the way setsockopt() and ioctl() work. The parameter connection is an endpoint -that was obtained from _XTransOpen*() functions. The parameter -option contains the option that will be set. The actual -values for option are defined in a later section. The parameter -arg 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. +that was obtained from _XTransOpen*() functions. +The parameter option contains the option that will +be set. The actual values for option are defined in a +later section. +The parameter arg can be used to pass +in an additional value that may be required by some options. +This function returns 0 on success and -1 on failure. Based on current usage, the complimentary function @@ -454,16 +476,21 @@ Based on current usage, the complimentary function - -int TRANS(CreateListener)(XtransConnInfo connection, char *port, int flags) - + + + int TRANS(CreateListener) + XtransConnInfo connection + char *port + int flags + + This function sets up the server endpoint for listening. The parameter connection is an endpoint that was obtained from TRANS(OpenCOTSServer)() or TRANS(OpenCLTSServer)(). The parameter -port specifies the -port to which this endpoint should be bound for listening. If port is NULL, +port 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 flags parameter can be set @@ -474,9 +501,12 @@ function itself to fail. This function return 0 on success and -1 on failure. - -int TRANS(ResetListener)(XtransConnInfo connection) - + + + int TRANS(ResetListener) + XtransConnInfo connection + + 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 @@ -491,44 +521,61 @@ This function will return one of the following values: - -XtransConnInfo TRANS(Accept)(XtransConnInfo connection) - + + + XtransConnInfo TRANS(Accept) + XtransConnInfo connection + + Once a connection indication is received, this function can be called to accept the connection. The parameter connection is an opened and bound endpoint that was obtained from TRANS(OpenCOTSServer)() and passed to TRANS(CreateListener)(). This function will return a -new opaque transport connection object upon success, NULL otherwise. +new opaque transport connection object upon success, +NULL otherwise. - -int TRANS(Connect)(XtransConnInfo connection, char *address) - + + + int TRANS(Connect) + XtransConnInfo connection + char *address + + This function creates a connection to a server. The parameter connection is an endpoint that was obtained from TRANS(OpenCOTSClient)(). The parameter address 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. +should connect. If the protocol is included in the address, it will be +ignored. This function returns 0 on success and -1 on failure. + + + int TRANS(BytesReadable) + XtransConnInfo connection + BytesReadable_t *pend + + -int TRANS(BytesReadable)(XtransConnInfo connection, BytesReadable_t *pend); - - -This function provides the same functionality as the BytesReadable macro. +This function provides the same functionality as the +BytesReadable macro. - -int TRANS(Read)(XtransConnInfo connection, char *buf, int size) - + + + int TRANS(Read) + XtransConnInfo connection + char *buf + int size + + This function will return the number of bytes requested on a COTS connection, and will return the minimum of the number bytes requested or @@ -536,34 +583,52 @@ the size of the incoming packet on a CLTS connection. - -int TRANS(Write)(XtransConnInfo connection, char *buf, int size) - + + + int TRANS(Write) + XtransConnInfo connection + char *buf + int size + + 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. - -int TRANS(Readv)(XtransConnInfo connection, struct iovec *buf, int size) - + + + int TRANS(Readv) + XtransConnInfo connection + struct iovec *buf + int size + + Similar to TRANS(Read)(). - - int TRANS(Writev)(XtransConnInfo connection, struct iovec *buf, int size) - + + + int TRANS(Writev) + XtransConnInfo connection + struct iovec *buf + int size + + Similar to TRANS(Write)(). - -int TRANS(Disconnect)(XtransConnInfo connection) - + + + int TRANS(Disconnect) + XtransConnInfo connection + + 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 @@ -571,9 +636,12 @@ breaks the connection on the transport. It is similar to the socket function - -int TRANS(Close)(XtransConnInfo connection) - + + + int TRANS(Close) + XtransConnInfo connection + + This function closes the transport, unbinds it, and frees all resources that was associated with the transport. If a TRANS(Disconnect) @@ -581,58 +649,75 @@ call was not made on the connection, a disorderly disconnect may occur. - -int TRANS(IsLocal)(XtransConnInfo connection) - + + + int TRANS(IsLocal) + XtransConnInfo connection + + Returns TRUE if it is a local transport. - -int TRANS(GetMyAddr)(XtransConnInfo connection, int *familyp, int *addrlenp, -Xtransaddr **addrp) - - -This function is similar to -getsockname(). + + + int TRANS(GetMyAddr) + XtransConnInfo connection + int *familyp + int *addrlenp + Xtransaddr **addrp + + + +This function is similar to getsockname(). 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 -Connect() or +established with Connect() or Accept(). - -int TRANS(GetPeerAddr)(XtransConnInfo connection, int *familyp, int *addrlenp, -Xtransaddr **addrp) - - -This function is similar to -getpeername(). + + + int TRANS(GetPeerAddr) + XtransConnInfo connection + int *familyp + int *addrlenp + Xtransaddr **addrp + + + +This function is similar to getpeername(). 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 -Connect() or +established with Connect() or Accept(). - -int TRANS(GetConnectionNumber)(XtransConnInfo connection) - + + + int TRANS(GetConnectionNumber) + XtransConnInfo connection + + Returns the file descriptor associated with this transport. - -int TRANS(MakeAllCOTSServerListeners)(char *port, int *partial_ret, -int *count_ret, XtransConnInfo **connections_ret) - + + + int TRANS(MakeAllCOTSServerListeners) + char *port + int *partial_ret + int *count_ret + XtransConnInfo **connections_ret + + 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. @@ -643,10 +728,15 @@ is the list of transports. - -int TRANS(MakeAllCLTSServerListeners)( char *port, int *partial_ret, -int *count_ret, XtransConnInfo **connections_ret) - + + + int TRANS(MakeAllCLTSServerListeners) + char *port + int *partial_ret + int *count_ret + XtransConnInfo **connections_ret + + 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. @@ -668,13 +758,19 @@ convenience. - -int TRANS(ConvertAddress)(int *familyp, int *addrlenp, Xtransaddr *addrp) - + + + int TRANS(ConvertAddress) + int *familyp + int *addrlenp + Xtransaddr *addrp + + 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)). +address (ie AF_INET, AF_UNIX to the X +protocol definition (ie FamilyInternet, +FamilyLocal)). @@ -685,8 +781,8 @@ FamilyLocal)). Transport Option Definition The following options are defined for the -TRANS(SetOption)() - function. If an OS or transport does not support any of these options, +TRANS(SetOption)() +function. If an OS or transport does not support any of these options, then it will silently ignore the option. @@ -726,18 +822,22 @@ the #ifdef SUNSYSV should be handled inside these functions. - -XtransConnInfo *OpenCOTSClient ( -struct _Xtransport *thistrans, char *protocol, char *host, char *port) - + + + XtransConnInfo *OpenCOTSClient + struct _Xtransport *thistrans + char *protocol + char *host + 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)(). +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)(). 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 @@ -746,39 +846,44 @@ this function. - -XtransConnInfo *OpenCOTSServer ( -struct _Xtransport *thistrans, char *protocol, char *host, char *port) - + + + XtransConnInfo *OpenCOTSServer + struct _Xtransport *thistrans + char *protocol + char *host + 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)(). +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)(). 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, char *protocol, char *host, char *port) - + + + XtransConnInfo *OpenCLTSClient + struct _Xtransport *thistrans + char *protocol + char *host + 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(OpenCOTSClient)(). +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)(). 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 @@ -787,28 +892,36 @@ in by this function. - -XtransConnInfo *OpenCLTSServer ( -struct _Xtransport *thistrans, char *protocol, char *host, char *port) - + + + XtransConnInfo *OpenCLTSServer + struct _Xtransport *thistrans + char *protocol + char *host + 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(OpenCOTSClient)(). +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)(). 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) - + + + 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, @@ -818,9 +931,14 @@ different transport type is added, or a transport dependent option is defined. - -int CreateListener (struct _Xtransport *thistrans, char *port, int flags ) - + + + int CreateListener + struct _Xtransport *thistrans + 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 @@ -838,17 +956,23 @@ listen for incoming connection requests. - -int ResetListener (struct _Xtransport *thistrans) - + + + int ResetListener + struct _Xtransport *thistrans + + This function resets the transport for listening. - - XtransConnInfo Accept(struct _Xtransport *thistrans) - + + + XtransConnInfo Accept + struct _Xtransport *thistrans + + This function creates a new transport endpoint as a result of an incoming connection request. The parameter @@ -859,13 +983,17 @@ structure describing the new endpoint is returned from this function - -int Connect(struct _Xtransport *thistrans, char *host, char *port ) - + + + int Connect + struct _Xtransport *thistrans + char *host + char *port + + This function establishes a connection to a server. The parameters -host and -port +host and port describe the server to which the connection should be established. The connection will be established so that Read() and @@ -873,52 +1001,80 @@ established. The connection will be established so that - -int BytesReadable(struct _Xtransport *thistrans, BytesReadable_t *pend ) - - -This function replaces the -BytesReadable() -macro. This allows each transport to have it’s own mechanism for determining + + + 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 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 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 ) - + + + 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 ) - + + + int Writev + struct _Xtransport *thistrans + struct iovec *buf + int size + + This function performs a writev() on the connection. - -int Disconnect(struct _Xtransport *thistrans) - + + + int Disconnect + struct _Xtransport *thistrans + + This function initiates an orderly shutdown of a connection. If a transport does not distinguish between orderly and disorderly @@ -926,9 +1082,12 @@ disconnects, then a call to this function will have no affect. - -int Close(struct _Xtransport *thistrans) - + + + int Close + struct _Xtransport *thistrans + + This function will break the connection, and close the endpoint. -- cgit v1.2.3