IO::So...lticast(3pm)

💖 IO::Socket::Multicast 💖

okay bestie, pull up a chair, because we're about to talk about the IO::So...lticast(3pm) page — yes that's the "User Contributed Perl Documentation" section of the manual, and yes it's giving absolute legend energy. this is part 1 of 2, so don't go anywhere, there's more coming 🫶

---

🌸 NAME 🌸

IO::Socket::Multicast — Send and receive multicast messages

like. literally that's the whole job. sending and receiving multicast. iconic.

---

✨ SYNOPSIS ✨

  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('225.0.1.1');

  # Add a multicast group to eth0 device
  $s->mcast_add('225.0.0.2','eth0');

  # now receive some multicast data
  $s->recv($data,1024);

  # Drop a multicast group
  $s->mcast_drop('225.0.0.1');

  # 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 225.0.0.1
  $s->mcast_send('hello world!','225.0.0.1:1200');
  $s->mcast_set('225.0.0.2:1200');
  $s->mcast_send('hello again!');

look at that. a whole little story. we love a self-contained example 💅

---

🦋 DESCRIPTION 🦋

so IO::Socket::Multicast is a subclass of IO::Socket::INET — it inherits all the base stuff and then levels you up so you can manipulate multicast groups. with this module (plus an operating system that actually supports multicasting, which bestie, check that) you can receive incoming multicast transmissions and generate your own outgoing multicast packets. main character on both sides of the conversation, no cap.

this module requires IO::Interface version 0.94 or higher. don't skip that part, it's not decorative.

---

🎀 INTRODUCTION 🎀

multicasting was designed for streaming multimedia applications and conferencing systems — the kind of setup where one transmitting machine needs to distribute data to a large number of clients. one to many. group chat, but for packets.

IP addresses in the range 224.0.0.0 and 239.255.255.255 are reserved for multicasting. these addresses don't correspond to individual machines — nope, they correspond to multicast groups. messages sent to these addresses get delivered to a potentially large number of machines that have registered their interest in receiving transmissions on those 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. literally channel surfing but make it network protocols 📺

to receive transmissions from a multicast group: use IO::Socket::Multicast->new() to create a UDP socket and bind it to a local network port. then subscribe one or more multicast groups using the mcast_add() method. after that, subsequent calls to the standard recv() method will receive incoming messages transmitted to the subscribed groups using the selected port number. set it and forget it, fr fr.

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. the mcast_set() and mcast_send() methods are there as convenience functions. mcast_set() will set a default multicast destination for messages which you then send with mcast_send(). cute little pair, they're a duo 💜

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 (where a copy of the transmitted messages is received by the local machine), call mcast_loopback().

---

🧚 CONSTRUCTORS 🧚

• $socket = IO::Socket::Multicast->new([LocalPort=>$port,...]) — the new() method is the constructor for the IO::Socket::Multicast class. it takes the same arguments as IO::Socket::INET, with one glow-up: the Proto argument, instead of defaulting to "tcp", defaults to "udp" — which is way more appropriate for multicasting.

to create a UDP socket suitable for sending outgoing multicast messages, call new() without 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. sharing is caring 🙈

---

💅 METHODS 💅

• $success = $socket->mcast_add($multicast_address [,$interface]) — the mcast_add() method adds the provided multicast address to the list of subscribed multicast groups. the address can be given either as a dotted-quad decimal, or as a packed IP address (like the kind produced by the inet_aton() function). on success, the method returns a true value. slay.

the optional $interface argument lets you specify which network interface to listen on for incoming multicast messages. if the IO::Interface module is installed, you can 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 multicast transmissions received on any of the host's network interfaces will be forwarded to the socket. catch-all energy.

heads up bestie, this one matters: 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. the way that it's interface-level, not socket-level?? yeah. 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::Multicast->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. multi-group multitasking, we love to see it 🌈

• $success = $socket->mcast_drop($multicast_address) — this reverses the action of mcast_add(), removing the indicated multicast address from the list of subscribed groups. unsubscribe arc.
• $loopback = $socket->mcast_loopback — the mcast_loopback() method controls whether the socket will receive its own multicast transmissions (default is yes). called without arguments, the method returns the current state of the loopback flag.
• $previous = $socket->mcast_loopback($new) — called with a boolean argument, the method will set the loopback flag, and return its previous value. glow up + receipt of what it used to be.
• $ttl = $socket->mcast_ttl — the mcast_ttl() method examines or sets the time to live (TTL) for outgoing multicast messages. the TTL controls the number of routers the packet can cross before being expired. the default TTL is 1, meaning 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.
• $previous = $socket->mcast_ttl($new) — called with a value, this method sets the TTL and returns its previous value.
• $interface = $socket->mcast_if — 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, it returns the current interface.
• $previous = $socket->mcast_if($new) — called with the name of an interface, it 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. incoming and outgoing are different lil settings, don't mix them up 🫶

• $dest = $socket->mcast_dest — the mcast_dest() method is a convenience function that lets you set the default destination group for outgoing multicasts. called without arguments, it returns the current destination as a packed binary sockaddr_in data structure.
• $previous = $socket->mcast_dest($new) — 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 structures, or in the form "XX.XX.XX.XX:YY" where the first part is the IP address, and the second is the port number.

• $bytes = $socket->mcast_send($data [,$dest]) — 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 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. it's keeping receipts, literally.

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::Multicast->new() with a PeerAddr, and IO::Socket::INET will perform a connect(), creating a default destination for calls to send(). options on options, we stay flexible ✨

🌈 EXAMPLE 🌈

ok so bestie, here's the whole vibe in action. this is a multicast server — every 10 seconds it blasts the current time and the list of logged-in users out to the local network using multicast group 226.1.1.2, port 2000 (those numbers are literally just picked at random, no thoughts head empty).

#!/usr/bin/perl
# server
use strict;
use IO::Socket::Multicast;

use constant DESTINATION => '226.1.1.2:2000';
my $sock = IO::Socket::Multicast->new(Proto=>'udp',PeerAddr=>DESTINATION);

while (1) {
  my $message = localtime;
  $message .= "\n" . `who`;
  $sock->send($message) || die "Couldn't send: $!";
} continue {
  sleep 10;
}

and here's its little partner in crime 🫶 the client. it just sits there listening for transmissions on group 226.1.1.2, port 2000, and echoes whatever it hears straight to standard output.

#!/usr/bin/perl
# client

use strict;
use IO::Socket::Multicast;

use constant GROUP => '226.1.1.2';
use constant PORT  => '2000';

my $sock = IO::Socket::Multicast->new(Proto=>'udp',LocalPort=>PORT);
$sock->mcast_add(GROUP) || die "Couldn't set group: $!\n";

while (1) {
  my $data;
  next unless $sock->recv($data,1024);
  print $data;
}

---

🌸 EXPORT 🌸

ok so by default? none by default. nothing. zero. nada. 🙈

but wait — if you want to call mcast_add(), mcast_drop(), mcast_if(), mcast_loopback(), mcast_ttl, mcast_dest() and mcast_send() as plain old functions, you 100% can, bestie — just import them explicitly on the use line, or import the tag ":functions". ez.

---

💀 BUGS 💀

ok this is the part where we hold hands. 🫶 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.

no cap: crash. on old Linux. kernel's fault, not ours, but still — be careful, babes. 😭

---

👑 AUTHOR 👑

Lincoln Stein, lstein@cshl.org.

This module is distributed under the same terms as Perl itself.

---

✨ SEE ALSO ✨

• perl(1)
• IO::Socket(3)
• IO::Socket::INET(3)

---

and that's the whole page, bestie!! 🎀 this was perl v5.42.3, dated 2026-08-20, and it's the User Contributed Perl Documentation version of IO::Socket::Multicast(3pm) — go forth and multicast responsibly 💅✨