Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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" or EPGM 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. For details, refer to
       the ZMQ_RATE, and ZMQ_RECOVERY_IVL 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 endpoint is a string consisting of	a transport:// followed	by an
       address.	The transport specifies	the underlying protocol	to use.	The
       address specifies the transport-specific	address	to connect to.

       For the PGM transport, the transport is pgm, and	for the	EPGM protocol
       the transport is	epgm. The meaning of the address part 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.	The interface part can be
	   omitted, in that case the default one will be selected.

       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 page was written by	the 0MQ	community. To make a change please
       read the	0MQ Contribution Policy	at
       http://www.zeromq.org/docs:contributing.

0MQ 4.1.5			  07/02/2017			    ZMQ_PGM(7)

NAME | SYNOPSIS | DESCRIPTION | ADDRESSING | WIRE FORMAT | EXAMPLE | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=zmq_pgm&sektion=7&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help