MAN page from Mandrake Other perl-Net-Bind-0.01-1.i386.rpm

Net::Bind::Resolv

Section: User Contributed Perl Documentation (3)
Updated: perl 5.004, patch 04
Index

NAME

Net::Bind::Resolv - a class to munge /etc/resolv.conf data.

SYNOPSIS

use Net::Bind::Resolv;

DESCRIPTION

This class provides an object oriented perl interface to/etc/resolv.conf data.

Here is an example snippet of code:

  use Net::Bind::Resolv;  my $res = new Net::Bind::Resolv('/etc/resolv.conf');  print $res->domain, "\n";

Or how about:

  use Net::Bind::Resolv;  use IO::File;  my $res = new Net::Bind::Resolv;  $res->comment("Programmatically generated\nDo not edit by hand");  $res->domain('arf.fz');  $res->nameservers('0.0.0.0');  $res->options('debug');  print $res->as_string;

METHODS

new([$filename])

Returns a reference to a new Net::Bind::Resolv object. If$filename is given then use that pass the value to a call toread_from_file.

read_from_string($string)

Populates the object with the parsed contents of $string. Returns1 is no errors were encounters, otherwise it returns 0.

The following directives are understood.

• domain DOMAIN
• search SEARCHLIST...: If a search directive and domain directive are found in the samefile, the last one encountered will be recorded and all previous oneswill be ignored.
• nameserver IP_ADDR: Each instance of a nameserver directive will cause the givenIP_ADDR to be remembered.
• sortlist SORTLIST...
• options OPTIONS...

There are very few requirements placed on the data in $string.Multiple entries of certain directives, while technically incorrect,will cause the last occurrence of the given directive to be the oneremembered. If there is sufficient precedence for this to beotherwise, let me know.

There is no requirement for the arguments to the directives to bevalid pieces of data. That job is delagated to local policy methodsto be applied against the object.

read_from_file($filename)

Populates the object with the parsed contents of $filename. Thisreally just a wrapper around read_from_string. Returns 0 iferrors were encountered, otherwise it returns 1.

clear

Zeros out the internal data in the object. This needs to be done ifmultiple read_from_string methods are called on a givenNet::Bind::Resolv object and you do not want to retain the previousvalues in the object.

domain([$domain])

Returns the value of the domain directive. If $domain isspecified, then set the domain to the given value and thesearchlist, if defined in the object, is undefined.

nameservers([@values])

Returns (in order) the list of nameserver entries. If called in anarray context it returns an array, otherwise it returns an arrayreference.

If @values is specified, then set the nameserver list to the givenvalues. Any items in @values that are list references aredereferences as they are added.

searchlist([@values])

Returns an array reference containing the items for the searchdirective. If called in an array context it returns an array,otherwise it returns an array reference.

If a list of values is specified, then set the searchlist to thosevalues and the domain, if defined in the object, is undefined. Anyitems in @values that are list references are dereferenced as theyare added.

sortlist([@values])

Returns an array reference containing the items for the sortlistdirective. If called in an array context it returns an array,otherwise it returns an array reference.

If a list of values is specified, then set the sortlist to thosevalues. Any items in @values that are list references aredereferenced as they are added.

options([@values])

Returns the items for the options directive. If called in an arraycontext it returns an array, otherwise it returns an array reference.

If a list of values is specified, then set the options to thosevalues. Any items in @values that are list references aredereferenced as they are added.

comments([@strings])

Returns the comments for the object. If called in an array context itreturns an array, otherwise it returns an array reference.

If a list of strings is specified, then set the comments to thosevalues after splitting the items on a NEWLINE boundary. Thisallows several combinations of arrays, array refs, or strings withembedded newlines to be specified. There is no need to prefix any ofthe comment lines with a comment character ([;\#]); theas_string automagically commentifies (:-) the comment strings.

Any items in @strings that are list references are dereferenced asthey are added.

as_string

Returns a string representing the contents of the object.Technically, this string could be used to populate a resolv.conffile, but use print for that. The <print> method is a wrapperaround this method. The data is generated in the following order:

  comments  domain        (mutually exclusive with search)  search        (mutually exclusive with domain)  nameservers   (one line for each nameserver entry)  sortlist  options

print($fh)

A wrapper around as_string that prints a valid resolver(5)representation of the data in the object to the given filehandle.

check([$policy])

Performs a policy/validity check of the data contained in the objectusing the given subroutine &policy. The given $policy routineis called as &$policy($self). If $policy is not given itdefaults to using default_policy_check. It returns the returnstatus of the policy check routine.

default_policy_check

A simple wrapper around various check_* methods.

check_domain

Returns 1 if the domain member of the object is defined and is avalid rfc1035 domain name, otherwise returns 0.

check_searchlist

Returns 1 if the searchlist member of the object is defined andcontains only valid rfc1035 domain names, otherwise returns 0.

check_nameservers

Returns 1 if the nameservers member of the object is defined andcontains only ip-addresses, otherwise returns 0.

Uses valid_ip to do the real work.

check_sortlist

Returns 1 if the sortlist member of the object is defined andcontains only ip-address/netmasks, otherwise returns 0.

Uses valid_netmask to do the real work.

check_options

Returns 1 if the options member of the object is empty or containsonly valid options, otherwise returns 0.

Currently recognized options are:

• debug
• ndots:N

qtynameservers

Returns the quantity of nameserver entries present.

CAVEATS

The read_from_{file|string} methods and the print method are notisomorphic. Given an arbitrary file or string which is read in, theoutput of print is not guaranteed to be an exact duplicate of theoriginal file. In the special case of files that are generated withthis module, the results will be isomorphic, assuming no modificationswere made to the data between when it was read in and subsequentlywritten back out.

Since Net::Bind::Resolv does not impose many requirements on the valuesof the various directives present in a /etc/resolv.conf file, it isimportant to apply the appropriate policy methods against the objectbefore writing it to a file that will be used by the resolver.Consider yourself warned!

AUTHOR

Kevin Johnson <kjjAATTpobox.com>

COPYRIGHT

This document was created byman2html,using the manual pages.