.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Net::XWhois 3pm" .TH Net::XWhois 3pm "2022-10-13" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Net::XWhois \- Whois Client Interface for Perl5. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Net::XWhois; \& \& $whois = new Net::XWhois Domain => "vipul.net" ; \& $whois = new Net::XWhois Domain => "bit.ch", \& Server => "domreg.nic.ch", \& Retain => 1, \& Parser => { \& nameservers => \*(Aqnserver:\es+(\eS+)\*(Aq, \& }; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The Net::XWhois class provides a generic client framework for doing Whois queries and parsing server response. .PP The class maintains an array of top level domains and whois servers associated with them. This allows the class to transparently serve requests for different tlds, selecting servers appropriate for the tld. The server details are, therefore, hidden from the user and \*(L"vipul.net\*(R" (from InterNIC), gov.ru (from \s-1RIPE\s0) and \*(L"bit.ch\*(R" (from domreg.nic.ch) are queried in the same manner. This behaviour can be overridden by specifying different bindings at object construction or by registering associations with the class. See \*(L"\fBregister_associations()\fR\*(R" and \*(L"\fBnew()\fR\*(R". .PP One of the more important goals of this module is to enable the design of consistent and predictable interfaces to incompatible whois response formats. The Whois \s-1RFC\s0 (954) does not define a template for presenting server data; consequently there is a large variation in layout styles as well as content served across servers. .PP (There is, however, a new standard called \s-1RPSL\s0 (\s-1RFC2622\s0) used by \s-1RIPE\s0 (http://www.ripe.net), the European main whois server.) .PP To overcome this, Net::XWhois maintains another set of tables \- parsing rulesets \- for a few, popular response formats. (See \*(L"%PARSERS\*(R"). These parsing tables contain section names (labels) together with regular expressions that \fImatch\fR the corresponding section text. The section text is accessed \*(L"via\*(R" labels which are available as data instance methods at runtime. By following a consistent nomenclature for labels, semantically related information encoded in different formats can be accessed with the same methods. .SH "CONSTRUCTOR" .IX Header "CONSTRUCTOR" .IP "new ()" 4 .IX Item "new ()" Creates a Net::XWhois object. Takes an optional argument, a hash, that specifies the domain name to be queried. Calls \fBlookup()\fR if a name is provided. The argument hash can also specify a whois server, a parsing rule-set or a parsing rule-set format. (See \*(L"\fBpersonality()\fR\*(R"). Omitting the argument will create an \*(L"empty\*(R" object that can be used for accessing class data. .IP "personality ()" 4 .IX Item "personality ()" Alters an object's personality. Takes a hash with following arguments. (Note: These arguments can also be passed to the constructor). .RS 4 .IP "\fBDomain\fR" 8 .IX Item "Domain" Domain name to be queried. .IP "\fBServer\fR" 8 .IX Item "Server" Server to query. .IP "\fBParser\fR" 8 .IX Item "Parser" Parsing Rule-set. See \*(L"%PARSERS\*(R". .Sp .Vb 5 \& Parser => { \& name => \*(Aqdomain:\es+(\eS+)\en\*(Aq, \& nameservers => \*(Aqnserver:\es+(\eS+)\*(Aq, \& contact_emails => \*(Aqe\-mail:\es+(\eS+\e@\eS+)\*(Aq, \& }; .Ve .IP "\fBFormat\fR" 8 .IX Item "Format" A pre-defined parser format like \s-1INTERNIC, INTERNIC_FORMAT, RIPE, RIPE_CH, JAPAN\s0 etc. .Sp .Vb 1 \& Format => \*(AqINTERNIC_CONTACT\*(Aq, .Ve .IP "\fBNocache\fR" 8 .IX Item "Nocache" Force XWhois to ignore the cached records. .IP "\fBError\fR" 8 .IX Item "Error" Determines how a network connection error is handled. By default Net::XWhois will \fBcroak()\fR if it can't connect to the whois server. The Error attribute specifies a function call name that will be invoked when a network connection error occurs. Possible values are croak, carp, confess (imported from Carp.pm) and ignore (a blank function provided by Net::XWhois). You can, of course, write your own function to do error handling, in which case you'd have to provide a fully qualified function name. Example: main::logerr. .IP "\fBTimeout\fR" 8 .IX Item "Timeout" Timeout value for establishing a network connection with the server. The default value is 60 seconds. .RE .RS 4 .RE .SH "CLASS DATA & ACCESS METHODS" .IX Header "CLASS DATA & ACCESS METHODS" .ie n .IP "%PARSERS" 4 .el .IP "\f(CW%PARSERS\fR" 4 .IX Item "%PARSERS" An associative array that contains parsing rule-sets for various response formats. Keys of this array are format names and values are hash refs that contain section labels and corresponding parser code. The parser code can either be a regex or a reference to a subroutine. In the case of a subroutine, the whois 'response' information is available to the sub in \&\f(CW$_\fR[0]. Parsers can be added and extended with the \fBregister_parser()\fR method. Also see \*(L"Data Instance Methods\*(R". .Sp .Vb 9 \& my %PARSERS = ( \& INTERNIC => { \& contact_tech => \*(AqTechnical Contact.*?\en(.*?)(?=\e... \& contact_zone => \*(AqZone Contact.*?\en(.*?)(?=\es*\en[... \& contact_billing => \*(AqBilling Contact.*?\en(.*?)(?=\es*... \& contact_emails => \e&example_email_parser \& }, \& { etc. ... }, \& ); \& \& sub example_email_parser { \& \& # Note that the default internal implemenation for \& # the INTERNIC parser is not a user\-supplied code \& # block. This is just an instructive example. \& \& my @matches = $_[0] =~ /(\eS+\e@\eS+)/sg; \& return @matches; \& } .Ve .Sp See XWhois.pm for the complete definition of \f(CW%PARSERS\fR. .ie n .IP "%WHOIS_PARSER" 4 .el .IP "\f(CW%WHOIS_PARSER\fR" 4 .IX Item "%WHOIS_PARSER" \&\f(CW%WHOIS_PARSER\fR is a table that associates each whois server with their output format. .Sp .Vb 10 \& my %WHOIS_PARSER = ( \& \*(Aqwhois.ripe.net\*(Aq => \*(AqRPSL\*(Aq, \& \*(Aqwhois.nic.mil\*(Aq => \*(AqINTERNIC\*(Aq, \& \*(Aqwhois.nic.ad.jp\*(Aq => \*(AqJAPAN\*(Aq, \& \*(Aqwhois.domainz.net.nz\*(Aq => \*(AqGENERIC\*(Aq, \& \*(Aqwhois.nic.gov\*(Aq => \*(AqINTERNIC\*(Aq, \& \*(Aqwhois.nic.ch\*(Aq => \*(AqRIPE_CH\*(Aq, \& \*(Aqwhois.twnic.net\*(Aq => \*(AqTAIWAN\*(Aq, \& \*(Aqwhois.internic.net\*(Aq => \*(AqINTERNIC\*(Aq, \& \*(Aqwhois.nic.net.sg\*(Aq => \*(AqRIPE\*(Aq, \& \*(Aqwhois.aunic.net\*(Aq => \*(AqRIPE\*(Aq, \& \*(Aqwhois.cdnnet.ca\*(Aq => \*(AqCANADA\*(Aq, \& \*(Aqwhois.nic.uk\*(Aq => \*(AqINTERNIC\*(Aq, \& \*(Aqwhois.krnic.net\*(Aq => \*(AqKOREA\*(Aq, \& \*(Aqwhois.isi.edu\*(Aq => \*(AqINTERNIC\*(Aq, \& \*(Aqwhois.norid.no\*(Aq => \*(AqRPSL\*(Aq, \& ( etc.....) .Ve .Sp Please note that there is a plethora of output formats, allthough there are RFCs on this issue, like for instance \s-1RFC2622,\s0 there are numerous different formats being used! .ie n .IP "%DOMAIN_ASSOC" 4 .el .IP "\f(CW%DOMAIN_ASSOC\fR" 4 .IX Item "%DOMAIN_ASSOC" \&\f(CW%DOMAIN_ASSOC\fR is a table that associates top level domain names with their respective whois servers. You'd need to modity this table if you wish to extend the module's functionality to handle a new set of domain names. Or alter existing information. \fI\f(BIregister_association()\fI\fR provides an interface to this array. See XWhois.pm for the complete definition. .Sp .Vb 8 \& my %DOMAIN_ASSOC = ( \& \*(Aqal\*(Aq => \*(Aqwhois.ripe.net\*(Aq, \& \*(Aqam\*(Aq => \*(Aqwhois.ripe.net\*(Aq, \& \*(Aqat\*(Aq => \*(Aqwhois.ripe.net\*(Aq, \& \*(Aqau\*(Aq => \*(Aqwhois.aunic.net\*(Aq, \& \*(Aqaz\*(Aq => \*(Aqwhois.ripe.net\*(Aq, \& \*(Aqba\*(Aq => \*(Aqwhois.ripe.net\*(Aq, \& \*(Aqbe\*(Aq => \*(Aqwhois.ripe.net\*(Aq, .Ve .IP "\fBregister_parser()\fR" 4 .IX Item "register_parser()" Extend, modify and override entries in \f(CW%PARSERS\fR. Accepts a hash with three keys \- Name, Retain and Parser. If the format definition for the specified format exists and the Retain key holds a true value, the keys from the specified Parser are added to the existing definition. A new definition is created when Retain is false/not specified. .Sp .Vb 8 \& my $w = new Net::Whois; \& $w\->register_parser ( \& Name => "INTERNIC", \& Retain => 1, \& Parser => { \& creation_time => \*(Aqcreated on (\eS*?)\e.\en\*(Aq, \& some_randome_entity => \e&random_entity_subroutine \& }; .Ve .Sp Instructions on how to create a workable random_entity_subroutine are availabe in the \fI\f(CI%PARSERS\fI\fR description, above. .IP "\fBregister_association()\fR" 4 .IX Item "register_association()" Override and add entries to \f(CW%ASSOC\fR. Accepts a hash that contains representation specs for a whois server. The keys of this hash are server machine names and values are list-refs to the associated response formats and the top-level domains handled by the servers. See Net/XWhois.pm for more details. .Sp .Vb 4 \& my $w = new Net::XWhois; \& $w\->register_association ( \& \*(Aqwhois.aunic.net\*(Aq => [ RIPE, [ qw/au/ ] ] \& ); .Ve .IP "\fBregister_cache()\fR" 4 .IX Item "register_cache()" By default, Net::XWhois caches all whois responses and commits them, as separate files, to /tmp/whois. register_cache () gets and sets the cache directory. Setting to \*(L"undef\*(R" will disable caching. .Sp .Vb 2 \& $w\->register_cache ( "/some/place/else" ); \& $w\->register_cache ( undef ); .Ve .SH "OBJECT METHODS" .IX Header "OBJECT METHODS" .IP "\fBData Instance Methods\fR" 4 .IX Item "Data Instance Methods" Access to the whois response data is provided via \s-1AUTOLOADED\s0 methods specified in the Parser. The methods return scalar or list data depending on the context. .Sp Internic Parser provides the following methods: .RS 4 .IP "\fB\fBname()\fB\fR" 8 .IX Item "name()" Domain name. .IP "\fB\fBstatus()\fB\fR" 8 .IX Item "status()" Domain Status when provided. When the domain is on hold, this method will return \*(L"On Hold\*(R" string. .IP "\fB\fBnameservers()\fB\fR" 8 .IX Item "nameservers()" Nameservers along with their IPs. .IP "\fBregistrant\fR" 8 .IX Item "registrant" Registrant's name and address. .IP "\fB\fBcontact_admin()\fB\fR" 8 .IX Item "contact_admin()" Administrative Contact. .IP "\fB\fBcontact_tech()\fB\fR" 8 .IX Item "contact_tech()" Technical Contact. .IP "\fB\fBcontact_zone()\fB\fR" 8 .IX Item "contact_zone()" Zone Contact. .IP "\fB\fBcontact_billing()\fB\fR" 8 .IX Item "contact_billing()" Billing Contact. .IP "\fB\fBcontact_emails()\fB\fR" 8 .IX Item "contact_emails()" List of email addresses of contacts. .IP "\fB\fBcontact_handles()\fB\fR" 8 .IX Item "contact_handles()" List of contact handles in the response. Contact and Domain handles are valid query data that can be used instead of contact and domain names. .IP "\fB\fBdomain_handles()\fB\fR" 8 .IX Item "domain_handles()" List of domain handles in the response. Can be used for sorting out reponses that contain multiple domain names. .RE .RS 4 .RE .IP "\fB\fBlookup()\fB\fR" 4 .IX Item "lookup()" Does a whois lookup on the specified domain. Takes the same arguments as \&\fBnew()\fR. .Sp .Vb 3 \& my $w = new Net::XWhois; \& $w\->lookup ( Domain => "perl.com" ); \& print $w\->response (); .Ve .SH "EXAMPLES" .IX Header "EXAMPLES" Look at example programs that come with this package. \*(L"whois\*(R" is a replacement for the standard RIPE/InterNIC whois client. \*(L"creation\*(R" overrides the Parser value at object init and gets the Creation Time of an InterNIC domain. \*(L"creation2\*(R" does the same thing by extending the Class Parser. \*(L"contacts\*(R" queries and prints information about domain's Tech/Billing/Admin contacts. .PP contribs/ containts parsers for serveral whois servers, which have not been patched into the module. .SH "AUTHOR" .IX Header "AUTHOR" Vipul Ved Prakash .SH "THANKS" .IX Header "THANKS" Curt Powell , Matt Spiers , Richard Dice , Robert Chalmers , Steinar Overbeck Cook , Steve Weathers , Robert Puettmann , Martin H . Sluka" , Rob Woodard , Jon Gilbert, Erik Aronesty for patches, bug-reports and many cogent suggestions. .SH "MAILING LIST" .IX Header "MAILING LIST" Net::XWhois development has moved to the sourceforge mailing list, xwhois\-devel@lists.sourceforge.net. Please send all Net::XWhois related communication directly to the list address. The subscription interface is at: http://lists.sourceforge.net/mailman/listinfo/xwhois\-devel .SH "SEE ALSO" .IX Header "SEE ALSO" .Vb 2 \& RFC 954 \& RFC 2622 .Ve .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (c) 1998\-2001 Vipul Ved Prakash. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.