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.