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

FreeBSD Manual Pages

  
 
  

home | help
IO::Socket::Multicast(User Contributed Perl DocumentatIO::Socket::Multicast(3)

NAME
       IO::Socket::Multicast - Send and	receive	multicast messages

SYNOPSIS
	 use IO::Socket::Multicast;

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

	 # Add a multicast group
	 $s->mcast_add('225.0.1.1');

	 # Add a multicast group to eth0 device
	 $s->mcast_add('225.0.0.2','eth0');

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

	 # Drop	a multicast group
	 $s->mcast_drop('225.0.0.1');

	 # 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	225.0.0.1
	 $s->mcast_send('hello world!','225.0.0.1:1200');
	 $s->mcast_set('225.0.0.2:1200');
	 $s->mcast_send('hello again!');

DESCRIPTION
       The IO::Socket::Multicast module	subclasses IO::Socket::INET to enable
       you to manipulate multicast groups.  With this module (and an operating
       system that supports multicasting), you will be able to receive
       incoming	multicast transmissions	and generate your own outgoing
       multicast packets.

       This module requires IO::Interface version 0.94 or higher.

   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.

       IP addresses in the range 224.0.0.0 and 239.255.255.255 are reserved
       for multicasting.  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::Multicast->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.	The mcast_set()	and mcast_send() methods are provided as
       convenience functions.  Mcast_set() will	set a default multicast
       destination for messages	which you then send with mcast_send().

       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::Multicast->new([LocalPort=>$port,...])
	   The new() method is the constructor for the IO::Socket::Multicast
	   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	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::Multicast->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_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($new)
	   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 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
	   structures, or in the form "XX.XX.XX.XX:YY" where the first part is
	   the IP address, and the second the port number.

       $bytes =	$socket->mcast_send($data [,$dest])
	   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 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::Multicast->new() with a
	   PeerAddr, and IO::Socket::INET 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 226.1.1.2,	port 2000 (these are chosen
       arbitrarily).

	#!/usr/bin/perl
	# server
	use strict;
	use IO::Socket::Multicast;

	use constant DESTINATION => '226.1.1.2:2000';
	my $sock = IO::Socket::Multicast->new(Proto=>'udp',PeerAddr=>DESTINATION);

	while (1) {
	  my $message =	localtime;
	  $message .= "\n" . `who`;
	  $sock->send($message)	|| die "Couldn't send: $!";
	} continue {
	  sleep	10;
	}

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

	#!/usr/bin/perl
	# client

	use strict;
	use IO::Socket::Multicast;

	use constant GROUP => '226.1.1.2';
	use constant PORT  => '2000';

	my $sock = IO::Socket::Multicast->new(Proto=>'udp',LocalPort=>PORT);
	$sock->mcast_add(GROUP)	|| die "Couldn't set group: $!\n";

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

   EXPORT
       None by default.	 However, if you wish to call mcast_add(),
       mcast_drop(), mcast_if(), mcast_loopback(), mcast_ttl, mcast_dest() and
       mcast_send() as functions you may import	them explicitly	on the use
       line or by importing the	tag ":functions".

   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.

AUTHOR
       Lincoln Stein, lstein@cshl.org.

       This module is distributed under	the same terms as Perl itself.

SEE ALSO
       perl(1),	IO::Socket(3), IO::Socket::INET(3).

perl v5.24.1			  2010-04-28	      IO::Socket::Multicast(3)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLE | AUTHOR | SEE ALSO

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

home | help