1IO::Socket::Multicast(3U)ser Contributed Perl DocumentatiIoOn::Socket::Multicast(3)
2
3
4

NAME

6       IO::Socket::Multicast - Send and receive multicast messages
7

SYNOPSIS

9         use IO::Socket::Multicast;
10
11         # create a new UDP socket ready to read datagrams on port 1100
12         my $s = IO::Socket::Multicast->new(LocalPort=>1100);
13
14         # Add a multicast group
15         $s->mcast_add('225.0.1.1');
16
17         # Add a multicast group to eth0 device
18         $s->mcast_add('225.0.0.2','eth0');
19
20         # now receive some multicast data
21         $s->recv($data,1024);
22
23         # Drop a multicast group
24         $s->mcast_drop('225.0.0.1');
25
26         # Set outgoing interface to eth0
27         $s->mcast_if('eth0');
28
29         # Set time to live on outgoing multicast packets
30         $s->mcast_ttl(10);
31
32         # Turn off loopbacking
33         $s->mcast_loopback(0);
34
35         # Multicast a message to group 225.0.0.1
36         $s->mcast_send('hello world!','225.0.0.1:1200');
37         $s->mcast_set('225.0.0.2:1200');
38         $s->mcast_send('hello again!');
39

DESCRIPTION

41       The IO::Socket::Multicast module subclasses IO::Socket::INET to enable
42       you to manipulate multicast groups.  With this module (and an operating
43       system that supports multicasting), you will be able to receive
44       incoming multicast transmissions and generate your own outgoing
45       multicast packets.
46
47       This module requires IO::Interface version 0.94 or higher.
48
49   INTRODUCTION
50       Multicasting is designed for streaming multimedia applications and for
51       conferencing systems in which one transmitting machines needs to
52       distribute data to a large number of clients.
53
54       IP addresses in the range 224.0.0.0 and 239.255.255.255 are reserved
55       for multicasting.  These addresses do not correspond to individual
56       machines, but to multicast groups.  Messages sent to these addresses
57       will be delivered to a potentially large number of machines that have
58       registered their interest in receiving transmissions on these groups.
59       They work like TV channels.  A program tunes in to a multicast group to
60       receive transmissions to it, and tunes out when it no longer wishes to
61       receive the transmissions.
62
63       To receive transmissions from a multicast group, you will use
64       IO::Socket::Multicast->new() to create a UDP socket and bind it to a
65       local network port.  You will then subscribe one or more multicast
66       groups using the mcast_add() method.  Subsequent calls to the standard
67       recv() method will now receive messages incoming messages transmitted
68       to the subscribed groups using the selected port number.
69
70       To send transmissions to a multicast group, you can use the standard
71       send() method to send messages to the multicast group and port of your
72       choice.  The mcast_set() and mcast_send() methods are provided as
73       convenience functions.  Mcast_set() will set a default multicast
74       destination for messages which you then send with mcast_send().
75
76       To set the number of hops (routers) that outgoing multicast messages
77       will cross, call mcast_ttl().  To activate or deactivate the looping
78       back of multicast messages (in which a copy of the transmitted messages
79       is received by the local machine), call mcast_loopback().
80
81   CONSTRUCTORS
82       $socket = IO::Socket::Multicast->new([LocalPort=>$port,...])
83           The new() method is the constructor for the IO::Socket::Multicast
84           class.  It takes the same arguments as IO::Socket::INET, except
85           that the Proto argument, rather than defaulting to "tcp", will
86           default to "udp", which is more appropriate for multicasting.
87
88           To create a UDP socket suitable for sending outgoing multicast
89           messages, call new() without arguments (or with "Proto=>'udp'").
90           To create a UDP socket that can also receive incoming multicast
91           transmissions on a specific port, call new() with the LocalPort
92           argument.
93
94           If you plan to run the client and server on the same machine, you
95           may wish to set the IO::Socket ReuseAddr argument to a true value.
96           This allows multiple multicast sockets to bind to the same address.
97
98   METHODS
99       $success = $socket->mcast_add($multicast_address [,$interface])
100           The mcast_add() method will add the provided multicast address to
101           the list of subscribed multicast groups.  The address may be
102           provided either as a dotted-quad decimal, or as a packed IP address
103           (such as produced by the inet_aton() function).  On success, the
104           method will return a true value.
105
106           The optional $interface argument can be used to specify on which
107           network interface to listen for incoming multicast messages.  If
108           the IO::Interface module is installed, you may use the device name
109           for the interface (e.g. "tu0").  Otherwise, you must use the IP
110           address of the desired network interface.  Either dotted quad form
111           or packed IP address is acceptable.  If no interface is specified,
112           then the multicast group is joined on INADDR_ANY, meaning that
113           multicast transmissions received on any of the host's network
114           interfaces will be forwarded to the socket.
115
116           Note that mcast_add() operates on the underlying interface(s) and
117           not on the socket. If you have multiple sockets listening on a
118           port, and you mcast_add() a group to one of those sockets,
119           subsequently all the sockets will receive mcast messages on this
120           group. To filter messages that can be received by a socket so that
121           only those sent to a particular multicast address are received,
122           pass the LocalAddr option to the socket at the time you create it:
123
124             my $socket = IO::Socket::Multicast->new(LocalPort=>2000,
125                                                     LocalAddr=>226.1.1.2',
126                                                     ReuseAddr=>1);
127             $socket->mcast_add('226.1.1.2');
128
129           By combining this technique with IO::Select, you can write
130           applications that listen to multiple multicast groups and
131           distinguish which group a message was addressed to by identifying
132           which socket it was received on.
133
134       $success = $socket->mcast_drop($multicast_address)
135           This reverses the action of mcast_add(), removing the indicated
136           multicast address from the list of subscribed groups.
137
138       $loopback = $socket->mcast_loopback
139       $previous = $socket->mcast_loopback($new)
140           The mcast_loopback() method controls whether the socket will
141           receive its own multicast transmissions (default yes).  Called
142           without arguments, the method returns the current state of the
143           loopback flag. Called with a boolean argument, the method will set
144           the loopback flag, and return its previous value.
145
146       $ttl = $socket->mcast_ttl
147       $previous = $socket->mcast_ttl($new)
148           The mcast_ttl() method examines or sets the time to live (TTL) for
149           outgoing multicast messages.  The TTL controls the numbers of
150           routers the packet can cross before being expired.  The default TTL
151           is 1, meaning that the message is confined to the local area
152           network.  Values between 0 and 255 are valid.
153
154           Called without arguments, this method returns the socket's current
155           TTL.  Called with a value, this method sets the TTL and returns its
156           previous value.
157
158       $interface = $socket->mcast_if
159       $previous = $socket->mcast_if($new)
160           By default, the OS will pick the network interface to use for
161           outgoing multicasts automatically.  You can control this process by
162           using the mcast_if() method to set the outgoing network interface
163           explicitly.  Called without arguments, returns the current
164           interface.  Called with the name of an interface, sets the outgoing
165           interface and returns its previous value.
166
167           You can use the device name for the interface (e.g. "tu0") if the
168           IO::Interface module is present.  Otherwise, you must use the
169           interface's dotted IP address.
170
171           NOTE: To set the interface used for incoming multicasts, use the
172           mcast_add() method.
173
174       $dest = $socket->mcast_dest
175       $previous = $socket->mcast_dest($new)
176           The mcast_dest() method is a convenience function that allows you
177           to set the default destination group for outgoing multicasts.
178           Called without arguments, returns the current destination as a
179           packed binary sockaddr_in data structure.  Called with a new
180           destination address, the method sets the default destination and
181           returns the previous one, if any.
182
183           Destination addresses may be provided as packed sockaddr_in
184           structures, or in the form "XX.XX.XX.XX:YY" where the first part is
185           the IP address, and the second the port number.
186
187       $bytes = $socket->mcast_send($data [,$dest])
188           Mcast_send() is a convenience function that simplifies the sending
189           of multicast messages.  $data is the message contents, and $dest is
190           an optional destination group.  You can use either the dotted IP
191           form of the destination address and its port number, or a packed
192           sockaddr_in structure.  If the destination is not supplied, it will
193           default to the most recent value set in mcast_dest() or a previous
194           call to mcast_send().
195
196           The method returns the number of bytes successfully queued for
197           delivery.
198
199           As a side-effect, the method will call mcast_dest() to remember the
200           destination address.
201
202           Example:
203
204             $socket->mcast_send('Hi there group members!','225.0.1.1:1900') || die;
205             $socket->mcast_send("How's the weather?") || die;
206
207           Note that you may still call IO::Socket::Multicast->new() with a
208           PeerAddr, and IO::Socket::INET will perform a connect(), creating a
209           default destination for calls to send().
210

EXAMPLE

212       The following is an example of a multicast server.  Every 10 seconds it
213       transmits the current time and the list of logged-in users to the local
214       network using multicast group 226.1.1.2, port 2000 (these are chosen
215       arbitrarily).
216
217        #!/usr/bin/perl
218        # server
219        use strict;
220        use IO::Socket::Multicast;
221
222        use constant DESTINATION => '226.1.1.2:2000';
223        my $sock = IO::Socket::Multicast->new(Proto=>'udp',PeerAddr=>DESTINATION);
224
225        while (1) {
226          my $message = localtime;
227          $message .= "\n" . `who`;
228          $sock->send($message) || die "Couldn't send: $!";
229        } continue {
230          sleep 10;
231        }
232
233       This is the corresponding client.  It listens for transmissions on
234       group 226.1.1.2, port 2000, and echoes the messages to standard output.
235
236        #!/usr/bin/perl
237        # client
238
239        use strict;
240        use IO::Socket::Multicast;
241
242        use constant GROUP => '226.1.1.2';
243        use constant PORT  => '2000';
244
245        my $sock = IO::Socket::Multicast->new(Proto=>'udp',LocalPort=>PORT);
246        $sock->mcast_add(GROUP) || die "Couldn't set group: $!\n";
247
248        while (1) {
249          my $data;
250          next unless $sock->recv($data,1024);
251          print $data;
252        }
253
254   EXPORT
255       None by default.  However, if you wish to call mcast_add(),
256       mcast_drop(), mcast_if(), mcast_loopback(), mcast_ttl, mcast_dest() and
257       mcast_send() as functions you may import them explicitly on the use
258       line or by importing the tag ":functions".
259
260   BUGS
261       The mcast_if(), mcast_ttl() and mcast_loopback() methods will cause a
262       crash on versions of Linux earlier than 2.2.0 because of a kernel bug
263       in the implementation of the multicast socket options.
264

AUTHOR

266       Lincoln Stein, lstein@cshl.org.
267
268       This module is distributed under the same terms as Perl itself.
269

SEE ALSO

271       perl(1), IO::Socket(3), IO::Socket::INET(3).
272
273
274
275perl v5.34.0                      2022-01-21          IO::Socket::Multicast(3)
Impressum