'\" t .\" Title: xs_tcp .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 .\" Date: 06/13/2012 .\" Manual: Crossroads I/O Manual .\" Source: Crossroads I/O 1.2.0 .\" Language: English .\" .TH "XS_TCP" "7" "06/13/2012" "Crossroads I/O 1\&.2\&.0" "Crossroads I/O Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" xs_tcp \- Crossroads unicast transport using TCP .SH "SYNOPSIS" .sp TCP is an ubiquitous, reliable, unicast transport\&. When connecting distributed applications over a network with Crossroads, using the TCP transport will likely be your first choice\&. .SH "ADDRESSING" .sp A Crossroads address string consists of two parts as follows: \fItransport\fR://[\fIsource address\fR;]\fIendpoint\fR\&. The \fItransport\fR part specifies the underlying transport protocol to use, and for the TCP transport shall be set to tcp\&. \fIsource address\fR is optional\&. The meaning of the \fIendpoint\fR part for the TCP transport is defined below\&. .SS "Assigning a local address to a socket" .sp When assigning a local address to a socket using \fIxs_bind()\fR with the \fItcp\fR transport, the \fIendpoint\fR shall be interpreted as an \fIinterface\fR followed by a colon and the TCP port number to use\&. .sp An \fIinterface\fR may be specified by either of the following: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} The wild\-card *, meaning all available interfaces\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} The primary IPv4 or IPv6 address assigned to the interface, in its numeric representation\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} The interface name as defined by the operating system\&. .RE .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br .sp Interface names are not standardised in any way and should be assumed to be arbitrary and platform dependent\&. On Win32 platforms no short interface names exist, thus only the primary IP address may be used to specify an \fIinterface\fR\&. .sp .5v .RE .SS "Connecting a socket" .sp When connecting a socket to a peer address using \fIxs_connect()\fR with the \fItcp\fR transport, the \fIendpoint\fR shall be interpreted as a \fIpeer address\fR followed by a colon and the TCP port number to use\&. .sp A \fIpeer address\fR may be specified by either of the following: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} The DNS name of the peer\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} The IPv4 or IPv6 address of the peer, in it\(cqs numeric representation\&. .RE .SH "WIRE FORMAT" .sp Crossroads messages are transmitted over TCP in frames consisting of an encoded \fIpayload length\fR, followed by a \fIflags\fR field and the message body\&. The \fIpayload length\fR is defined as the combined length in octets of the message body and the \fIflags\fR field\&. .sp For frames with a \fIpayload length\fR not exceeding 254 octets, the \fIpayload length\fR shall be encoded as a single octet\&. The minimum valid \fIpayload length\fR of a frame is 1 octet, thus a \fIpayload length\fR of 0 octets is invalid and such frames SHOULD be ignored\&. .sp For frames with a \fIpayload length\fR exceeding 254 octets, the \fIpayload length\fR shall be encoded as a single octet with the value 255 followed by the \fIpayload length\fR represented as a 64\-bit unsigned integer in network byte order\&. .sp The \fIflags\fR field consists of a single octet containing various control flags: .sp Bit 0 (MORE): \fIMore message parts to follow\fR\&. A value of 0 indicates that there are no more message parts to follow; or that the message being sent is not a multi\-part message\&. A value of 1 indicates that the message being sent is a multi\-part message and more message parts are to follow\&. .sp Bits 1\-7: \fIReserved\fR\&. Bits 1\-7 are reserved for future expansion and MUST be set to zero\&. .sp The following ABNF grammar represents a single \fIframe\fR: .sp .if n \{\ .RS 4 .\} .nf frame = (length flags data) length = OCTET / (escape 8OCTET) flags = OCTET escape = %xFF data = *OCTET .fi .if n \{\ .RE .\} .sp The following diagram illustrates the layout of a frame with a \fIpayload length\fR not exceeding 254 octets: .sp .if n \{\ .RS 4 .\} .nf 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ | Payload length| Flags | Message body \&.\&.\&. | +\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ | Message body \&.\&.\&. +\-+\-+\-+\-+\-+\-+\- \&.\&.\&. .fi .if n \{\ .RE .\} .sp The following diagram illustrates the layout of a frame with a \fIpayload length\fR exceeding 254 octets: .sp .if n \{\ .RS 4 .\} .nf 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ | 0xff | Payload length \&.\&.\&. | +\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ | Payload length \&.\&.\&. | +\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ | Payload length| Flags | Message body \&.\&.\&. | +\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ | Message body \&.\&.\&. +\-+\-+\-+\-+\-+\-+\-+ \&.\&.\&. .fi .if n \{\ .RE .\} .SH "EXAMPLES" .PP \fBAssigning a local address to a socket\fR. .sp .if n \{\ .RS 4 .\} .nf /* TCP port 5555 on all available interfaces */ rc = xs_bind(socket, "tcp://*:5555"); assert (rc != \-1); /* TCP port 5555 on the local loop\-back interface on all platforms */ rc = xs_bind(socket, "tcp://127\&.0\&.0\&.1:5555"); assert (rc != \-1); /* TCP port 5555 on the first Ethernet network interface on Linux */ rc = xs_bind(socket, "tcp://eth0:5555"); assert (rc != \-1); .fi .if n \{\ .RE .\} .PP \fBConnecting a socket\fR. .sp .if n \{\ .RS 4 .\} .nf /* Connecting using an IP address */ rc = xs_connect(socket, "tcp://192\&.168\&.1\&.1:5555"); assert (rc != \-1); /* Connecting using a DNS name */ rc = xs_connect(socket, "tcp://server1:5555"); assert (rc != \-1); .fi .if n \{\ .RE .\} .sp .SH "SEE ALSO" .sp \fBxs_bind\fR(3) \fBxs_connect\fR(3) \fBxs_pgm\fR(7) \fBxs_ipc\fR(7) \fBxs_inproc\fR(7) \fBxs\fR(7) .SH "AUTHORS" .sp The Crossroads documentation was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmartin@lucina\&.net\fR\m[]\&\s-2\u[2]\d\s+2>\&. .SH "NOTES" .IP " 1." 4 sustrik@250bpm.com .RS 4 \%mailto:sustrik@250bpm.com .RE .IP " 2." 4 martin@lucina.net .RS 4 \%mailto:martin@lucina.net .RE