--- name: "IO::Interface" section: "3pm" platform: "linux" package: "libio-interface-perl" version: "1.09-2+b5" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/IO::Interface" --- # IO::Interface(3pm) Perl extension for access to network card configuration information ## NAME IO::Interface - Perl extension for access to network card configuration information ## SYNOPSIS ``` # ====================== # the new, preferred API # ====================== use IO::Interface::Simple; my $if1 = IO::Interface::Simple->new('eth0'); my $if2 = IO::Interface::Simple->new_from_address('127.0.0.1'); my $if3 = IO::Interface::Simple->new_from_index(1); my @interfaces = IO::Interface::Simple->interfaces; for my $if (@interfaces) { print "interface = $if\n"; print "addr = ",$if->address,"\n", "broadcast = ",$if->broadcast,"\n", "netmask = ",$if->netmask,"\n", "dstaddr = ",$if->dstaddr,"\n", "hwaddr = ",$if->hwaddr,"\n", "mtu = ",$if->mtu,"\n", "metric = ",$if->metric,"\n", "index = ",$if->index,"\n"; print "is running\n" if $if->is_running; print "is broadcast\n" if $if->is_broadcast; print "is p-to-p\n" if $if->is_pt2pt; print "is loopback\n" if $if->is_loopback; print "is promiscuous\n" if $if->is_promiscuous; print "is multicast\n" if $if->is_multicast; print "is notrailers\n" if $if->is_notrailers; print "is noarp\n" if $if->is_noarp; } # =========== # the old API # =========== use IO::Socket; use IO::Interface qw(:flags); my $s = IO::Socket::INET->new(Proto => 'udp'); my @interfaces = $s->if_list; for my $if (@interfaces) { print "interface = $if\n"; my $flags = $s->if_flags($if); print "addr = ",$s->if_addr($if),"\n", "broadcast = ",$s->if_broadcast($if),"\n", "netmask = ",$s->if_netmask($if),"\n", "dstaddr = ",$s->if_dstaddr($if),"\n", "hwaddr = ",$s->if_hwaddr($if),"\n"; print "is running\n" if $flags & IFF_RUNNING; print "is broadcast\n" if $flags & IFF_BROADCAST; print "is p-to-p\n" if $flags & IFF_POINTOPOINT; print "is loopback\n" if $flags & IFF_LOOPBACK; print "is promiscuous\n" if $flags & IFF_PROMISC; print "is multicast\n" if $flags & IFF_MULTICAST; print "is notrailers\n" if $flags & IFF_NOTRAILERS; print "is noarp\n" if $flags & IFF_NOARP; } my $interface = $s->addr_to_interface('127.0.0.1'); ``` ## DESCRIPTION IO::Interface adds methods to IO::Socket objects that allows them to be used to retrieve and change information about the network interfaces on your system. In addition to the object-oriented access methods, you can use a function-oriented style. THIS API IS DEPRECATED. Please see IO::Interface::Simple for the preferred way to get and set interface configuration information. ### Creating a Socket to Access Interface Information You must create a socket before you can access interface information. The socket does not have to be connected to a remote site, or even used for communication. The simplest procedure is to create a UDP protocol socket: ``` my $s = IO::Socket::INET->new(Proto => 'udp'); ``` The various IO::Interface functions will now be available as methods on this socket. ### Methods - @iflist = $s-\>if\_list The **if\_list()** method will return a list of active interface names, for example "eth0" or "tu0". If no interfaces are configured and running, returns an empty list. - $addr = $s-\>if\_addr($ifname \[,$newaddr\]) **if\_addr()** gets or sets the interface address. Call with the interface name to retrieve the address (in dotted decimal format). Call with a new address to set the interface. In the latter case, the routine will return a true value if the operation was successful. ``` my $oldaddr = $s->if_addr('eth0'); $s->if_addr('eth0','192.168.8.10') || die "couldn't set address: $!"; ``` Special case: the address of the pseudo-device "any" will return the IP address "0.0.0.0", which corresponds to the INADDR\_ANY constant. - $broadcast = $s-\>if\_broadcast($ifname \[,$newbroadcast\] Get or set the interface broadcast address. If the interface does not have a broadcast address, returns undef. - $mask = $s-\>if\_netmask($ifname \[,$newmask\]) Get or set the interface netmask. - $dstaddr = $s-\>if\_dstaddr($ifname \[,$newdest\]) Get or set the destination address for point-to-point interfaces. - $hwaddr = $s-\>if\_hwaddr($ifname \[,$newhwaddr\]) Get or set the hardware address for the interface. Currently only ethernet addresses in the form "00:60:2D:2D:51:70" are accepted. - $flags = $s-\>if\_flags($ifname \[,$newflags\]) Get or set the flags for the interface. The flags are a bitmask formed from a series of constants. See "Exportable constants" below. - $ifname = $s-\>addr\_to\_interface($ifaddr) Given an interface address in dotted form, returns the name of the interface associated with it. Special case: the INADDR\_ANY address, 0.0.0.0 will return a pseudo-interface name of "any". ### EXPORT IO::Interface exports nothing by default. However, you can import the following symbol groups into your namespace: ``` :functions Function-oriented interface (see below) :flags Flag constants (see below) :all All of the above ``` ### Function-Oriented Interface By importing the ":functions" set, you can access IO::Interface in a function-oriented manner. This imports all the methods described above into your namespace. Example: ``` use IO::Socket; use IO::Interface ':functions'; my $sock = IO::Socket::INET->new(Proto=>'udp'); my @interfaces = if_list($sock); print "address = ",if_addr($sock,$interfaces[0]); ``` ### Exportable constants The ":flags" constant imports the following constants for use with the flags returned by **if\_flags()**: ``` IFF_ALLMULTI IFF_AUTOMEDIA IFF_BROADCAST IFF_DEBUG IFF_LOOPBACK IFF_MASTER IFF_MULTICAST IFF_NOARP IFF_NOTRAILERS IFF_POINTOPOINT IFF_PORTSEL IFF_PROMISC IFF_RUNNING IFF_SLAVE IFF_UP ``` This example determines whether interface 'tu0' supports multicasting: ``` use IO::Socket; use IO::Interface ':flags'; my $sock = IO::Socket::INET->new(Proto=>'udp'); print "can multicast!\n" if $sock->if_flags & IFF_MULTICAST. ``` ## AUTHOR Lincoln D. Stein \ Copyright 2001-2014, Lincoln D. Stein. This library is distributed under the Perl Artistic License 2.0. Please see LICENSE for more information. ## SUPPORT For feature requests, bug reports and code contributions, please use the GitHub repository at https://github.com/lstein/LibIO-Interface-Perl ## SEE ALSO [**perl**(1)](/perl/1.md), **IO::Socket**(3), **IO::Multicast**(3), IO::Interface::Simple