#!/usr/bin/perl -wT
# IBM_PROLOG_BEGIN_TAG 
# This is an automatically generated prolog. 
#  
# bos720 src/perl/libext/Socket/Socket.pm 1.3 
#  
# Licensed Materials - Property of IBM 
#  
# COPYRIGHT International Business Machines Corp. 2008 
# All Rights Reserved 
#  
# US Government Users Restricted Rights - Use, duplication or 
# disclosure restricted by GSA ADP Schedule Contract with IBM Corp. 
#  
# IBM_PROLOG_END_TAG 
# @(#)55      1.3  src/perl/libext/Socket/Socket.pm, perl_libaix, bos720 3/31/08 15:52:25

package LibExt::Socket;

use strict;

require Exporter;
our @ISA = qw(Exporter);
our @EXPORT_OK = qw(AF_INET AF_INET6 gethostbyname2 gethostbyaddr2 inet_pton inet_ntop ipv6_network prefixlen_to_mask);
our %EXPORT_TAGS = ( all => \@EXPORT_OK );

require XSLoader;
XSLoader::load('LibExt::Socket');

=head1 NAME

LibExt::Socket - Generic Socket library supporting IPv4 and IPv6.

=head1 DESCRIPTION

This module provides basic querying and conversion capabilities for IPv4 and
IPv6 address families.  A lookup can be performed using a host name, or an IP
address in its ASCII or packed-string format.  The host name, addresses,
aliases and address type can be obtained through any of the lookup methods.
In addition, it also provides methods to convert IP addesses between their
ASCII string and packed-string formats.

=head1 SYNOPSIS

  use LibExt::Socket qw(:all);

  # Query the host name "myhostname"

    $host4 = "myhostname";
    $hostent4 = gethostbyname2($host4, AF_INET);

    if ($hostent4) {
      $addr4 = inet_ntop(AF_INET, $hostent4->{addr}[0]);
      print "$host4 has an IPv4 address $addr4\n";

      if ($alias4 = $hostent4->{aliases}[0]) {
        print "myhostname also has an alias $alias4\n";
      }
    }

  # Same as above, but the address family of
  # host name "myhostname2" is not known

    $host = "myhostname2";
    $hostent= gethostbyname2($host);

    if ($hostent) {
      $addr = inet_ntop($hostent->{addrtype}, $hostent->{addr}[0]);
      print "$host has an address $addr\n";
    }

  # Perform an address-to-name lookup for IPv6

    $addr6str = '1234::ABCD';
    $addr6A    = inet_pton(AF_INET6, $addr6str);
    $hostent6 = gethostbyaddr2($addr6A, AF_INET6);

    if($hostent6) {
      print "The hostname for $addr6str is $hostent6->{name}\n";
    }

  # Also performs an address-to-name lookup

    $hostent6 = gethostbyname2($addr6str, AF_INET6);

    if($hostent6) {
      print "The hostname for $addr6str is $hostent6->{name}\n";
    }

  # Convert a prefix length to a IPv6 netmask

    $mask = prefixlen_to_mask(112);

  # Are two addresses on the same network?

    $addr6B  = inet_pton(AF_INET6, '1234::A0FF');

    $netA = ipv6_network($addr6A, $mask);
    $netB = ipv6_network($addr6B, $mask);

    if ($netA eq $netB) {
      print "$hostA and $hostB are on the same network!\n";
    }


=cut

=head1 CONSTANTS

=over 4

=item AF_INET

The address family for an IPv4 address.  The value is imported from the C header <sys/socket.h>.

=item AF_INET6

The address family for an IPv6 address.  The value is imported from the C header <sys/socket.h>.

=back

=head1 METHODS

=over 4

=item gethostbyname2(name[, af])

Calls the C library gethostbyname2() in <netdb.h> to retrieve information about
a host.  If an address is passed, the C library gethostbyaddr_r() is called.

Arguments:

  name - A host name, IPv4 address, or IPv6 address.
  af   - An address family, AF_INET or AF_INET6

The address family (af) argument is optional.  If omitted, gethostbyname2 will
first perform a query with the AF_INET family.  If the query fails, then a
second query will be attempted using AF_INET6.

Return Value:

If the query fails, returns undef.
If successful, returns a hash reference with the following keys:

  name      - The host name
  addrttype - The address type, AF_INET or AF_INET6
  length    - The length of the address in bytes
  addrs     - An array of addresses in packed-string form
  aliases   - An array of host name aliases

=item gethostbyaddr2(addr, af)

Calls the C library gethostbyaddr_r() in <netdb.h> to retrieve
information about a host.

Arguments:

  addr - An IPv4 or IPv6 address, in packed-string format.
  af   - An address family, AF_INET or AF_INET6

The address family argument must be AF_INET or AF_INET6.

The caller must be careful to supply the correct address family.  A
segmentation fault can occur if the wrong address family is supplied.

Return Value:

If the query fails, returns undef.
If successful, returns a hash reference with the following keys:

  name      - The host name
  addrttype - The address type, AF_INET or AF_INET6
  length    - The length of the address in bytes
  addrs     - An array of addresses in packed-string form
  aliases   - An array of host name aliases

=item inet_pton(af, src)

Calls the C library inet_pton() to convert an IP address into its packed-string
form.

Arguments:

  af  - The address family, AF_INET or AF_INET6
  src - Either an IPv4 address, or an IPv6 address.

The src argument must be in ASCII format.

Return Value:

If successful, returns the IP address as a packed string.
Upon failure, returns undef.

=item inet_ntop(af, src)

Calls the C library inet_ntop() to convert an IP address from a packed string
form to an ASCII format.

Arguments:

  af  - The address family, AF_INET or AF_INET6
  src - Either an IPv4 address, or an IPv6 address.

The src argument must be in packed-string format.

Return Value:

If successful, returns the IP address in ASCII form.
Upon failure, returns undef.

=item ipv6_network(addr, mask)

Masks an IPv6 address to determine the network which it belongs.

Arguments:

  addr - The IPv6 addresses, in packed string format.
  mask - The IPv6 netmask, in packed string format.

Return Value:

The logical AND between the address and netmask.

=item prefixlen_to_mask(prefixlen)

Converts a prefix length to an IPv6 netmask.

Arguments:

prefixlen - An integer representing an IPv6 prefix length, between 0 and 128
(inclusive).

Return Value:

The IPv6 netmask in packed string format.

=back

=cut

1;