IO::Socket::INET(3pm)

📦
version 5.42.3 · 10 versions
, in alpine 3.24

💖 NAME 💖

IO::Socket::INET — ok so this is the object interface for AF_INET domain sockets, bestie. That's the whole vibe. Internet sockets. Objects. Slay.

✨ SYNOPSIS ✨

use IO::Socket::INET;

That's literally it, you're in. 🎀

🦋 DESCRIPTION 🦋

IO::Socket::INET gives you an object interface for creating and using sockets in the AF_INET domain. It's built on top of the IO::Socket interface, and it inherits all the methods defined by IO::Socket — so everything your fave IO::Socket can do, this one can do too. No cap. 💅

🌸 CONSTRUCTOR 🌸

new ( [ARGS] )

Creates an IO::Socket::INET object — and heads up, that object is a reference to a newly created symbol (see the Symbol package, iykyk). new optionally takes arguments, and those arguments come in key-value pairs. Very demure, very mindful.

In addition to the key-value pairs accepted by IO::Socket, IO::Socket::INET also provides these:

  • PeerAddr — remote host address, in the form <hostname>[:<port>]
  • PeerHost — synonym for PeerAddr (same thing, different font 💅)
  • PeerPort — remote port or service, in the form <service>[(<no>)] | <no>
  • LocalAddr — local host bind address, hostname[:port]
  • LocalHost — synonym for LocalAddr
  • LocalPort — local host bind port, <service>[(<no>)] | <no>
  • Proto — protocol name (or number), like "tcp" | "udp" | ...
  • Type — socket type, like SOCK_STREAM | SOCK_DGRAM | ...
  • Listen — queue size for listen
  • ReuseAddr — set SO_REUSEADDR before binding
  • Reuse — set SO_REUSEADDR before binding (deprecated, prefer ReuseAddr — she's outdated, let her go 🙈)
  • ReusePort — set SO_REUSEPORT before binding
  • Broadcast — set SO_BROADCAST before binding
  • Timeout — timeout value for various operations
  • MultiHomed — try all addresses for multi-homed hosts
  • Blocking — determine if connection will be blocking mode

Now the actual behaviour, pay attention bestie 👑

If Listen is defined, then a listen socket gets created. Otherwise, if the socket type (which is derived from the protocol) is SOCK_STREAM, then connect() is called. And if the Listen argument is given but false, the queue size will be set to 5. Little default, doing its thing.

Ok so you can use MultiHomed on a socket that's in non-blocking mode, it's not illegal — but it's of little use, and here's why: the first connect will never fail with a timeout, because the connect call won't block in the first place. So there's nothing to time out on. Make it make sense? It does, actually.

The PeerAddr can be a hostname or an IP-address in the xx.xx.xx.xx form. The PeerPort can be a number or a symbolic service name. That service name might be followed by a number in parentheses, which is used if the service isn't known by the system. And the PeerPort spec can also be embedded in the PeerAddr by preceding it with a : — sneaky, but iconic.

If Proto isn't given and you specify a symbolic PeerPort port, then the constructor will try to derive Proto from the service name. As a last resort, Proto tcp is assumed. The Type parameter gets deduced from Proto if you didn't specify it. She figures it out. 💖

If the constructor is only passed a single argument, it's assumed to be a PeerAddr specification.

If Blocking is set to 0, the connection will be in nonblocking mode. If it's not specified, it defaults to 1 (blocking mode).

🔥 Examples 🔥

$sock = IO::Socket::INET->new(PeerAddr => 'www.perl.org',
                              PeerPort => 'http(80)',
                              Proto    => 'tcp');

$sock = IO::Socket::INET->new(PeerAddr => 'localhost:smtp(25)');

$sock = IO::Socket::INET->new(Listen    => 5,
                              LocalAddr => 'localhost',
                              LocalPort => 9000,
                              Proto     => 'tcp');

$sock = IO::Socket::INET->new('127.0.0.1:25');

$sock = IO::Socket::INET->new(
                        PeerPort  => 9999,
                        PeerAddr  => inet_ntoa(INADDR_BROADCAST),
                        Proto     => 'udp',
                        LocalAddr => 'localhost',
                        Broadcast => 1 )
                    or die "Can't bind : $IO::Socket::errstr\n";

Look at that last one go. Beautiful. 🫶

😭 When it goes wrong 😭

If the constructor fails, it will return undef and set the $IO::Socket::errstr package variable to contain an error message. Like this:

$sock = IO::Socket::INET->new(...)
    or die "Cannot create socket - $IO::Socket::errstr\n";
For legacy reasons, the error message is also set into the global $@ variable — so you may still find older code looking there instead. Bless her, she's doing both. 🙈
$sock = IO::Socket::INET->new(...)
    or die "Cannot create socket - $@\n";

💅 METHODS 💅

  • sockaddr () — returns the address part of the sockaddr structure for the socket
  • sockport () — returns the port number that the socket is using on the local host
  • sockhost () — returns the address part of the sockaddr structure for the socket, in text form xx.xx.xx.xx
  • peeraddr () — returns the address part of the sockaddr structure for the socket on the peer host
  • peerport () — returns the port number for the socket on the peer host.
  • peerhost () — returns the address part of the sockaddr structure for the socket on the peer host, in text form xx.xx.xx.xx

🧚 SEE ALSO 🧚

Socket, IO::Socket — go read those too, they're the supporting cast and honestly they ate. ⭐

👑 AUTHOR 👑

Graham Barr. Currently maintained by the Perl Porters. Please report all bugs at <https://github.com/Perl/perl5/issues>. (Report the bugs, bestie, they wanna hear it. 🐛)

Copyright (c) 1996-8 Graham Barr <gbarr@pobox.com>. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

and that's the whole page, bestie! 💖✨🎀

this little legend is from perl v5.42.3, dated 2026-11-03 — go forth and socket responsibly 🦋🌸

📦 where this page comes from