NAME
    Net::NBsocket -- Non-Blocking Sockets

SYNOPSIS
      use Net::NBsocket qw(
            open_UDP
            open_udpNB
            open_Listen
            open_listenNB
            connectBlk
            connect_NB
            accept_Blk
            accept_NB
            set_NB
            set_so_linger
            dyn_bind
            inet_aton
            inet_ntoa
            sockaddr_in
            sockaddr_un
            inet_pton
            inet_ntop
            ipv6_aton
            ipv6_n2x
            ipv6_n2d
            INADDR_ANY
            INADDR_BROADCAST
            INADDR_LOOPBACK
            INADDR_NONE
            AF_INET
            AF_INET6
            in6addr_any
            in6addr_loopback        
            havesock6
            isupport6
            pack_sockaddr_in6
            unpack_sockaddr_in6
      );

      $sock = open_UDP($af_family);
      $sock = open_udpNB($af_family);
      DEPRECATED $sock = bind2pp($sock,$port_path,$netaddr);
      $listener = open_Listen($port_path,$netaddr,$af_family);
      $listener = open_listenNB($port_path,$netaddr,$af_family);
      $client = connectBlk($port_path,$netaddr,$af_family);
      $client = connect_NB($port_path,$netaddr,$af_family);
      ($sock,$netaddr) = accept_Blk($srvsock);
      ($sock,$netaddr) = accept_NB($srvsock);
      $rv = set_NB($sock);
      $rv = set_so_linger($sock,$seconds);
      $port = dyn_bind($sock,$netaddr);

            IPv4
      $netaddr = inet_aton($dot_quad);
      $dot_quad = inet_ntoa($netaddr);
      $sin = sockaddr_in($port,$netaddr);
      ($port,$netaddr) = sockaddr_in($sin);
      $sun = sockaddr_un($path);
      ($path) = sockaddr_un($sun);

            IPv6
      $netaddr = inet_pton($AF_family,$text_addr);
      $text_addr = inet_ntop($AF_family,$netaddr);
      $ipv6naddr = ipv6_aton($ipv6_text);
      $hex_text = ipv6_n2x($ipv6naddr);
      $dec_text = ipv6_n2d($ipv6naddr);

            CONSTANTS
      $constant = INADDR_ANY();
      $constant = INADDR_BROADCAST();
      $constant = INADDR_LOOPBACK();
      $constant = INADDR_NONE();
      $constant = AF_INET();
      $constant = AF_INET6();
      $constant = in6addr_any();
      $constant = in6addr_loopback();

            IPv6 conditional
      $trueif = havesock6();
      $trueif = isupport6();
      $sockaddr_in6_struct=pack_sockaddr_in6($port,ipv6naddr);
      ($port,$ipv6naddr)=unpack_sockaddr_in6($sockaddr_in6_struct);

DESCRIPTION
    Net::NBsocket provides a wrapper for Socket and Socket6 to supply
    Non-Blocking sockets of various flavors;

  FUNCTIONS

    * $sock = open_UDP();
    Open an unbound UDP socket as below.

    * $sock = open_udpNB();
    Open and return an unbound non-blocking UDP socket object

      input:        [optional] address family (required for IPv6)
      returns:      pointer to socket object
                    or undef on failure

    * DEPRECATED $sock=bind2pp($sock,$port_path,$netaddr);
    Bind to $port_path and an optional IPv4 bind address as returned by
    inet_aton (defaults to INADDR_ANY).

      input:        port or unix domain socket path,
                    [optional] bind address
      returns:      socket on sucess, else undef;

    Author's note: This function was not well thought out and is now
    deprecated. It may be removed in future versions and is no longer in the
    EXPORT_OK array though it is still in the module and may be accessed
    with Net::NBsocket::bind2pp();

    Does not support IPv6

    * $listener = open_Listen($port_path,$netaddr,$af_family);
    Open a blocking TCP listner as below.

    * $listener = open_listenNB($port_path,$netaddr,$af_family);
    Open and return a non-blocking TCP listener bound to $port_path and an
    optional IPv4 or IPv6 bind address as returned by inet_pton (defaults to
    INADDR_ANY or in6addr_any for AF_INET6).

    Opens a unix-domain socket if port_path is a path instead of a number.

    The user must set the appropriate UMASK prior to calling this routine.

      input:        port or unix domain socket path,
                    [optional] bind address
                    [optional] address family, default AF_INET
      returns:      pointer to listening socket
                    object or undef on failure

    * $client = connectBlk($port_path,$netaddr,$af_family);
    Begin a blocking TCP connection as below.

    * $client = connect_NB($port_path,$netaddr,$af_family);
    Begin a non-blocking TCP connection to the host designated by $netaddr
    on $port_path, or to the unix domain socket designated by the path in
    $port_path. $netaddr is unused for unix domain sockets.

      input:        port number or unix domain socket path,
                    netaddr as returned by inet_aton,
                    [optional] address family (default AF_INET)
      returns:      socket object or
                    undef on failure

    * ($sock,$netaddr) = accept_Blk($srvsock);
    Accept a connection and return a BLOCKING socket as below.

    * ($sock,$netaddr) = accept_NB($srvsock);
    Accept a connection from a remote client, return a non-blocking socket
    and the network address of the remote host as returned by inet_aton or
    the unix domain socket path if PF_INET or PF_UNIX respectively.

      input:        listening socket object
      returns:      client socket object,
                    client packed netaddr or
                    unix domain socket path

            on failure returns and empty array or undef

    * $rv = set_NB($sock);
    Set a socket to Non-Blocking mode

      input:        SOCK object pointer
      returns:      true on success or
                    undef on failure

    $rv = set_so_linger($sock,$seconds);
      Set SO_LINGER on top level socket

      input:        sock object pointer, seconds
      returns:      true = success, false = fail

    * $port = dyn_bind($sock,$netaddr,$af_family);
    Attempt to bind a socket to the IP address and randomly assigned port
    number, in the range 49152 through 65535. Fails after 100 attempts

      input:        socket
                    netaddr as returned by inet_pton
      returns:      port number or undef

  IPv4 exported from Socket

    * $netaddr = inet_aton($dot_quad);
    Takes an argument of a hostname or dot quad ip address and returns a
    four octet packed network address.

    * $dot_quad = inet_ntoa($netaddr);
    Takes a 4 octet packed network address and returns a dot quad text
    string. Throws an error if fed a non-standard argument.

    * $sin = sockaddr_in($port,$netaddr);
    In SCALAR context, takes a port number and an IPv4 network address and
    returns a sockaddr_in structure.

    * ($port,$netaddr) = sockaddr_in($sin);
    In ARRAY context, takes a sockaddr_in structure and return the port and
    network address

    * $sun = sockaddr_un($path);
    In SCALAR context, takes its pathname and returns a sockaddr_un
    structure.

    * ($path) = sockaddr_un($sun);
    In ARRAY context, takes a sockaddr_un structure and returns its
    pathname.

  IPv6 exported from Socket6 & NetAddr::IP::InetBase

    * $netaddr = inet_pton($AF_family,$text_addr);
    This function takes a dot quad IPv4 address or an RFC 1884 text IPv6
    address and returns a 4 or 16 octet network address depending on the AF
    family argument.

    * $text_addr = inet_ntop($AF_family,$netaddr);
    This function takes a 4 or 16 octet network address depending on the AF
    family argument and returns a IPv4 dot quad or IPv6 text address
    respectively.

    * $ipv6naddr = ipv6_aton($ipv6_text);
    This function takes an RFC 1884 IPv6 text address and returns a 16 octet
    IPv6 network address.

    * $hex_text = ipv6_n2x($ipv6naddr);
    This function takes an IPv6 network address and returns an IPv6 hex text
    address. Throws an error if fed a non-standard argument.

    * $dec_text = ipv6_n2d($ipv6naddr);
    This function takes an IPv6 network address and returns and IPv6 text
    address with the last two octets in IPv4 dot quad representation.

  CONSTANTS

    * $constant = INADDR_ANY(); INADDR_ANY;
    This constant returns the wildcard address, equivalent to
    inet_aton('0.0.0.0');

    * $constant = INADDR_BROADCAST(); INADDR_BROADCAST;
    This constant returns the wildcard address, equivalent to
    inet_aton('255.255.255.255');

    * $constant = INADDR_LOOPBACK(); INADDR_LOOPBACK;
    This constant returns the LOCALHOST address, equivalent to
    inet_aton('127.0.0.1');

    * $constant = INADDR_NONE(); INADDR_NONE;
    This constant returns the "invalid" address, equivalent to
    inet_aton('255.255.255.255');

    * $constant = AF_INET(); AF_INET;
    This constant returns the AF_INET family number.

    * $constant = AF_INET6(); AF_INET6;
    This constant retunrs the AF_INET6 family number for this operating
    system.

    * $constant = in6addr_any(); in6addr_any;
    This constant returns the IPv6 16 octet wildcard address, equivalent to
    ipv6_aton('::0');

    * $constant = in6addr_loopback(); in6addr_loopback;
    This constant returns the IPv6 16 octet LOCALHOST address, equivalent to
    ipv6_aton('::1');

  IPv6 Conditional

    * $trueif = havesock6();
    This function returns TRUE if Socket6 is loaded on this host, else
    returns FALSE.

    * $trueif = isupport6();
    This function returns TRUE if Socket6 is loaded on this host and the
    underlying operating system suports IPv6 sockets, else returns FALSE.

    * $sockaddr_in6_struct=pack_sockaddr_in6($port,ipv6naddr);
    If Socket6 is loaded on this host, in SCALAR context, takes a port
    number and an IPv6 network address and returns a sockaddr_in6 structure.
    If Socket6 is not loaded, returns "undef".

    * ($port,$ipv6naddr)=unpack_sockaddr_in6($sockaddr_in6_struct);
    If Socket6 is loaded on this host, in ARRAY context, takes a
    sockaddr_in6 structure and returns the port number and IPv6 netaddr. If
    Socket6 is not loaded, returns and empty array.

DEPENDENCIES
            POSIX
            Socket
            NetAddr::IP

EXPORT_OK
            open_UDP
            open_udpNB
            open_Listen
            open_listenNB
            connectBlk
            connect_NB
            accept_Blk
            accept_NB
            set_NB
            set_so_linger
            dyn_bind
            inet_aton
            inet_ntoa
            sockaddr_in
            sockaddr_un
            inet_pton
            inet_ntop
            ipv6_aton
            ipv6_n2x
            ipv6_n2d
            INADDR_ANY
            INADDR_BROADCAST
            INADDR_LOOPBACK
            INADDR_NONE
            in6addr_any
            in6addr_loopback        
            AF_INET
            AF_INET6
            havesock6
            isupport6
            pack_sockaddr_in6
            unpack_sockaddr_in6

AUTHOR
    Michael Robinton, michael@bizsystems.com

COPYRIGHT 2004 - 2014
    Michael Robinton

    All rights reserved.

    This program is free software; you can redistribute it and/or modify it
    under the terms of either:

      a) the GNU General Public License as published by the Free
      Software Foundation; either version 2, or (at your option) any
      later version, or

      b) the "Artistic License" which comes with this distribution.

    This program is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU
    General Public License or the Artistic License for more details.

    You should have received a copy of the Artistic License with this
    distribution, in the file named "Artistic". If not, I'll be glad to
    provide one.

    You should also have received a copy of the GNU General Public License
    along with this program in the file named "Copying". If not, write to
    the

            Free Software Foundation, Inc.
            59 Temple Place, Suite 330
            Boston, MA  02111-1307, USA

    or visit their web page on the internet at:

            http://www.gnu.org/copyleft/gpl.html.

SEE ALSO
    the POSIX manpage, the Socket manpage