transports man pages updated

4 files changed, 145 insertions, 3 deletions

diff --git a/man/man7/zmq_inproc.7 b/man/man7/zmq_inproc.7
index 7f43ca7..bc09f90 100644
--- a/man/man7/zmq_inproc.7
+++ b/man/man7/zmq_inproc.7
@@ -2,8 +2,40 @@
 .SH NAME
 In-process (inter-thread) tranport for 0MQ
 .SH SYNOPSIS
-.SH DESCRIPTION
+
+In-process transport is optimised for passing messages betweem threads in the
+same process.
+
+Messages are passed directly from one application thread to
+another application thread. There are no intervening I/O threads involved.
+Thus, if you are using 0MQ for in-process messaging only, you can initialise
+the library (
+.IR zmq_init
+) with zero I/O worker threads.
+
+.SH CONNECTION STRING
+
+Connection string for inproc transport is "inproc://" followed by an arbitrary
+string. There are no restrictions on the string format:
+
+.nf
+    inproc://my_endpoint
+    inproc://feeds/opra/cboe
+    inproc://feeds.opra.nasdaq
+    inproc://!&W#($)_@_123*((^^^
+.fi
+
+.SH WIRE FORMAT
+
+In-process transport transfers messages via memory thus there is no need for a
+wire format specification.
+
 .SH "SEE ALSO"
+
+.BR zmq_tcp (7)
+.BR zmq_udp (7)
+.BR zmq_pgm (7)
+
 .SH AUTHOR
 Martin Sustrik <sustrik at 250bpm dot com>
 
diff --git a/man/man7/zmq_pgm.7 b/man/man7/zmq_pgm.7
index 57af65e..e432730 100644
--- a/man/man7/zmq_pgm.7
+++ b/man/man7/zmq_pgm.7
@@ -2,8 +2,83 @@
 .SH NAME
 PGM-based tranport for 0MQ
 .SH SYNOPSIS
-.SH DESCRIPTION
+
+PGM is a protocol for reliable multicast (RFC3208). 0MQ's PGM transport allows
+you to deliver messages to multiple destinations sending the data over
+the network once only. It makes sense to use PGM transport if the data,
+delivered to each destination separately, would seriously load or even overload
+the network.
+
+PGM sending is rate limited rather than controlled by receivers. Thus, to get
+optimal performance you should set ZMQ_RATE and ZMQ_RECOVERY_IVL socket options
+prior to using PGM transport. Also note that passing multicast packets via
+loopback interface has negative effect on the overall performance of the system.
+Thus, if not needed, you should turn multicast loopback off using ZMQ_MCAST_LOOP
+socket option.
+
+PGM transport can be used only with ZMQ_PUB and ZMQ_SUB sockets.
+
+.SH CONNECTION STRING
+
+Connection string for PGM transport is "pgm://" followed by an IP adress
+of the NIC to use, semicolon, IP adress of the multicast group, colon and
+port numbrt. IP address of the NIC can be either its numeric representation
+or the name of the NIC as reported by operating system. IP address of the
+mutlicast group should be specified in the numeric representation. For example:
+
+.nf
+    pgm://eth0:224.0.0.1:5555
+    pgm://lo:230.0.0.0:6666
+    pgm://192.168.0.111:224.0.0.1:5555
+.fi
+
+.SH WIRE FORMAT
+
+Consecutive PGM packets are interpreted as a single continuous stream of data.
+The data is then split into messages using the wire format described in
+.IR zmq_tcp(7) .
+Thus, messages are not aligned with packet boundaries and each message can start
+at an arbitrary position within the packet and span several packets.
+
+Given this wire format, it would be impossible for late joining consumers to
+identify message boundaries. To solve this problem, each PGM packet payload
+starts with 16-bit unsigned integer in network byte order which specifies the
+offset of the first message in the packet. If there's no beginning of a message
+in the packet (it's a packet transferring inner part of a larger message)
+the value of the initial integer is 0xFFFF.
+
+Each packet thus looks like this:
+
+.nf
++-----------+------------+------------------+--------
+| IP header | PGM header | offset (16 bits) | data .....
++-----------+------------+------------------+--------
+.fi
+
+Following example shows how messages are arranged in subsequent packets:
+
+.nf
++---------------+--------+-----------+-----------------------------+
+| PGM/IPheaders | 0x0000 |   message 1   |   message 2 (part 1)    |
++---------------+--------+-----------+-----------------------------+
+
++---------------+--------+-----------------------------------------+
+| PGM/IPheaders | 0xFFFF |           message 2 (part 2)            |
++---------------+--------+-----------------------------------------+
+
++---------------+--------+--------------------------+-----------+
+| PGM/IPheaders | 0x0008 | message 2 (last 8 bytes) | message 3 |
++---------------+--------+--------------------------+-----------+
+.fi
+
 .SH "SEE ALSO"
+
+.BR zmq_udp (7)
+.BR zmq_tcp (7)
+.BR zmq_inproc (7)
+.BR zmq_setsockopt (3)
+
 .SH AUTHOR
 Martin Sustrik <sustrik at 250bpm dot com>
 
+
diff --git a/man/man7/zmq_tcp.7 b/man/man7/zmq_tcp.7
index 391215e..aa3f56e 100644
--- a/man/man7/zmq_tcp.7
+++ b/man/man7/zmq_tcp.7
@@ -64,6 +64,11 @@ Binary layout of a larger message:
 .fi
 
 .SH "SEE ALSO"
+
+.BR zmq_udp (7)
+.BR zmq_pgm (7)
+.BR zmq_inproc (7)
+
 .SH AUTHOR
 Martin Sustrik <sustrik at 250bpm dot com>
 
diff --git a/man/man7/zmq_udp.7 b/man/man7/zmq_udp.7
index 16cbf08..bfebc1c 100644
--- a/man/man7/zmq_udp.7
+++ b/man/man7/zmq_udp.7
@@ -2,8 +2,38 @@
 .SH NAME
 UDP-based tranport for 0MQ
 .SH SYNOPSIS
-.SH DESCRIPTION
+
+UDP transport is exactly the same as PGM transport except that PGM packets
+are encapsulated in UDP packets. Rationale for this transport is that user-space
+implementation of PGM requires right to create raw sockets (PGM is located
+directly on top of IP layer in the netwroking stack), which is often not
+available. UDP encapsulation solves this problem, however, it adds some overhead
+related to creating and transferring UDP packet headers.
+
+.SH CONNECTION STRING
+
+Connection string for UDP transport is "udp://" followed by an IP adress
+of the NIC to use, semicolon, IP adress of the multicast group, colon and
+port numbrt. IP address of the NIC can be either its numeric representation
+or the name of the NIC as reported by operating system. IP address of the
+mutlicast group should be specified in the numeric representation. For example:
+
+.nf
+    udp://eth0:224.0.0.1:5555
+    udp://lo:230.0.0.0:6666
+    udp://192.168.0.111:224.0.0.1:5555
+.fi
+
+.SH WIRE FORMAT
+
+Same as with PGM transport except for UDP packet headers.
+
 .SH "SEE ALSO"
+
+.BR zmq_pgm (7)
+.BR zmq_tcp (7)
+.BR zmq_inproc (7)
+
 .SH AUTHOR
 Martin Sustrik <sustrik at 250bpm dot com>