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);
  $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 is returned

  input:	pointer to response buffer
  returns:	host name

• $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

Copyright 2003, 2004 Michael Robinton <michael@bizsystems.com>

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>

SEE ALSO

Net::DNS::Codes, Net::DNS::ToolKit, Net::DNS::ToolKit::RR,