DragonFly On-Line Manual Pages

ZMQ_PGM(7)                        0MQ Manual                        ZMQ_PGM(7)

NAME
       zmq_pgm - 0MQ reliable multicast transport using PGM

SYNOPSIS
       PGM (Pragmatic General Multicast) is a protocol for reliable multicast
       transport of data over IP networks.

DESCRIPTION
       0MQ implements two variants of PGM, the standard protocol where PGM
       datagrams are layered directly on top of IP datagrams as defined by RFC
       3208 (the pgm transport) and "Encapsulated PGM" where PGM datagrams are
       encapsulated inside UDP datagrams (the epgm transport).

       The pgm and epgm transports can only be used with the ZMQ_PUB and
       ZMQ_SUB socket types.

       Further, PGM sockets are rate limited by default and incur a
       performance penalty when used over a loop-back interface. For details,
       refer to the ZMQ_RATE, ZMQ_RECOVERY_IVL and ZMQ_MCAST_LOOP options
       documented in zmq_setsockopt(3).

           Caution

           The pgm transport implementation requires access to raw IP sockets.
           Additional privileges may be required on some operating systems for
           this operation. Applications not requiring direct interoperability
           with other PGM implementations are encouraged to use the epgm
           transport instead which does not require any special privileges.

ADDRESSING
       A 0MQ address string consists of two parts as follows:
       transport://endpoint. The transport part specifies the underlying
       transport protocol to use. For the standard PGM protocol, transport
       shall be set to pgm. For the "Encapsulated PGM" protocol transport
       shall be set to epgm. The meaning of the endpoint part for both the pgm
       and epgm transport is defined below.

   Connecting a socket
       When connecting a socket to a peer address using zmq_connect() with the
       pgm or epgm transport, the endpoint shall be interpreted as an
       interface followed by a semicolon, followed by a multicast address,
       followed by a colon and a port number.

       An interface may be specified by either of the following:

       o   The interface name as defined by the operating system.

       o   The primary IPv4 address assigned to the interface, in its numeric
           representation.

           Note

           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 interface.

       A multicast address is specified by an IPv4 multicast address in its
       numeric representation.

WIRE FORMAT
       Consecutive PGM datagrams are interpreted by 0MQ as a single continuous
       stream of data where 0MQ messages are not necessarily aligned with PGM
       datagram boundaries and a single 0MQ message may span several PGM
       datagrams. This stream of data consists of 0MQ messages encapsulated in
       frames as described in zmq_tcp(7).

   PGM datagram payload
       The following ABNF grammar represents the payload of a single PGM
       datagram as used by 0MQ:

           datagram               = (offset data)
           offset                 = 2OCTET
           data                   = *OCTET

       In order for late joining consumers to be able to identify message
       boundaries, each PGM datagram payload starts with a 16-bit unsigned
       integer in network byte order specifying either the offset of the first
       message frame in the datagram or containing the value 0xFFFF if the
       datagram contains solely an intermediate part of a larger message.

       Note that offset specifies where the first message begins rather than
       the first message part. Thus, if there are trailing message parts at
       the beginning of the packet the offset ignores them and points to first
       initial message part in the packet.

       The following diagram illustrates the layout of a single PGM datagram
       payload:

           +------------------+----------------------+
           | offset (16 bits) |         data         |
           +------------------+----------------------+

       The following diagram further illustrates how three example 0MQ frames
       are laid out in consecutive PGM datagram payloads:

           First datagram payload
           +--------------+-------------+---------------------+
           | Frame offset |   Frame 1   |   Frame 2, part 1   |
           |    0x0000    | (Message 1) | (Message 2, part 1) |
           +--------------+-------------+---------------------+

           Second datagram payload
           +--------------+---------------------+
           | Frame offset |   Frame 2, part 2   |
           | 0xFFFF       | (Message 2, part 2) |
           +--------------+---------------------+

           Third datagram payload
           +--------------+----------------------------+-------------+
           | Frame offset |   Frame 2, final 8 bytes   |   Frame 3   |
           | 0x0008       | (Message 2, final 8 bytes) | (Message 3) |
           +--------------+----------------------------+-------------+

EXAMPLE
       Connecting a socket.

           /* Connecting to the multicast address 239.192.1.1, port 5555, */
           /* using the first Ethernet network interface on Linux */
           /* and the Encapsulated PGM protocol */
           rc = zmq_connect(socket, "epgm://eth0;239.192.1.1:5555");
           assert (rc == 0);
           /* Connecting to the multicast address 239.192.1.1, port 5555, */
           /* using the network interface with the address 192.168.1.1 */
           /* and the standard PGM protocol */
           rc = zmq_connect(socket, "pgm://192.168.1.1;239.192.1.1:5555");
           assert (rc == 0);

SEE ALSO
       zmq_connect(3) zmq_setsockopt(3) zmq_tcp(7) zmq_ipc(7) zmq_inproc(7)
       zmq(7)

AUTHORS
       This manual page was written by the 0MQ community.

0MQ 2.2.0                         04/04/2012                        ZMQ_PGM(7)