IO::SOCKET::INET(3perl)

📦
version 5.44.0 · 14 versions
, in arch rolling

💖 IO::Socket::INET 💖

okay bestie, welcome to IO::Socket::INET — it's the Perl manual page for making AF_INET domain sockets with an object interface, and honestly? she's iconic. ✨

✨ SYNOPSIS ✨

use IO::Socket::INET;

that's it. that's the whole vibe check to get started. 🎀

🌸 DESCRIPTION 🌸

So like, IO::Socket::INET gives you an object interface for creating and using sockets in the AF_INET domain. She's built on top of the IO::Socket interface and inherits literally all the methods IO::Socket defines. no cap. 💅

👑 CONSTRUCTOR 👑

🦋 new ( [ARGS] ) 🦋

Creates an IO::Socket::INET object — which is a reference to a newly created symbol, see the Symbol package if you wanna go deeper. new optionally takes arguments, and those arguments come in key-value pairs. 🫶

On top of the key-value pairs that IO::Socket already accepts, IO::Socket::INET brings these to the group chat:

  • PeerAddr — Remote host address, in the form <hostname>[:<port>] 🌈
  • PeerHost — Synonym for PeerAddr
  • 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): "tcp" | "udp" | ...
  • Type — Socket type: SOCK_STREAM | SOCK_DGRAM | ...
  • Listen — Queue size for listen
  • ReuseAddr — Set SO_REUSEADDR before binding
  • Reuse — Set SO_REUSEADDR before binding (deprecated, prefer ReuseAddr) ⚠️
  • 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

okay so here's how the logic flows: 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() gets called. and if the Listen argument is given but it's false, the queue size gets set to 5. 🍓

Now, lowkey important: even though it's not illegal, using MultiHomed on a socket that's in non-blocking mode is of little use. Why? Because the first connect will never fail with a timeout, since the connect call won't block. so like, don't. 🙈

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 gets used if the service isn't known by the system. And plot twist — the PeerPort spec can also be embedded right inside the PeerAddr by preceding it with a :. 💀

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 it's not specified. 🧚

And if the constructor is only passed a single argument, it's assumed to be a PeerAddr specification. simple as that.

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";

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

$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, and you may still find older code which looks here instead. it's giving old money, honestly.

$sock = IO::Socket::INET->new(...)
    or die "Cannot create socket - $@\n";

💅 METHODS 💅

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

🌈 SEE ALSO 🌈

Socket, IO::Socket — go read those too, bestie, they're the blueprint. ⭐

💜 AUTHOR 💜

Graham Barr. Currently maintained by the Perl Porters. Please report all bugs at <https://github.com/Perl/perl5/issues>. (yes, actual URL, go be a good citizen and file that bug 🐛)

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.

periodt. that's the whole page, and you ate it. 👑

okay so that was IO::Socket::INET from the Perl Programmers Reference Guide — this version is from perl v5.44.0, dated 2026-10-17, and it's exactly the same facts as the IO::Socket::INET(3perl) manpage, just with way better energy. slay, go make some sockets, and don't forget ReuseAddr instead of the deprecated Reuse. mwah 🫶💖✨

📦 where this page comes from