'\" t .\" Title: zmq_tcp .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets v1.75.2 .\" Date: 11/22/2011 .\" Manual: 0MQ Manual .\" Source: 0MQ 2.1.10 .\" Language: English .\" .TH "ZMQ_TCP" "7" "11/22/2011" "0MQ 2\&.1\&.10" "0MQ 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" zmq_tcp \- 0MQ unicast transport using TCP .SH "SYNOPSIS" .sp TCP is an ubiquitous, reliable, unicast transport\&. When connecting distributed applications over a network with 0MQ, using the TCP transport will likely be your first choice\&. .SH "ADDRESSING" .sp A 0MQ address string consists of two parts as follows: \fItransport\fR://\fIendpoint\fR\&. The \fItransport\fR part specifies the underlying transport protocol to use, and for the TCP transport shall be set to tcp\&. 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 \fIzmq_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 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 IPv4 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 \fIzmq_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 address of the peer, in its numeric representation\&. .RE .SH "WIRE FORMAT" .sp 0MQ 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 = zmq_bind(socket, "tcp://*:5555"); assert (rc == 0); /* TCP port 5555 on the local loop\-back interface on all platforms */ rc = zmq_bind(socket, "tcp://127\&.0\&.0\&.1:5555"); assert (rc == 0); /* TCP port 5555 on the first Ethernet network interface on Linux */ rc = zmq_bind(socket, "tcp://eth0:5555"); assert (rc == 0); .fi .if n \{\ .RE .\} .PP \fBConnecting a socket\fR. .sp .if n \{\ .RS 4 .\} .nf /* Connecting using an IP address */ rc = zmq_connect(socket, "tcp://192\&.168\&.1\&.1:5555"); assert (rc == 0); /* Connecting using a DNS name */ rc = zmq_connect(socket, "tcp://server1:5555"); assert (rc == 0); .fi .if n \{\ .RE .\} .sp .SH "SEE ALSO" .sp \fBzmq_bind\fR(3) \fBzmq_connect\fR(3) \fBzmq_pgm\fR(7) \fBzmq_ipc\fR(7) \fBzmq_inproc\fR(7) \fBzmq\fR(7) .SH "AUTHORS" .sp This 0MQ manual page was written by Martin Sustrik <\m[blue]\fBsustrik@250bpm\&.com\fR\m[]\&\s-2\u[1]\d\s+2> and Martin Lucina <\m[blue]\fBmato@kotelna\&.sk\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 mato@kotelna.sk .RS 4 \%mailto:mato@kotelna.sk .RE