NAME
Socket::More::Lookup - System DNS Lookup Routines
SYNOPSIS
use Socket::More::Lookup;
use Socket::More::Constants;
# Convert a host name to one or more address structures
my $res=getaddrinfo( "www.google.com", 80, {family=>AF_INET}, my @results);
die gai_strerror($!) unless $res;
# Convert an addres structure to a hostname and port
my $res=getnameinfo($addr, my $host="", my $port="", $flags);
die gai_strerror($!) unless $res;DESCRIPTION
This is an alternative implementation to the Perl Socket subroutines for address and name resolution. It provides bindings to getaddrinfo, getnameinfo, gai_strerror.
Big differences between Core Perl Socket and this module:
- More like the C library and Perl's 'sys*' subroutines
-
The return value is a indication of success, while the results are stored in an 'in/out' array
- Error codes is stored in
$! -
The user must convert to a string error if they want it via
gai_strerror - Results are either hash or arrays
-
If the hints used is an array the returned results will be arrays. If the hints are a hash, the results are a hash
This module is part of Socket::More but exists as a standalone distribution for better reuse and smaller memory footprint
If you are after asynchronous resolving with event loop (or not) integration, please look at Socket::More::Resolver.
The resulting address information is super set of the Core Perl routines.
API
getaddrinfo
my $res=getaddrinfo($host, $port, \%hints, @results)
my $res=getaddrinfo($host, $port, \@hints, @results)Calls the getaddrinfo library function to resolve the address information of $host. The $port variable is filled into the resulting address structure.
The address structures returned are influenced by the hints provided by as either a hash reference \%hints or array reference \@hints. If it isn't a reference, the default hints are used. If the array is an empty array, the default hints are used.
The hash keys accepted for hints are flags, family, socktype and protocol. The array version expects each element to be in this order.
Please refer to the man page of getaddrinfo for details on what the hint values mean.
Results, if any are are stored in @results. If the hints argument was a hash reference, the results are represented as a hash references. If hints was an array reference, the results are represented as array references. The hash case contains the keys flags, family, socktype, protocol, addr and cannonname. The array case contains the fields in the same order.
Please refer to the main page of getaddrinfo for details.
Returns true on success, on undef on failure. In the later case $! is set to the numeric error code, which can then be converted to a string via gai_strerror.
getnaminfo
my $res=getnameinfo($sock_addr, $host, $port);
my $res=getnameinfo($sock_addr, my $host="", my $port="",$flags);Calls the getnameinfolibrary function to convert a known address structure to a host and port. The resulting hostname and port number are stored in the arguments $host and $port. This must be defined string and writable variables.
The output is influenced by the $flags argument. Please refer to the man page of getnameinfo for details.
Returns true on success, on undef on failure. In the later case $! is set to the numeric error code, which can then be converted to a string via gai_strerror
gai_strerror
my $string=gai_strerror($code)Converts a numerical error code returned from either getaddrinfo or getnameinfo into a human readable string. Please refer to man page of gai_strerror for more details
AUTHOR
Ruben Westerberg, <drclaw@mac.com>
REPOSITORTY and BUGS
Please report any bugs via git hub: https://github.com/drclaw1394/perl-socket-more-lookup
COPYRIGHT AND LICENSE
Copyright (C) 2024 by Ruben Westerberg
This library is free software; you can redistribute it and/or modify it under the same terms as Perl or the MIT license.
DISCLAIMER OF WARRANTIES
THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.