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

FreeBSD Manual Pages

  
 
  

home | help
IO::Socket::Multicast6User Contributed Perl DocumentaIO::Socket::Multicast6(3)

NAME
       IO::Socket::Multicast6 -	Send and receive IPv4 and IPv6 multicast
       messages

SYNOPSIS
	 use IO::Socket::Multicast6;

	 # create a new	IPv6 UDP socket	ready to read datagrams	on port	1100
	 my $s = IO::Socket::Multicast6->new(
				       Domain=>AF_INET6,
				       LocalPort=>1100);

	 # Add an IPv6 multicast group
	 $s->mcast_add('FF15::0561');

	 # now receive some multicast data
	 $s->recv($data,1024);

	 # Drop	a multicast group
	 $s->mcast_drop('FF15::0561');

	 # create a new	IPv4 UDP socket	ready to send datagrams	to port	1100
	 my $s = IO::Socket::Multicast6->new(
				       Domain=>AF_INET,
				       PeerDest=>'225.0.0.1',
				       PeerPort=>1100);

	 # Set outgoing	interface to eth0
	 $s->mcast_if('eth0');

	 # Set time to live on outgoing	multicast packets
	 $s->mcast_ttl(10);

	 # Turn	off loopbacking
	 $s->mcast_loopback(0);

	 # Multicast a message to group
	 $s->send( 'hello world!' );

DESCRIPTION
       The IO::Socket::Multicast6 module subclasses IO::Socket::INET6 to
       enable you to manipulate	multicast groups.  With	this module you	will
       be able to receive incoming multicast transmissions and generate	your
       own outgoing multicast packets.

       This module uses	the same API as	IO::Socket::Multicast, but with	added
       support for IPv6	(IPv4 is still supported). Unlike
       IO::Socket::Multicast, this is a	pure-perl module.

   DEPENDENCIES
       This module depends on a	number of other	modules:

	 Socket6 version 0.19 or higher.
	 IO::Socket::INET6 version 2.51	or higher.
	 IO::Interface version 1.01 or higher.
	 Socket::Multicast6 0.01 or higher.

       Your operating system must have IPv6 and	Multicast support.

   INTRODUCTION
       Multicasting is designed	for streaming multimedia applications and for
       conferencing systems in which one transmitting machines needs to
       distribute data to a large number of clients.

       IPv4 addresses in the range 224.0.0.0 and 239.255.255.255 are reserved
       for multicasting.  IPv6 multicast addresses start with the prefix FF.
       These addresses do not correspond to individual machines, but to
       multicast groups.  Messages sent	to these addresses will	be delivered
       to a potentially	large number of	machines that have registered their
       interest	in receiving transmissions on these groups.  They work like TV
       channels.  A program tunes in to	a multicast group to receive
       transmissions to	it, and	tunes out when it no longer wishes to receive
       the transmissions.

       To receive transmissions	from a multicast group,	you will use
       IO::Socket::INET->new() to create a UDP socket and bind it to a local
       network port.  You will then subscribe one or more multicast groups
       using the mcast_add() method.  Subsequent calls to the standard recv()
       method will now receive messages	incoming messages transmitted to the
       subscribed groups using the selected port number.

       To send transmissions to	a multicast group, you can use the standard
       send() method to	send messages to the multicast group and port of your
       choice.

       To set the number of hops (routers) that	outgoing multicast messages
       will cross, call	mcast_ttl().  To activate or deactivate	the looping
       back of multicast messages (in which a copy of the transmitted messages
       is received by the local	machine), call mcast_loopback().

   CONSTRUCTORS
       $socket = IO::Socket::Multicast6->new([LocalPort=>$port,...])
	   The new() method is the constructor for the IO::Socket::Multicast6
	   class.  It takes the	same arguments as IO::Socket::INET, except
	   that	the Proto argument, rather than	defaulting to "tcp", will
	   default to "udp", which is more appropriate for multicasting.

	   To create a UDP socket suitable for sending outgoing	multicast
	   messages, call new()	without	no arguments (or with "Proto=>'udp'").
	   To create a UDP socket that can also	receive	incoming multicast
	   transmissions on a specific port, call new()	with the LocalPort
	   argument.

	   If you plan to run the client and server on the same	machine, you
	   may wish to set the IO::Socket ReuseAddr argument to	a true value.
	   This	allows multiple	multicast sockets to bind to the same address.

   METHODS
       $success	= $socket->mcast_add($multicast_address	[,$interface])
	   The mcast_add() method will add the provided	multicast address to
	   the list of subscribed multicast groups.  The address may be
	   provided either as a	dotted-quad decimal, or	as a packed IP address
	   (such as produced by	the inet_aton()	function).  On success,	the
	   method will return a	true value.

	   The optional	$interface argument can	be used	to specify on which
	   network interface to	listen for incoming multicast messages.	 If
	   the IO::Interface module is installed, you may use the device name
	   for the interface (e.g. "tu0").  Otherwise, you must	use the	IP
	   address of the desired network interface.  Either dotted quad form
	   or packed IP	address	is acceptable.	If no interface	is specified,
	   then	the multicast group is joined on INADDR_ANY, meaning that
	   multicast transmissions received on any of the host's network
	   interfaces will be forwarded	to the socket.

	   Note	that mcast_add() operates on the underlying interface(s) and
	   not on the socket. If you have multiple sockets listening on	a
	   port, and you mcast_add() a group to	one of those sockets,
	   subsequently	all the	sockets	will receive mcast messages on this
	   group. To filter messages that can be received by a socket so that
	   only	those sent to a	particular multicast address are received,
	   pass	the LocalAddr option to	the socket at the time you create it:

	     my	$socket	= IO::Socket::Multicast6->new(LocalPort=>2000,
						     LocalAddr=>226.1.1.2',
						     ReuseAddr=>1);
	     $socket->mcast_add('226.1.1.2');

	   By combining	this technique with IO::Select,	you can	write
	   applications	that listen to multiple	multicast groups and
	   distinguish which group a message was addressed to by identifying
	   which socket	it was received	on.

       $success	= $socket->mcast_add_source($multicast_add, $source_addr
       [,$interface])
	   Same	as mcast_add() but for Source Specific Multicast (SSM).

       $success	= $socket->mcast_drop($multicast_address)
	   This	reverses the action of mcast_add(), removing the indicated
	   multicast address from the list of subscribed groups.

       $loopback = $socket->mcast_loopback
       $previous = $socket->mcast_loopback($new)
	   The mcast_loopback()	method controls	whether	the socket will
	   receive its own multicast transmissions (default yes).  Called
	   without arguments, the method returns the current state of the
	   loopback flag. Called with a	boolean	argument, the method will set
	   the loopback	flag, and return its previous value.

       $ttl = $socket->mcast_ttl
       $previous = $socket->mcast_ttl($new)
	   The mcast_ttl() method examines or sets the time to live (TTL) for
	   outgoing multicast messages.	 The TTL controls the numbers of
	   routers the packet can cross	before being expired.  The default TTL
	   is 1, meaning that the message is confined to the local area
	   network.  Values between 0 and 255 are valid.

	   Called without arguments, this method returns the socket's current
	   TTL.	 Called	with a value, this method sets the TTL and returns its
	   previous value.

       $interface = $socket->mcast_if
       $previous = $socket->mcast_if($new)
	   By default, the OS will pick	the network interface to use for
	   outgoing multicasts automatically.  You can control this process by
	   using the mcast_if()	method to set the outgoing network interface
	   explicitly.	Called without arguments, returns the current
	   interface.  Called with the name of an interface, sets the outgoing
	   interface and returns its previous value.

	   You can use the device name for the interface (e.g. "tu0") if the
	   IO::Interface module	is present.  Otherwise,	you must use the
	   interface's dotted IP address.

	   NOTE: To set	the interface used for incoming	multicasts, use	the
	   mcast_add() method.

       $dest = $socket->mcast_dest
       $previous = $socket->mcast_dest($address	[, $port])
	   The mcast_dest() method is a	convenience function that allows you
	   to set the default destination group	for outgoing multicasts.
	   Called without arguments, returns the current destination as	a
	   packed binary sockaddr_in/sockaddr_in6 data structure.  Called with
	   a new destination address, the method sets the default destination
	   and returns the previous one, if any.

	   Destination addresses may be	provided as packed
	   sockaddr_in/sockaddr_in6 structures,	or address and port as
	   strings.

	   For IPv4 the	address	can be supplied	in the form "XX.XX.XX.XX:YY"
	   where the first part	is the IPv4 address, and the second the	port
	   number.

	   For IPv6 the	address	can be supplied	in the form
	   "[FFXX:XXXX::XXXX]:YY" where	the first part is the IPv6 address,
	   and the second the port number.

	   Alternatively the port can be supplied as an	additional parameter,
	   separate to the address.

       $bytes =	$socket->mcast_send($data [,$address [,$port]])
	   mcast_send()	is a convenience function that simplifies the sending
	   of multicast	messages.  $data is the	message	contents, and $dest is
	   an optional destination group.  You can use either the dotted IP
	   form	of the destination address and its port	number,	or a packed
	   sockaddr_in/sockaddr_in6 structure.	If the destination is not
	   supplied, it	will default to	the most recent	value set in
	   mcast_dest()	or a previous call to mcast_send().

	   The method returns the number of bytes successfully queued for
	   delivery.

	   As a	side-effect, the method	will call mcast_dest() to remember the
	   destination address.

	   Example:

	     $socket->mcast_send('Hi there group members!','225.0.1.1:1900') ||	die;
	     $socket->mcast_send("How's	the weather?") || die;

	   Note	that you may still call	IO::Socket::INET6->new() with a
	   PeerAddr, and IO::Socket::INET6 will	perform	a connect(), creating
	   a default destination for calls to send().

EXAMPLE
       The following is	an example of a	multicast server.  Every 10 seconds it
       transmits the current time and the list of logged-in users to the local
       network using multicast group FF15::0561, port 2000 (these are chosen
       arbitrarily, the	FF15:: is a Transient, Site Local prefix).

	#!/usr/bin/perl
	# server (transmitter)
	use strict;
	use IO::Socket::Multicast6;

	use constant GROUP => 'FF15::0561';
	use constant PORT  => '2000';

	my $sock = IO::Socket::Multicast6->new(
			   Proto=>'udp',
			   Domain=>AF_INET6,
			   PeerAddr=>GROUP,
			   PeerPort=>PORT);

	while (1) {
	   my $message = localtime();
	   $sock->send($message) || die	"Couldn't send:	$!";
	} continue {
	   sleep 4;
	}

       This is the corresponding client.  It listens for transmissions on
       group FF15::0561, port 2000, and	echoes the messages to standard
       output.

	#!/usr/bin/perl
	# client (receiver)

	use strict;
	use IO::Socket::Multicast6;

	use constant GROUP => 'FF15::0561';
	use constant PORT  => '2000';

	my $sock = IO::Socket::Multicast6->new(
			   Proto=>'udp',
			   Domain=>AF_INET6,
			   LocalAddr=>GROUP,
			   LocalPort=>PORT);

	$sock->mcast_add(GROUP)	|| die "Couldn't set group: $!\n";

	while (1) {
	   my $data;
	   next	unless $sock->recv($data,1024);
	   print "$data\n";
	}

   BUGS
       The mcast_if(), mcast_ttl() and mcast_loopback()	methods	will cause a
       crash on	versions of Linux earlier than 2.2.0 because of	a kernel bug
       in the implementation of	the multicast socket options.

SEE ALSO
       <http://www.ietf.org/rfc/rfc2553.txt>

       perl(1),	IO::Socket(3), Socket::Multicast6(3), IO::Socket::INET6(3).

AUTHOR
       Based on	IO::Socket::Multicast by Lincoln Stein,	lstein@cshl.org.

       IO::Socket::Multicast6 by Nicholas J Humfrey, <njh@cpan.org>.

COPYRIGHT AND LICENSE
       Copyright (C) 2006-2009 Nicholas	J Humfrey Copyright (C)	2000-2005
       Lincoln Stein

       This library is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself, either Perl	version	5.6.1 or, at
       your option, any	later version of Perl 5	you may	have available.

perl v5.24.1			  2017-07-02	     IO::Socket::Multicast6(3)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLE | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

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

home | help