1IO::Socket::Multicast(3U)ser Contributed Perl DocumentatiIoOn::Socket::Multicast(3)
2
6 IO::Socket::Multicast - Send and receive multicast messages
7
9 use IO::Socket::Multicast;
10 # create a new UDP socket ready to read datagrams on port 1100
12 my $s = IO::Socket::Multicast->new(LocalPort=>1100);
13 # Add a multicast group
15 $s->mcast_add('225.0.1.1');
16 # Add a multicast group to eth0 device
18 $s->mcast_add('225.0.0.2','eth0');
19 # now receive some multicast data
21 $s->recv($data,1024);
22 # Drop a multicast group
24 $s->mcast_drop('225.0.0.1');
25 # Set outgoing interface to eth0
27 $s->mcast_if('eth0');
28 # Set time to live on outgoing multicast packets
30 $s->mcast_ttl(10);
31 # Turn off loopbacking
33 $s->mcast_loopback(0);
34 # 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
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 This module requires IO::Interface version 0.94 or higher.
48 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 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 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 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 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 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 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 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 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 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 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 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 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 $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 $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 $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 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 $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 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 NOTE: To set the interface used for incoming multicasts, use the
172 mcast_add() method.
173 $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 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 $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 The method returns the number of bytes successfully queued for
197 delivery.
198 As a side-effect, the method will call mcast_dest() to remember the
200 destination address.
201 Example:
203 $socket->mcast_send('Hi there group members!','225.0.1.1:1900') || die;
205 $socket->mcast_send("How's the weather?") || die;
206 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
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 #!/usr/bin/perl
218 # server
219 use strict;
220 use IO::Socket::Multicast;
221 use constant DESTINATION => '226.1.1.2:2000';
223 my $sock = IO::Socket::Multicast->new(Proto=>'udp',PeerAddr=>DESTINATION);
224 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 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 #!/usr/bin/perl
237 # client
238 use strict;
240 use IO::Socket::Multicast;
241 use constant GROUP => '226.1.1.2';
243 use constant PORT => '2000';
244 my $sock = IO::Socket::Multicast->new(Proto=>'udp',LocalPort=>PORT);
246 $sock->mcast_add(GROUP) || die "Couldn't set group: $!\n";
247 while (1) {
249 my $data;
250 next unless $sock->recv($data,1024);
251 print $data;
252 }
253 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 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
266 Lincoln Stein, lstein@cshl.org.
267 This module is distributed under the same terms as Perl itself.
269
271 perl(1), IO::Socket(3), IO::Socket::INET(3).
272perl v5.34.0 2021-07-22 IO::Socket::Multicast(3)