get-host-entry

get-host-entry Function

Summary

Returns address (IPv6 and IPv4) or name information about a given host.

Package

comm

Signature

get-host-entry host &key fields ipv6 v4mapped addrconfig numerichost avoid-reverse-lookup => field-values

Arguments

`host`⇩	A number or a string.
`fields`⇩	A list of keywords.
`ipv6`⇩	`nil`, `t` or the keyword `:any`.
`v4mapped`⇩	A boolean.
`addrconfig`⇩	A boolean.
`numerichost`⇩	A boolean.
`avoid-reverse-lookup`⇩	A generalized boolean.

Values

field-values

Values, one for each field.

Description

The function get-host-entry returns address or name information about the given host. By default, it tries to find addresses both of IPv6 and IPv4. It uses whatever host naming services are configured on the current machine. nil is returned if the host is unknown.

host can be one of the following:

a name string, for example "www.foobar.com"
a dotted inet address string, for example "209.130.14.246"
a integer representing the inet address, for example #xD1820EF6

fields is a list of keywords describing what information to return for the host. If get-host-entry succeeds, it returns multiple values, one value for each field specified. The following fields are allowed:

`:address`	The primary IP address.
`:ipv6-address`	The primary IPv6 address.
`:ipv4-address`	The primary IPv4 address.
`:addresses`	A list of all the IP addresses.
`:ipv6-addresses`	A list of all the IPv6 addresses, only.
`:ipv4-addresses`	A list of all the IPv4 addresses, only.
`:name`	The primary name as a string.
`:aliases`	The alias names as a list of strings.

IPv4 addresses are returned as integers and IPv6 addresses are returned as objects of type ipv6-address.

If ipv6 is nil or t the search is restricted to one family only IPv4 or IPv6. The default value of ipv6 is :any, meaning that addresses in both families are returned. If the argument host is a string, that has a similar effect to using the family-specific keywords, but it may be faster. For example, these two calls returns the same addresses (possibly in a different order):

(get-host-entry "hostname"
                :fields '(:ipv6-addresses))
 
(get-host-entry "hostname"
                :fields '(:addresses) :ipv6 t)

If host is an address of the other type, that is integer with ipv6 t or ipv6-address with ipv6 nil, then get-host-entry first tries to do a reverse lookup to find the name of the host, and then looks for the values as if it was called with this name as the host.

When avoid-reverse-lookup is non-nil, get-host-entry avoids doing reverse lookup if host is a string which specifies a valid address (either IPv6 or IPv4). The default value of avoid-reverse-lookup is nil, so by default it does the lookup.

The arguments v4mapped, addrconfig and numerichost have an effect only when host is a string. They define the flags AI_V4MAPPED, AI_ADDRCONFIG and AI_NUMERICHOST when doing the getaddrinfo call.

When v4mapped is t, the IPv6 addresses contain an IPv4 address mapped to IPv6 (::ffff:<IPv4>). The default value of v4mapped is nil.

When addrconfig is t, addresses of a family are returned only if the local system is configured to handle them. The default value of addrconfig is nil.

When numerichost is t, host is assumed to be a numeric address, either IPv4 if dotted notation or IPv6. If it is not, get-host-entry just returns nil. Using numerichost can speed up get-host-entry, because it prevents any DNS lookup. This has an effect only if avoid-reverse-lookup is non-nil. The default value of numerichost is nil.

Notes

Although the results of get-host-entry are not cached by LispWorks, the Operating System might cache them.
When get-host-entry is passed a string specifying an IPv6 address, the address can be followed by '%' character and a scope ID. If the scope ID is a decimal number or a valid interface name on the local system, the resulting address contains the scope ID as a number.

Examples

CL-USER 16 > (comm:get-host-entry "www.altavista.com" 
                                  :fields '(:address))
3511264349
 
CL-USER 17 > (comm:get-host-entry 3511264349 
                                  :fields '(:name))
"altavista.com"
 
CL-USER 18 > (comm:get-host-entry "altavista.com" 
                                  :fields '(:name 
                                            :address 
                                            :aliases))
"altavista.com"
3511264349
("www.altavista.com" "www.altavista.com")