Provided by: libio-socket-multicast6-perl_0.03-2_all bug

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.