| Current Path : /proc/2/root/usr/local/share/man/man3/ |
| Current File : //proc/2/root/usr/local/share/man/man3/Data::Validate::Domain.3pm |
.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\" ========================================================================
.\"
.IX Title "Data::Validate::Domain 3"
.TH Data::Validate::Domain 3 "2016-08-21" "perl v5.10.1" "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"
Data::Validate::Domain \- Domain and host name validation
.SH "VERSION"
.IX Header "VERSION"
version 0.14
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Data::Validate::Domain qw(is_domain);
\&
\& # as a function
\& my $test = is_domain($suspect);
\& die "$test is not a domain" unless $test;
\&
\& # or
\&
\& die "$test is not a domain" unless is_domain($suspect, \e%options);
\&
\& # or as an object
\& my $v = Data::Validate::Domain\->new(%options);
\&
\& die "$test is not a domain" unless $v\->is_domain($suspect);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module offers a few subroutines for validating domain and host names.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
All of the functions below are exported by default.
.PP
All of the functions return an untainted value on success and a false value
(\f(CW\*(C`undef\*(C'\fR or an empty list) on failure. In scalar context, you should check
that the return value is defined, because something like
\&\f(CW\*(C`is_domain_label(\*(Aq0\*(Aq)\*(C'\fR will return a defined but false value.
.PP
The value to test is always the first (and often only) argument.
.PP
Note that none of these functions test whether a domain or hostname is
actually resolvable or reachable.
.SS "Data::Validate::Domain\->\fInew()\fP"
.IX Subsection "Data::Validate::Domain->new()"
This method constructs a validation object. It accepts the following arguments:
.IP "\(bu" 4
domain_allow_underscore
.Sp
According to \s-1RFC\s0 underscores are forbidden in hostnames but not domain names.
By default \f(CW\*(C`is_domain()\*(C'\fR, \f(CW\*(C`is_domain_label()\*(C'\fR, and \f(CW\*(C`is_hostname()\*(C'\fR will
fail if the value to be checked includes underscores. Setting this to a true
value with allow the use of underscores in all functions.
.IP "\(bu" 4
domain_allow_single_label
.Sp
By default \f(CW\*(C`is_domain()\*(C'\fR will fail if you ask it to verify a domain that only
has a single label i.e. \*(L"neely.cx\*(R" is good, but \*(L"com\*(R" would fail. If you set
this option to a true value then \f(CW\*(C`is_domain()\*(C'\fR will allow single label
domains through. This is most likely to be useful in combination with
the \f(CW\*(C`domain_private_tld\*(C'\fR argument.
.IP "\(bu" 4
domain_disable_tld_validation
.Sp
Disables \s-1TLD\s0 validation for \f(CW\*(C`is_domain()\*(C'\fR. This may be useful if you need to
check domains with new gTLDs that have not yet been added to
Net::Domain::TLD.
.IP "\(bu" 4
domain_private_tld
.Sp
By default \f(CW\*(C`is_domain()\*(C'\fR requires all domains to have a valid public \s-1TLD\s0
(i.e. com, net, org, uk, etc). This is verified using the Net::Domain::TLD
module. This behavior can be extended in two different ways. You can provide
either a hash reference where additional TLDs are keys or you can supply a
regular expression.
.Sp
\&\s-1NOTE:\s0 The \s-1TLD\s0 is normalized to the lower case form prior to the check being
done. This is done only for the \s-1TLD\s0 check, and does not alter the output in
any way.
.Sp
Hashref example:
.Sp
.Vb 4
\& domain_private_tld => {
\& privatetld1 => 1,
\& privatetld2 => 1,
\& }
.Ve
.Sp
Regular expression example:
.Sp
.Vb 1
\& domain_private_tld => qr /^(?:privatetld1|privatetld2)$/,
.Ve
.SS "is_domain($domain, \e%options)"
.IX Subsection "is_domain($domain, %options)"
This can be called as either a subroutine or a method. If called as a sub, you
can pass any of the arguments accepted by the constructor as options. If
called as a method, any additional options are ignored.
.PP
This returns the untainted domain name if the given \f(CW$domain\fR is a valid
domain.
.PP
A dotted quad (such as 127.0.0.1) is not considered a domain and will return false.
See Data::Validate::IP for \s-1IP\s0 Validation.
.PP
Per \s-1RFC\s0 1035, this sub does accept a value ending in a single period
(i.e. \*(L"domain.com.\*(R") to be a valid domain. This is called an absolute domain
name, and should be properly resolved by any \s-1DNS\s0 tool (tested with \f(CW\*(C`dig\*(C'\fR,
\&\f(CW\*(C`ssh\*(C'\fR, and Net::DNS).
.IP "\fIFrom \s-1RFC\s0 952\fR" 4
.IX Item "From RFC 952"
.Vb 4
\& A "name" (Net, Host, Gateway, or Domain name) is a text string up
\& to 24 characters drawn from the alphabet (A\-Z), digits (0\-9), minus
\& sign (\-), and period (.). Note that periods are only allowed when
\& they serve to delimit components of "domain style names".
\&
\& No blank or space characters are permitted as part of a
\& name. No distinction is made between upper and lower case. The first
\& character must be an alpha character [Relaxed in RFC 1123] . The last
\& character must not be a minus sign or period.
.Ve
.IP "\fIFrom \s-1RFC\s0 1035\fR" 4
.IX Item "From RFC 1035"
.Vb 2
\& labels 63 octets or less
\& names 255 octets or less
\&
\& [snip] limit the label to 63 octets or less.
\&
\& To simplify implementations, the total length of a domain name (i.e.,
\& label octets and label length octets) is restricted to 255 octets or
\& less.
.Ve
.IP "\fIFrom \s-1RFC\s0 1123\fR" 4
.IX Item "From RFC 1123"
.Vb 4
\& One aspect of host name syntax is hereby changed: the
\& restriction on the first character is relaxed to allow either a
\& letter or a digit. Host software MUST support this more liberal
\& syntax.
\&
\& Host software MUST handle host names of up to 63 characters and
\& SHOULD handle host names of up to 255 characters.
.Ve
.SS "is_hostname($hostname, \e%options)"
.IX Subsection "is_hostname($hostname, %options)"
This can be called as either a subroutine or a method. If called as a sub, you
can pass any of the arguments accepted by the constructor as options. If
called as a method, any additional options are ignored.
.PP
This returns the untainted hostname if the given \f(CW$hostname\fR is a valid
hostname.
.PP
Hostnames are not required to end in a valid \s-1TLD\s0.
.SS "is_domain_label($label, \e%options)"
.IX Subsection "is_domain_label($label, %options)"
This can be called as either a subroutine or a method. If called as a sub, you
can pass any of the arguments accepted by the constructor as options. If
called as a method, any additional options are ignored.
.PP
This returns the untainted label if the given \f(CW$label\fR is a valid
label.
.PP
A domain label is simply a single piece of a domain or hostname. For example,
the \*(L"www.foo.com\*(R" hostname contains the labels \*(L"www\*(R", \*(L"foo\*(R", and \*(L"com\*(R".
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fB[\s-1RFC\s0 1034] [\s-1RFC\s0 1035] [\s-1RFC\s0 2181] [\s-1RFC\s0 1123]\fR
.IP "Data::Validate" 4
.IX Item "Data::Validate"
.PD 0
.IP "Data::Validate::IP" 4
.IX Item "Data::Validate::IP"
.PD
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
Thanks to Richard Sonnen <\fIsonnen@richardsonnen.com\fR> for writing the Data::Validate module.
.PP
Thanks to Len Reed <\fIlreed@levanta.com\fR> for helping develop the options mechanism for Data::Validate modules.
.SH "SUPPORT"
.IX Header "SUPPORT"
Bugs may be submitted through <the \s-1RT\s0 bug tracker>
(or <bug\-data\-validate\-domain@rt.cpan.org>).
.PP
I am also usually active on \s-1IRC\s0 as 'drolsky' on \f(CW\*(C`irc://irc.perl.org\*(C'\fR.
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
Neil Neely <neil@neely.cx>
.IP "\(bu" 4
Dave Rolsky <autarch@urth.org>
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
.IP "\(bu" 4
David Steinbrunner <dsteinbrunner@pobox.com>
.IP "\(bu" 4
Gregory Oschwald <goschwald@maxmind.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2016 by Neil Neely.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
Copyright 2K16 - 2K18 Indonesian Hacker Rulez
;?>)