home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _1684d70be70279fab1d15e0e2f6412a7 < prev    next >
Text File  |  2000-03-23  |  13KB  |  284 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>Net::Bind::Resolv - a class to munge /etc/resolv.conf data.</TITLE>
  5. <LINK REL="stylesheet" HREF="../../../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> Net::Bind::Resolv - a class to munge /etc/resolv.conf data.</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  23.     <LI><A HREF="#synopsis">SYNOPSIS</A></LI>
  24.     <LI><A HREF="#description">DESCRIPTION</A></LI>
  25.     <LI><A HREF="#methods">METHODS</A></LI>
  26.     <UL>
  27.  
  28.         <LI><A HREF="#new([$filename])"><CODE>new([$filename])</CODE></A></LI>
  29.         <LI><A HREF="#read_from_string($string)"><CODE>read_from_string($string)</CODE></A></LI>
  30.         <LI><A HREF="#read_from_file($filename)"><CODE>read_from_file($filename)</CODE></A></LI>
  31.         <LI><A HREF="#clear">clear</A></LI>
  32.         <LI><A HREF="#domain([$domain])"><CODE>domain([$domain])</CODE></A></LI>
  33.         <LI><A HREF="#nameservers([@values])"><CODE>nameservers([@values])</CODE></A></LI>
  34.         <LI><A HREF="#searchlist([@values])"><CODE>searchlist([@values])</CODE></A></LI>
  35.         <LI><A HREF="#sortlist([@values])"><CODE>sortlist([@values])</CODE></A></LI>
  36.         <LI><A HREF="#options([@values])"><CODE>options([@values])</CODE></A></LI>
  37.         <LI><A HREF="#comments([@strings])"><CODE>comments([@strings])</CODE></A></LI>
  38.         <LI><A HREF="#as_string">as_string</A></LI>
  39.         <LI><A HREF="#print($fh)"><A HREF="../../../../lib/Pod/perlfunc.html#item_print"><CODE>print($fh)</CODE></A></A></LI>
  40.         <LI><A HREF="#check([$policy])"><CODE>check([$policy])</CODE></A></LI>
  41.         <LI><A HREF="#default_policy_check">default_policy_check</A></LI>
  42.         <LI><A HREF="#check_domain">check_domain</A></LI>
  43.         <LI><A HREF="#check_searchlist">check_searchlist</A></LI>
  44.         <LI><A HREF="#check_nameservers">check_nameservers</A></LI>
  45.         <LI><A HREF="#check_sortlist">check_sortlist</A></LI>
  46.         <LI><A HREF="#check_options">check_options</A></LI>
  47.         <LI><A HREF="#qtynameservers">qtynameservers</A></LI>
  48.     </UL>
  49.  
  50.     <LI><A HREF="#caveats">CAVEATS</A></LI>
  51.     <LI><A HREF="#author">AUTHOR</A></LI>
  52.     <LI><A HREF="#copyright">COPYRIGHT</A></LI>
  53. </UL>
  54. <!-- INDEX END -->
  55.  
  56. <HR>
  57. <P>
  58. <H1><A NAME="name">NAME</A></H1>
  59. <P>Net::Bind::Resolv - a class to munge /etc/resolv.conf data.</P>
  60. <P>
  61. <HR>
  62. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  63. <UL>
  64. <LI>Linux</LI>
  65. <LI>Solaris</LI>
  66. <LI>Windows</LI>
  67. </UL>
  68. <HR>
  69. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  70. <P><CODE>use Net::Bind::Resolv;</CODE></P>
  71. <P>
  72. <HR>
  73. <H1><A NAME="description">DESCRIPTION</A></H1>
  74. <P>This class provides an object oriented perl interface to
  75. <CODE>/etc/resolv.conf</CODE> data.</P>
  76. <P>Here is an example snippet of code:</P>
  77. <PRE>
  78.   use Net::Bind::Resolv;
  79.   my $res = new Net::Bind::Resolv('/etc/resolv.conf');
  80.   print $res->domain, "\n";</PRE>
  81. <P>Or how about:</P>
  82. <PRE>
  83.   use Net::Bind::Resolv;
  84.   use IO::File;
  85.   my $res = new Net::Bind::Resolv;
  86.   $res->comment("Programmatically generated\nDo not edit by hand");
  87.   $res->domain('arf.fz');
  88.   $res->nameservers('0.0.0.0');
  89.   $res->options('debug');
  90.   print $res->as_string;</PRE>
  91. <P>
  92. <HR>
  93. <H1><A NAME="methods">METHODS</A></H1>
  94. <P>
  95. <H2><A NAME="new([$filename])"><CODE>new([$filename])</CODE></A></H2>
  96. <P>Returns a reference to a new <CODE>Net::Bind::Resolv</CODE> object.  If
  97. <CODE>$filename</CODE> is given then use that pass the value to a call to
  98. <CODE>read_from_file</CODE>.</P>
  99. <P>
  100. <H2><A NAME="read_from_string($string)"><CODE>read_from_string($string)</CODE></A></H2>
  101. <P>Populates the object with the parsed contents of <CODE>$string</CODE>.  Returns
  102. <CODE>1</CODE> is no errors were encounters, otherwise it returns <CODE>0</CODE>.</P>
  103. <P>The following directives are understood.</P>
  104. <UL>
  105. <LI><STRONG><A NAME="item_domain">domain DOMAIN</A></STRONG><BR>
  106.  
  107. <LI><STRONG><A NAME="item_search_SEARCHLIST%2E%2E%2E">search SEARCHLIST...</A></STRONG><BR>
  108.  
  109. If a <CODE>search</CODE> directive and domain directive are found in the same
  110. file, the last one encountered will be recorded and all previous ones
  111. will be ignored.
  112. <P></P>
  113. <LI><STRONG><A NAME="item_nameserver_IP_ADDR">nameserver IP_ADDR</A></STRONG><BR>
  114.  
  115. Each instance of a <CODE>nameserver</CODE> directive will cause the given
  116. <CODE>IP_ADDR</CODE> to be remembered.
  117. <P></P>
  118. <LI><STRONG><A NAME="item_sortlist_SORTLIST%2E%2E%2E">sortlist SORTLIST...</A></STRONG><BR>
  119.  
  120. <LI><STRONG><A NAME="item_options_OPTIONS%2E%2E%2E">options OPTIONS...</A></STRONG><BR>
  121.  
  122. </UL>
  123. <P>There are very few requirements placed on the data in <CODE>$string</CODE>.
  124. Multiple entries of certain directives, while technically incorrect,
  125. will cause the last occurrence of the given directive to be the one
  126. remembered.  If there is sufficient precedence for this to be
  127. otherwise, let me know.</P>
  128. <P>There is no requirement for the arguments to the directives to be
  129. valid pieces of data.  That job is delagated to local policy methods
  130. to be applied against the object.</P>
  131. <P>
  132. <H2><A NAME="read_from_file($filename)"><CODE>read_from_file($filename)</CODE></A></H2>
  133. <P>Populates the object with the parsed contents of <CODE>$filename</CODE>.  This
  134. really just a wrapper around <CODE>read_from_string</CODE>.  Returns <CODE>0</CODE> if
  135. errors were encountered, otherwise it returns <CODE>1</CODE>.</P>
  136. <P>
  137. <H2><A NAME="clear">clear</A></H2>
  138. <P>Zeros out the internal data in the object.  This needs to be done if
  139. multiple <CODE>read_from_string</CODE> methods are called on a given
  140. <CODE>Net::Bind::Resolv</CODE> object and you do not want to retain the previous
  141. values in the object.</P>
  142. <P>
  143. <H2><A NAME="domain([$domain])"><A HREF="#item_domain"><CODE>domain([$domain])</CODE></A></A></H2>
  144. <P>Returns the value of the <A HREF="#item_domain"><CODE>domain</CODE></A> directive.  If <CODE>$domain</CODE> is
  145. specified, then set the domain to the given value and the
  146. <CODE>searchlist</CODE>, if defined in the object, is undefined.</P>
  147. <P>
  148. <H2><A NAME="nameservers([@values])"><CODE>nameservers([@values])</CODE></A></H2>
  149. <P>Returns (in order) the list of <CODE>nameserver</CODE> entries.  If called in an
  150. array context it returns an array, otherwise it returns an array
  151. reference.</P>
  152. <P>If <CODE>@values</CODE> is specified, then set the nameserver list to the given
  153. values.  Any items in <CODE>@values</CODE> that are list references are
  154. dereferences as they are added.</P>
  155. <P>
  156. <H2><A NAME="searchlist([@values])"><CODE>searchlist([@values])</CODE></A></H2>
  157. <P>Returns an array reference containing the items for the <CODE>search</CODE>
  158. directive.  If called in an array context it returns an array,
  159. otherwise it returns an array reference.</P>
  160. <P>If a list of values is specified, then set the searchlist to those
  161. values and the <A HREF="#item_domain"><CODE>domain</CODE></A>, if defined in the object, is undefined.  Any
  162. items in <CODE>@values</CODE> that are list references are dereferenced as they
  163. are added.</P>
  164. <P>
  165. <H2><A NAME="sortlist([@values])"><CODE>sortlist([@values])</CODE></A></H2>
  166. <P>Returns an array reference containing the items for the <CODE>sortlist</CODE>
  167. directive.  If called in an array context it returns an array,
  168. otherwise it returns an array reference.</P>
  169. <P>If a list of values is specified, then set the sortlist to those
  170. values.  Any items in <CODE>@values</CODE> that are list references are
  171. dereferenced as they are added.</P>
  172. <P>
  173. <H2><A NAME="options([@values])"><CODE>options([@values])</CODE></A></H2>
  174. <P>Returns the items for the <CODE>options</CODE> directive.  If called in an array
  175. context it returns an array, otherwise it returns an array reference.</P>
  176. <P>If a list of values is specified, then set the options to those
  177. values.  Any items in <CODE>@values</CODE> that are list references are
  178. dereferenced as they are added.</P>
  179. <P>
  180. <H2><A NAME="comments([@strings])"><CODE>comments([@strings])</CODE></A></H2>
  181. <P>Returns the comments for the object.  If called in an array context it
  182. returns an array, otherwise it returns an array reference.</P>
  183. <P>If a list of strings is specified, then set the comments to those
  184. values after splitting the items on a <CODE>NEWLINE</CODE> boundary.  This
  185. allows several combinations of arrays, array refs, or strings with
  186. embedded newlines to be specified.  There is no need to prefix any of
  187. the comment lines with a comment character (<CODE>[;\#]</CODE>); the
  188. <CODE>as_string</CODE> automagically commentifies (:-) the comment strings.</P>
  189. <P>Any items in <CODE>@strings</CODE> that are list references are dereferenced as
  190. they are added.</P>
  191. <P>
  192. <H2><A NAME="as_string">as_string</A></H2>
  193. <P>Returns a string representing the contents of the object.
  194. Technically, this string could be used to populate a <CODE>resolv.conf</CODE>
  195. file, but use <A HREF="../../../../lib/Pod/perlfunc.html#item_print"><CODE>print</CODE></A> for that.  The <print> method is a wrapper
  196. around this method.  The data is generated in the following order:</P>
  197. <PRE>
  198.   comments
  199.   domain        (mutually exclusive with search)
  200.   search        (mutually exclusive with domain)
  201.   nameservers   (one line for each nameserver entry)
  202.   sortlist
  203.   options</PRE>
  204. <P>
  205. <H2><A NAME="print($fh)"><A HREF="../../../../lib/Pod/perlfunc.html#item_print"><CODE>print($fh)</CODE></A></A></H2>
  206. <P>A wrapper around <CODE>as_string</CODE> that prints a valid <CODE>resolver(5)</CODE>
  207. representation of the data in the object to the given filehandle.</P>
  208. <P>
  209. <H2><A NAME="check([$policy])"><CODE>check([$policy])</CODE></A></H2>
  210. <P>Performs a policy/validity check of the data contained in the object
  211. using the given subroutine <CODE>&policy</CODE>.  The given <CODE>$policy</CODE> routine
  212. is called as <CODE>&$policy($self)</CODE>.  If <CODE>$policy</CODE> is not given it
  213. defaults to using <CODE>default_policy_check</CODE>.  It returns the return
  214. status of the policy check routine.</P>
  215. <P>
  216. <H2><A NAME="default_policy_check">default_policy_check</A></H2>
  217. <P>A simple wrapper around various <CODE>check_*</CODE> methods.</P>
  218. <P>
  219. <H2><A NAME="check_domain">check_domain</A></H2>
  220. <P>Returns <CODE>1</CODE> if the domain member of the object is defined and is a
  221. valid rfc1035 domain name, otherwise returns <CODE>0</CODE>.</P>
  222. <P>
  223. <H2><A NAME="check_searchlist">check_searchlist</A></H2>
  224. <P>Returns <CODE>1</CODE> if the searchlist member of the object is defined and
  225. contains only valid rfc1035 domain names, otherwise returns <CODE>0</CODE>.</P>
  226. <P>
  227. <H2><A NAME="check_nameservers">check_nameservers</A></H2>
  228. <P>Returns <CODE>1</CODE> if the nameservers member of the object is defined and
  229. contains only ip-addresses, otherwise returns <CODE>0</CODE>.</P>
  230. <P>Uses <CODE>valid_ip</CODE> to do the real work.</P>
  231. <P>
  232. <H2><A NAME="check_sortlist">check_sortlist</A></H2>
  233. <P>Returns <CODE>1</CODE> if the sortlist member of the object is defined and
  234. contains only ip-address/netmasks, otherwise returns <CODE>0</CODE>.</P>
  235. <P>Uses <CODE>valid_netmask</CODE> to do the real work.</P>
  236. <P>
  237. <H2><A NAME="check_options">check_options</A></H2>
  238. <P>Returns <CODE>1</CODE> if the options member of the object is empty or contains
  239. only valid options, otherwise returns <CODE>0</CODE>.</P>
  240. <P>Currently recognized options are:</P>
  241. <UL>
  242. <LI><STRONG><A NAME="item_debug">debug</A></STRONG><BR>
  243.  
  244. <LI><STRONG><A NAME="item_ndots%3AN">ndots:N</A></STRONG><BR>
  245.  
  246. </UL>
  247. <P>
  248. <H2><A NAME="qtynameservers">qtynameservers</A></H2>
  249. <P>Returns the quantity of nameserver entries present.</P>
  250. <P>
  251. <HR>
  252. <H1><A NAME="caveats">CAVEATS</A></H1>
  253. <P>The <CODE>read_from_{file|string}</CODE> methods and the <A HREF="../../../../lib/Pod/perlfunc.html#item_print"><CODE>print</CODE></A> method are not
  254. isomorphic.  Given an arbitrary file or string which is read in, the
  255. output of <A HREF="../../../../lib/Pod/perlfunc.html#item_print"><CODE>print</CODE></A> is not guaranteed to be an exact duplicate of the
  256. original file.  In the special case of files that are generated with
  257. this module, the results will be isomorphic, assuming no modifications
  258. were made to the data between when it was read in and subsequently
  259. written back out.</P>
  260. <P>Since Net::Bind::Resolv does not impose many requirements on the values
  261. of the various directives present in a <CODE>/etc/resolv.conf</CODE> file, it is
  262. important to apply the appropriate policy methods against the object
  263. before writing it to a file that will be used by the resolver.
  264. Consider yourself warned!</P>
  265. <P>
  266. <HR>
  267. <H1><A NAME="author">AUTHOR</A></H1>
  268. <P>Kevin Johnson <<EM><A HREF="mailto:kjj@pobox.com">kjj@pobox.com</A></EM>></P>
  269. <P>
  270. <HR>
  271. <H1><A NAME="copyright">COPYRIGHT</A></H1>
  272. <P>Copyright (c) 1997 Kevin Johnson <<A HREF="mailto:kjj@pobox.com">kjj@pobox.com</A>>.</P>
  273. <P>All rights reserved. This program is free software; you can
  274. redistribute it and/or modify it under the same terms as Perl itself.</P>
  275. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  276. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  277. <STRONG><P CLASS=block> Net::Bind::Resolv - a class to munge /etc/resolv.conf data.</P></STRONG>
  278. </TD></TR>
  279. </TABLE>
  280.  
  281. </BODY>
  282.  
  283. </HTML>
  284.