Sys::HostIP(3pm)

💖 Sys::HostIP 💖

okay bestie, welcome to Sys::HostIP (that's the 3pm one, a Perl module manual page, in case you were wondering) — she's a little Perl module that tries extra hard to figure out your machine's IP situation. no cap. 💅

---

✨ NAME ✨

Sys::HostIP — try extra hard to get IP address related info 🦋

---

🌸 SYNOPSIS 🌸

use Sys::HostIP;

my $hostip     = Sys::HostIP->new;
my $ips        = $hostip->ips;
my $interfaces = $hostip->interfaces;

look at her go. three lines and you're already getting your whole network tea ☕✨

---

💜 DESCRIPTION 💜

so basically Sys::HostIP does what it can to determine the ip address of your machine. and when I say what it can, I mean she is genuinely trying her best. all 3 methods work fine on every single system that the author was able to test on — and the list is giving global icon behavior:

• Irix
• OpenBSD
• FreeBSD
• NetBSD
• Solaris
• Linux
• OSX
• Win32
• Cygwin

how does she do it? she parses ifconfig(8) output — and on Win32/Cygwin she's parsing ipconfig instead. yes bestie, she's out here reading your interface output like it's a group chat and she's catching up on everything. 📖👑

and she comes in two flavors: an object oriented interface, and a functional one for compatibility with older versions. so whether you're an OOP girlie or a retro function-call girlie, she's got you. 🫶

---

🎀 ATTRIBUTES 🎀

🧚 ifconfig

my $hostip = Sys::HostIP->new( ifconfig => '/path/to/your/ifconfig' );

if the code has no idea where your ifconfig lives, you can just tell her. set the location of ifconfig with this attribute and she'll stop guessing. queen of accepting help 💅

heads up: if you're using the object oriented interface, this value is cached. so she remembers what you told her. lowkey sweet of her.

🦋 if_info

the interface information. this is either created on new, or you can create it yourself at initialize. your call, bestie.

# get the cached if_info
my $if_info = $hostip->if_info;

# create custom one at initialize
my $hostip = Sys::HostIP->new( if_info => {...} );

---

🔥 METHODS 🔥

⭐ ip

my $ip = $hostip->ip;

returns a scalar containing a best guess of your host machine's IP address. (best guess!! she's doing her best, don't come for her 💀)

and okay, important detail: on *nix systems (Unix, BSD, GNU/Linux, OSX, etc.) she will return the loopback interface (127.0.0.1) if she can't find anything else. so like, if you see 127.0.0.1 and you're confused — that's her fallback, that's the safety net, that's her saying "girl I looked everywhere and this is all I got." 🙈

✨ ips

my $all_ips = $hostip->ips;
foreach my $ip ( @{$all_ips} ) {
    print "IP: $ip\n";
}

returns an array ref containing all the IP addresses of your machine. not just one. ALL of them. she's thorough like that 👑

🌈 interfaces

my $interfaces = $hostip->interfaces;

foreach my $interface ( keys %{$interfaces} ) {
    my $ip = $interfaces->{$interface};
    print "$interface => $ip\n";
}

returns a hash ref containing all pairs of interfaces and their corresponding IP addresses that Sys::HostIP could find on your machine. interface => ip. a whole matching set. iconic. 💖

🌸 EXPORT 🌸

Nothing by default! periodt. she's not gonna dump a bunch of subs into your namespace uninvited, that's not the vibe.

if you want to export something explicitly, use the syntax: Nothing.

use HostIP qw/ip ips interfaces/;
# that will get you those three subroutines, for example

all of these subroutines will match the object oriented interface methods. so same energy, different syntax. ✨

• ip

my $ip = ip();

• ips

my $ips = ips();

• interfaces

my $interfaces = interfaces();

---

💀 HISTORY 💀

originally written by Jonathan Schatz <bluelines@divisionbyzero.com>. 🫶

currently maintained by Paul Cochrane <paul@liekut.de> and Sawyer X <xsawyerx@cpan.org>. handing the aux cord down through the generations, love to see it 💜

---

🧚 TODO 🧚

keeping it real with you, bestie:

• the win32 code has not been tested with dialup or wireless connections. so like... no promises there.
• machines with output in some languages other than English fail. neverthless, the code has been shown to work in German, Swedish, French, Italian, and Finnish locales. so multilingual-ish, but not fully multilingual. we're getting there 🌈

---

👑 COPYRIGHT AND LICENSE 👑

Copyright (C) prior to 2010, Jonathan Schatz <bluelines@divisionbyzero.com>.

Copyright (C) 2010-2019, Sawyer X <xsawyerx@cpan.org>.

this program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. so yes, she's free, she's open, she's generous 💖

---

🎀 SEE ALSO 🎀

• ifconfig(8)
• ipconfig

---

that's the whole page, bestie!! this was perl v5.38.2, dated 2024-07-29, and it's the Sys::HostIP(3pm) manual — go forth and find your IP, you main character 🦋✨💅