NAME
SYNOPSIS
DESCRIPTION
DEPENDENCIES
EXPORT
EXPORT_OK
COPYRIGHT
AUTHOR
SEE ALSO

NAME

Net::DNS::ToolKit::Utilities - a collection of helper utilities

SYNOPSIS

  use Net::DNS::ToolKit::Utilities qw(
        id
        question  
        revIP   
        query  
        dns_udpsend
        dns_udpresp
        dns_ans
        dns_ns
        dns_ptr
        rlook_send
        rlook_rcv
  );

  $unique = id($seed);
  $querybuf = question($name,$type);
  $rev = revIP($ip);
  $response = query(\$buffer,$timeout);
  $socket = dns_udpsend(\$buffer,$timeout);
  $response = dns_udpresp($socket,$timeout);
  ($aptr,$tptr,$auth_zone) = dns_ans(\$buffer);
  $nsptr = dns_ns(\$buffer);
  $hostname = dns_ptr(\$buffer);
  @hosts = dns_ptr(\$buffer);
  $socket = rlook_send($IP,$timeout);
  $hostname = rlook_rcv($socket,$timeout);

DESCRIPTION

Net::DNS::ToolKit::Utilities provides a collection of DNS utilities built from the ToolKit building blocks

$unique = id($seed);
Return a unique, non-zero, 16 bit ID for this session. Seeded with time, this number is autoincremented each time it is retrieved and will be unique each call from a single session. The number wraps around at 65535.
```
  input:        [optional] seed
  returns:      the last 16 bit number +1
```
Optionally, the user may supply a seed for the first call. Subsquent calls will return the previous number + 1 (mod 65536). The seed is set when the module is instantiated if no seed is supplied.
$querybuf = question($name,$type);
Create a C_IN DNS query of $type about $name.
```
  input:        host or domain name,
                query type
  returns:      query buffer
```
Supports types T_A, T_TXT, T_ANY, T_MX, T_NS, T_PTR
$rev = revIP($ip);
Reverse an IP address. i.e
```
  78.56.34.12 = revIP(12.34.56.78);

  input:        a dot quad IP address
  returns:      reversed dot quad address
```
NOTE: this is an operation on ASCII characters, not packed network addresses.
$response = query(\$buffer,$timeout);
Sends a DNS query contained in $buffer. Return a DNS response buffer or undef on error. If the error is catastophic (like a timeout), $@ will be set.
```
  input:        pointer to query buffer,
                optional timeout (secs, def 30)
  returns:      DNS answer or undef
```
$socket = dns_udpsend(\$buffer,$timeout);
Sends a DNS query contained in $buffer. Returns a UDP socket or undef; If the error is catastophic (like a timeout), $@ will be set.
```
  input:        pointer to query buffer,
                optional timeout (secs, def 30)
  returns:      socket or undef
```
$buffer = dns_udpresp($socket,$timeout);
Returns a DNS answer from $socket and closes socket. Returns undef on failure. If the error is catastophic (like a timeout), $@ will be set.
```
  input:        socket,
                optional timeout (secs, def 30)
  returns:      response buffer

  closes:       socket
```
($aptr,$tptr,$auth_zone)=dns_ans(\$buffer);
Parse a DNS answer and return pointer to an array of A response records and TXT records blessed into the callers namespace.
```
  input:        DNS answer
  returns:      pointers to two arrays,
                auth_zone name or ''
```
Returns an empty array unless there is at least ONE A record found.

The first array contains packed IPv4 addresses of the form returned by inet_aton (text). The second array contains text strings.

auth_zone will contain the zone name if an SOA record is found, otherwise it will contain ''.

$nsptr = dns_ns(\$buffer);

Parse a DNS NS request answer and return pointer to a hash of name servers and TTL's.

  $ptr->{hostname}--->{addr} = netaddr
                   |
                   *->{ttl}  = seconds

If no records are found, undef is returned

  input:        pointer to response buffer
  returns:      pointer to hash or undef

$host = dns_ptr(\$buffer);
Parse a DNS PTR request answer and return the hostname

If no records are found, undef or an empty array is returned
```
  input:        pointer to response buffer
  returns:      host name or array of hosts
```

$socket = rlook_send($IP,$timeout);

Send a query for reverse lookup of $IP and return the receive socket handle.

  input:        dotquad IP address,
                optional timeout (sec, def 30)
  return:       socket or undef

$hostname = rlook_rcv($socket,$timeout);

Receive DNS response, parse for hostname, close socket;

  input:        receive socket,
                optional timeout (sec, def 30)
  return:       hostname text or undef

DEPENDENCIES

        IO::Socket
        Net::DNS::Codes
        Net::DNS::ToolKit
        Net::DNS::ToolKit::RR

EXPORT

        none by default

EXPORT_OK

        id   
        question
        revIP
        query
        dns_udpsend
        dns_udpresp
        dns_ans
        dns_ns
        dns_ptr
        rlook_send
        rlook_rcv

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

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 the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

AUTHOR

Michael Robinton <michael@bizsystems.com>

CPAN RT