.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "IO::Socket::Multicast 3pm"
.TH IO::Socket::Multicast 3pm "2018-11-02" "perl v5.28.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
IO::Socket::Multicast \- Send and receive multicast messages
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  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(\*(Aq225.0.1.1\*(Aq);
\&
\&  # Add a multicast group to eth0 device
\&  $s\->mcast_add(\*(Aq225.0.0.2\*(Aq,\*(Aqeth0\*(Aq);
\&
\&  # now receive some multicast data
\&  $s\->recv($data,1024);
\&
\&  # Drop a multicast group
\&  $s\->mcast_drop(\*(Aq225.0.0.1\*(Aq);
\&
\&  # Set outgoing interface to eth0
\&  $s\->mcast_if(\*(Aqeth0\*(Aq);
\&
\&  # 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(\*(Aqhello world!\*(Aq,\*(Aq225.0.0.1:1200\*(Aq);
\&  $s\->mcast_set(\*(Aq225.0.0.2:1200\*(Aq);
\&  $s\->mcast_send(\*(Aqhello again!\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
This module requires IO::Interface version 0.94 or higher.
.SS "\s-1INTRODUCTION\s0"
.IX Subsection "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.
.PP
\&\s-1IP\s0 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 \s-1TV\s0 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.
.PP
To receive transmissions \fBfrom\fR a multicast group, you will use
IO::Socket::Multicast\->\fBnew()\fR to create a \s-1UDP\s0 socket and bind it to a local
network port.  You will then subscribe one or more multicast groups
using the \fBmcast_add()\fR method.  Subsequent calls to the standard \fBrecv()\fR
method will now receive messages incoming messages transmitted to the
subscribed groups using the selected port number.
.PP
To send transmissions \fBto\fR a multicast group, you can use the
standard \fBsend()\fR method to send messages to the multicast group and
port of your choice.  The \fBmcast_set()\fR and \fBmcast_send()\fR methods are
provided as convenience functions.  \fBMcast_set()\fR will set a default
multicast destination for messages which you then send with
\&\fBmcast_send()\fR.
.PP
To set the number of hops (routers) that outgoing multicast messages
will cross, call \fBmcast_ttl()\fR.  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 \fBmcast_loopback()\fR.
.SS "\s-1CONSTRUCTORS\s0"
.IX Subsection "CONSTRUCTORS"
.ie n .IP "$socket = IO::Socket::Multicast\->new([LocalPort=>$port,...])" 4
.el .IP "\f(CW$socket\fR = IO::Socket::Multicast\->new([LocalPort=>$port,...])" 4
.IX Item "$socket = IO::Socket::Multicast->new([LocalPort=>$port,...])"
The \fBnew()\fR method is the constructor for the IO::Socket::Multicast
class.  It takes the same arguments as IO::Socket::INET, except that
the \fBProto\fR argument, rather than defaulting to \*(L"tcp\*(R", will default
to \*(L"udp\*(R", which is more appropriate for multicasting.
.Sp
To create a \s-1UDP\s0 socket suitable for sending outgoing multicast
messages, call \fBnew()\fR without arguments (or with
\&\f(CW\*(C`Proto=>\*(Aqudp\*(Aq\*(C'\fR).  To create a \s-1UDP\s0 socket that can also receive
incoming multicast transmissions on a specific port, call \fBnew()\fR with
the \fBLocalPort\fR argument.
.Sp
If you plan to run the client and server on the same machine, you may
wish to set the IO::Socket \fBReuseAddr\fR argument to a true value.
This allows multiple multicast sockets to bind to the same address.
.SS "\s-1METHODS\s0"
.IX Subsection "METHODS"
.ie n .IP "$success = $socket\->mcast_add($multicast_address [,$interface])" 4
.el .IP "\f(CW$success\fR = \f(CW$socket\fR\->mcast_add($multicast_address [,$interface])" 4
.IX Item "$success = $socket->mcast_add($multicast_address [,$interface])"
The \fBmcast_add()\fR 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 \s-1IP\s0 address (such as
produced by the \fBinet_aton()\fR function).  On success, the method will
return a true value.
.Sp
The optional \f(CW$interface\fR 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. \*(L"tu0\*(R").  Otherwise, you must use the \s-1IP\s0 address of the
desired network interface.  Either dotted quad form or packed \s-1IP\s0
address is acceptable.  If no interface is specified, then the
multicast group is joined on \s-1INADDR_ANY,\s0 meaning that multicast
transmissions received on \fBany\fR of the host's network interfaces will
be forwarded to the socket.
.Sp
Note that \fBmcast_add()\fR operates on the underlying interface(s) and not
on the socket. If you have multiple sockets listening on a port, and
you \fBmcast_add()\fR a group to one of those sockets, subsequently \fBall\fR
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 \fBLocalAddr\fR
option to the socket at the time you create it:
.Sp
.Vb 4
\&  my $socket = IO::Socket::Multicast\->new(LocalPort=>2000,
\&                                          LocalAddr=>226.1.1.2\*(Aq,
\&                                          ReuseAddr=>1);
\&  $socket\->mcast_add(\*(Aq226.1.1.2\*(Aq);
.Ve
.Sp
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.
.ie n .IP "$success = $socket\->mcast_drop($multicast_address)" 4
.el .IP "\f(CW$success\fR = \f(CW$socket\fR\->mcast_drop($multicast_address)" 4
.IX Item "$success = $socket->mcast_drop($multicast_address)"
This reverses the action of \fBmcast_add()\fR, removing the indicated
multicast address from the list of subscribed groups.
.ie n .IP "$loopback = $socket\->mcast_loopback" 4
.el .IP "\f(CW$loopback\fR = \f(CW$socket\fR\->mcast_loopback" 4
.IX Item "$loopback = $socket->mcast_loopback"
.PD 0
.ie n .IP "$previous = $socket\->mcast_loopback($new)" 4
.el .IP "\f(CW$previous\fR = \f(CW$socket\fR\->mcast_loopback($new)" 4
.IX Item "$previous = $socket->mcast_loopback($new)"
.PD
The \fBmcast_loopback()\fR 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.
.ie n .IP "$ttl = $socket\->mcast_ttl" 4
.el .IP "\f(CW$ttl\fR = \f(CW$socket\fR\->mcast_ttl" 4
.IX Item "$ttl = $socket->mcast_ttl"
.PD 0
.ie n .IP "$previous = $socket\->mcast_ttl($new)" 4
.el .IP "\f(CW$previous\fR = \f(CW$socket\fR\->mcast_ttl($new)" 4
.IX Item "$previous = $socket->mcast_ttl($new)"
.PD
The \fBmcast_ttl()\fR method examines or sets the time to live (\s-1TTL\s0) for
outgoing multicast messages.  The \s-1TTL\s0 controls the numbers of routers
the packet can cross before being expired.  The default \s-1TTL\s0 is 1,
meaning that the message is confined to the local area network.
Values between 0 and 255 are valid.
.Sp
Called without arguments, this method returns the socket's current
\&\s-1TTL.\s0  Called with a value, this method sets the \s-1TTL\s0 and returns its
previous value.
.ie n .IP "$interface = $socket\->mcast_if" 4
.el .IP "\f(CW$interface\fR = \f(CW$socket\fR\->mcast_if" 4
.IX Item "$interface = $socket->mcast_if"
.PD 0
.ie n .IP "$previous = $socket\->mcast_if($new)" 4
.el .IP "\f(CW$previous\fR = \f(CW$socket\fR\->mcast_if($new)" 4
.IX Item "$previous = $socket->mcast_if($new)"
.PD
By default, the \s-1OS\s0 will pick the network interface to use for outgoing
multicasts automatically.  You can control this process by using the
\&\fBmcast_if()\fR 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.
.Sp
You can use the device name for the interface (e.g. \*(L"tu0\*(R") if the
IO::Interface module is present.  Otherwise, you must use the
interface's dotted \s-1IP\s0 address.
.Sp
\&\fB\s-1NOTE\s0\fR: To set the interface used for \fBincoming\fR multicasts, use the
\&\fBmcast_add()\fR method.
.ie n .IP "$dest = $socket\->mcast_dest" 4
.el .IP "\f(CW$dest\fR = \f(CW$socket\fR\->mcast_dest" 4
.IX Item "$dest = $socket->mcast_dest"
.PD 0
.ie n .IP "$previous = $socket\->mcast_dest($new)" 4
.el .IP "\f(CW$previous\fR = \f(CW$socket\fR\->mcast_dest($new)" 4
.IX Item "$previous = $socket->mcast_dest($new)"
.PD
The \fBmcast_dest()\fR 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.
.Sp
Destination addresses may be provided as packed sockaddr_in
structures, or in the form \*(L"\s-1XX.XX.XX.XX:YY\*(R"\s0 where the first part is
the \s-1IP\s0 address, and the second the port number.
.ie n .IP "$bytes = $socket\->mcast_send($data [,$dest])" 4
.el .IP "\f(CW$bytes\fR = \f(CW$socket\fR\->mcast_send($data [,$dest])" 4
.IX Item "$bytes = $socket->mcast_send($data [,$dest])"
\&\fBMcast_send()\fR is a convenience function that simplifies the sending of
multicast messages.  \f(CW$data\fR is the message contents, and \f(CW$dest\fR is
an optional destination group.  You can use either the dotted \s-1IP\s0 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 \fBmcast_dest()\fR or a previous
call to \fBmcast_send()\fR.
.Sp
The method returns the number of bytes successfully queued for
delivery.
.Sp
As a side-effect, the method will call \fBmcast_dest()\fR to remember the
destination address.
.Sp
Example:
.Sp
.Vb 2
\&  $socket\->mcast_send(\*(AqHi there group members!\*(Aq,\*(Aq225.0.1.1:1900\*(Aq) || die;
\&  $socket\->mcast_send("How\*(Aqs the weather?") || die;
.Ve
.Sp
Note that you may still call IO::Socket::Multicast\->\fBnew()\fR with a
\&\fBPeerAddr\fR, and IO::Socket::INET will perform a \fBconnect()\fR, creating a
default destination for calls to \fBsend()\fR.
.SH "EXAMPLE"
.IX Header "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).
.PP
.Vb 4
\& #!/usr/bin/perl
\& # server
\& use strict;
\& use IO::Socket::Multicast;
\&
\& use constant DESTINATION => \*(Aq226.1.1.2:2000\*(Aq; 
\& my $sock = IO::Socket::Multicast\->new(Proto=>\*(Aqudp\*(Aq,PeerAddr=>DESTINATION);
\&
\& while (1) {
\&   my $message = localtime;
\&   $message .= "\en" . \`who\`;
\&   $sock\->send($message) || die "Couldn\*(Aqt send: $!";
\& } continue {
\&   sleep 10;
\& }
.Ve
.PP
This is the corresponding client.  It listens for transmissions on
group 226.1.1.2, port 2000, and echoes the messages to standard
output.
.PP
.Vb 2
\& #!/usr/bin/perl
\& # client
\&
\& use strict;
\& use IO::Socket::Multicast;
\&
\& use constant GROUP => \*(Aq226.1.1.2\*(Aq;
\& use constant PORT  => \*(Aq2000\*(Aq;
\&
\& my $sock = IO::Socket::Multicast\->new(Proto=>\*(Aqudp\*(Aq,LocalPort=>PORT);
\& $sock\->mcast_add(GROUP) || die "Couldn\*(Aqt set group: $!\en";
\&
\& while (1) {
\&   my $data;
\&   next unless $sock\->recv($data,1024);
\&   print $data;
\& }
.Ve
.SS "\s-1EXPORT\s0"
.IX Subsection "EXPORT"
None by default.  However, if you wish to call \fBmcast_add()\fR,
\&\fBmcast_drop()\fR, \fBmcast_if()\fR, \fBmcast_loopback()\fR, mcast_ttl, \fBmcast_dest()\fR
and \fBmcast_send()\fR as functions you may import them explicitly on the
\&\fBuse\fR line or by importing the tag \*(L":functions\*(R".
.SS "\s-1BUGS\s0"
.IX Subsection "BUGS"
The \fBmcast_if()\fR, \fBmcast_ttl()\fR and \fBmcast_loopback()\fR 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.
.SH "AUTHOR"
.IX Header "AUTHOR"
Lincoln Stein, lstein@cshl.org.
.PP
This module is distributed under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBperl\fR\|(1), \fBIO::Socket\fR\|(3), \fBIO::Socket::INET\fR\|(3).