=head1 NAME

Socket::More::Interface - Query network interfaces of your system


=head1 SYNOPOSIS

  use v5.36;
  use Socket::More::Interface;

  # Return a list of interface structures (hashes)
  my @interfaces=getifaddrs();


  # Lookup the interface index from its name
  my $index=if_nametoindex($name);
  
  # Lookup the interface name from its index
  my $name=if_nametoindex($index);

  # Get the key/value array of names and indexes
  @kvpairs=if_nameindex;


=head1 DESCRIPTION

Simple wrapper to library calls. Consult you man page for what they do.
C<getifaddrs>, C<if_nametoindex>, C<if_indextoname> and C<if_nameindex> are
exported by default.

=head1 API

=head2 getifaddrs

	my @interfaces=getifaddrs;

Queries the OS via  C<getifaddr> for the list of interfaces currently active.
Returns a list of hash references representing the network interfaces. The keys
of these hashes include:
	
=over

=item	name

The text name of the interface

=item flags

Flags set on the interface

=item	addr

Packed sockaddr structure suitable for use with C<bind>


=item	netmask

Packed sockaddr structure of the netmask

=item	dstmask

Packed sockaddr structure of the dstmask


=back

=head2 if_nametoindex

	my $index=if_nametoindex($name);

Returns the index of an interface by name. If the interface is not found,
returns 0 and sets C<$!> with error code.

=head2 if_indextoname

	my $name=if_indextoname($index);

Returns the name of an interface by index. If the index does not represent an
interface, C<undef> is returned and sets C<$!> with error code

=head2 if_nameindex

	my @pairs=if_nameindex;

Returns a list of key value pairs. The key is the interface index, and the
value is the name of the interface.

Return C<undef> on error and sets C<$!> with error code.


=head1 TODO

=over

=item Network interface queries for byte counts, rates.. etc

=item Expand address family types support(i.e link)

=item Network change events/notifications

=back

=head1 AUTHOR

Ruben Westerberg, E<lt>drclaw@mac.com<gt>

=head1 REPOSITORTY and BUGS

Please report any bugs via git hub: L<https://github.com/drclaw1394/perl-socket-more-interface>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2023 by Ruben Westerberg

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

=head1 DISCLAIMER OF WARRANTIES

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE.

=cut
