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

FreeBSD Manual Pages

  
 
  

home | help
XS_PGM(7)		     Crossroads	I/O Manual		     XS_PGM(7)

NAME
       xs_pgm -	reliable multicast transport via PGM protocol

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

DESCRIPTION
       Crossroads implement 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 XS_PUB and	XS_SUB
       socket types.

       Further,	PGM sockets are	rate limited by	default. For details, refer to
       the XS_RATE, and	XS_RECOVERY_IVL	options	documented in
       xs_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 Crossroads 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	xs_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 it's 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	it's
       numeric representation.

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

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

	   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 Crossroads
       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 =	xs_connect(socket, "epgm://eth0;239.192.1.1:5555");
	   assert (rc != -1);
	   /* 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 =	xs_connect(socket, "pgm://192.168.1.1;239.192.1.1:5555");
	   assert (rc != -1);

SEE ALSO
       xs_connect(3) xs_setsockopt(3) xs_tcp(7)	xs_ipc(7) xs_inproc(7) xs(7)

AUTHORS
       The Crossroads documentation was	written	by Martin Sustrik
       <sustrik@250bpm.com[1]> and Martin Lucina <martin@lucina.net[2]>.

NOTES
	1. sustrik@250bpm.com
	   mailto:sustrik@250bpm.com

	2. martin@lucina.net
	   mailto:martin@lucina.net

Crossroads I/O 1.2.0		  04/29/2017			     XS_PGM(7)

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

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

home | help