This section describes procedures which query various network databases. Care should be taken when using the database routines since they are not reentrant.
getaddrinfo ¶The getaddrinfo procedure maps host and service names to socket addresses
and associated information in a protocol-independent way.
Return a list of addrinfo structures containing
a socket address and associated information for host name
and/or service to be used in creating a socket with
which to address the specified service.
(let* ((ai (car (getaddrinfo "www.gnu.org" "http")))
(s (socket (addrinfo:fam ai) (addrinfo:socktype ai)
(addrinfo:protocol ai))))
(connect s (addrinfo:addr ai))
s)
When service is omitted or is #f, return
network-level addresses for name. When name
is #f service must be provided and service
locations local to the caller are returned.
Additional hints can be provided. When specified, hint_flags should be a bitwise-or of zero or more constants among the following:
AI_PASSIVESocket address is intended for bind.
AI_CANONNAMERequest for canonical host name, available via
addrinfo:canonname. This makes sense mainly when
DNS lookups are involved.
AI_NUMERICHOSTSpecifies that name is a numeric host address string
(e.g., "127.0.0.1"), meaning that name resolution
will not be used.
AI_NUMERICSERVLikewise, specifies that service is a numeric port
string (e.g., "80").
AI_ADDRCONFIGReturn only addresses configured on the local system It is highly recommended to provide this flag when the returned socket addresses are to be used to make connections; otherwise, some of the returned addresses could be unreachable or use a protocol that is not supported.
AI_V4MAPPEDWhen looking up IPv6 addresses, return mapped IPv4 addresses if there is no IPv6 address available at all.
AI_ALLIf this flag is set along with AI_V4MAPPED when looking up IPv6
addresses, return all IPv6 addresses as well as all IPv4 addresses, the latter
mapped to IPv6 format.
When given, hint_family should specify the requested
address family, e.g., AF_INET6. Similarly,
hint_socktype should specify the requested socket type
(e.g., SOCK_DGRAM), and hint_protocol should
specify the requested protocol (its value is interpreted
as in calls to socket).
On error, an exception with key getaddrinfo-error is
thrown, with an error code (an integer) as its argument:
(catch 'getaddrinfo-error
(lambda ()
(getaddrinfo "www.gnu.org" "gopher"))
(lambda (key errcode)
(cond ((= errcode EAI_SERVICE)
(display "doesn't know about Gopher!\n"))
((= errcode EAI_NONAME)
(display "www.gnu.org not found\\n"))
(else
(format #t "something wrong: ~a\n"
(gai-strerror errcode))))))
Error codes are:
EAI_AGAINThe name or service could not be resolved at this time. Future attempts may succeed.
EAI_BADFLAGShint_flags contains an invalid value.
EAI_FAILA non-recoverable error occurred when attempting to resolve the name.
EAI_FAMILYhint_family was not recognized.
EAI_NONAMEEither name does not resolve for the supplied parameters, or neither name nor service were supplied.
EAI_NODATAThis non-POSIX error code can be returned on some systems (GNU and Darwin, at least), for example when name is known but requests that were made turned out no data. Error handling code should be prepared to handle it when it is defined.
EAI_SERVICEservice was not recognized for the specified socket type.
EAI_SOCKTYPEhint_socktype was not recognized.
EAI_SYSTEMA system error occurred. In C, the error code can be found in
errno; this value is not accessible from Scheme, but in
practice it provides little information about the actual error
cause.
Users are encouraged to read the "POSIX specification for more details.
The following procedures take an addrinfo object as returned by
getaddrinfo:
Return flags for ai as a bitwise or of AI_ values (see above).
Return the address family of ai (a AF_ value).
Return the socket type for ai (a SOCK_ value).
Return the protocol of ai.
Return the socket address associated with ai as a sockaddr
object (see Network Socket Address).
Return a string for the canonical name associated with ai if
the AI_CANONNAME flag was supplied.
A host object is a structure that represents what is known about a network host, and is the usual way of representing a system’s network identity inside software.
The following functions accept a host object and return a selected component:
The “official” hostname for host.
A list of aliases for host.
The host address type, one of the AF constants, such as
AF_INET or AF_INET6.
The length of each address for host, in bytes.
The list of network addresses associated with host. For
AF_INET these are integer IPv4 address (see Network Address Conversion).
The following procedures can be used to search the host database. However,
getaddrinfo should be preferred over them since it’s more generic and
thread-safe.
Look up a host by name or address, returning a host object. The
gethost procedure will accept either a string name or an integer
address; if given no arguments, it behaves like gethostent (see
below). If a name or address is supplied but the address can not be
found, an error will be thrown to one of the keys:
host-not-found, try-again, no-recovery or
no-data, corresponding to the equivalent h_error values.
Unusual conditions may result in errors thrown to the
system-error or misc_error keys.
(gethost "www.gnu.org")
⇒ #("www.gnu.org" () 2 4 (3353880842))
(gethostbyname "www.emacs.org")
⇒ #("emacs.org" ("www.emacs.org") 2 4 (1073448978))
The following procedures may be used to step through the host database from beginning to end.
Initialize an internal stream from which host objects may be read. This
procedure must be called before any calls to gethostent, and may
also be called afterward to reset the host entry stream. If
stayopen is supplied and is not #f, the database is not
closed by subsequent gethostbyname or gethostbyaddr calls,
possibly giving an efficiency gain.
Return the next host object from the host database, or #f if
there are no more hosts to be found (or an error has been encountered).
This procedure may not be used before sethostent has been called.
Close the stream used by gethostent. The return value is unspecified.
If stayopen is omitted, this is equivalent to endhostent.
Otherwise it is equivalent to sethostent stayopen.
The following functions accept an object representing a network and return a selected component:
The “official” network name.
A list of aliases for the network.
The type of the network number. Currently, this returns only
AF_INET.
The network number.
The following procedures are used to search the network database:
Look up a network by name or net number in the network database. The
net-name argument must be a string, and the net-number
argument must be an integer. getnet will accept either type of
argument, behaving like getnetent (see below) if no arguments are
given.
The following procedures may be used to step through the network database from beginning to end.
Initialize an internal stream from which network objects may be read. This
procedure must be called before any calls to getnetent, and may
also be called afterward to reset the net entry stream. If
stayopen is supplied and is not #f, the database is not
closed by subsequent getnetbyname or getnetbyaddr calls,
possibly giving an efficiency gain.
Return the next entry from the network database.
Close the stream used by getnetent. The return value is unspecified.
If stayopen is omitted, this is equivalent to endnetent.
Otherwise it is equivalent to setnetent stayopen.
The following functions accept an object representing a protocol and return a selected component:
The “official” protocol name.
A list of aliases for the protocol.
The protocol number.
The following procedures are used to search the protocol database:
Look up a network protocol by name or by number. getprotobyname
takes a string argument, and getprotobynumber takes an integer
argument. getproto will accept either type, behaving like
getprotoent (see below) if no arguments are supplied.
The following procedures may be used to step through the protocol database from beginning to end.
Initialize an internal stream from which protocol objects may be read. This
procedure must be called before any calls to getprotoent, and may
also be called afterward to reset the protocol entry stream. If
stayopen is supplied and is not #f, the database is not
closed by subsequent getprotobyname or getprotobynumber calls,
possibly giving an efficiency gain.
Return the next entry from the protocol database.
Close the stream used by getprotoent. The return value is unspecified.
If stayopen is omitted, this is equivalent to endprotoent.
Otherwise it is equivalent to setprotoent stayopen.
The following functions accept an object representing a service and return a selected component:
The “official” name of the network service.
A list of aliases for the network service.
The Internet port used by the service.
The protocol used by the service. A service may be listed many times in the database under different protocol names.
The following procedures are used to search the service database:
Look up a network service by name or by service number, and return a network service object. The protocol argument specifies the name of the desired protocol; if the protocol found in the network service database does not match this name, a system error is signaled.
The getserv procedure will take either a service name or number
as its first argument; if given no arguments, it behaves like
getservent (see below).
(getserv "imap" "tcp")
⇒ #("imap2" ("imap") 143 "tcp")
(getservbyport 88 "udp")
⇒ #("kerberos" ("kerberos5" "krb5") 88 "udp")
The following procedures may be used to step through the service database from beginning to end.
Initialize an internal stream from which service objects may be read. This
procedure must be called before any calls to getservent, and may
also be called afterward to reset the service entry stream. If
stayopen is supplied and is not #f, the database is not
closed by subsequent getservbyname or getservbyport calls,
possibly giving an efficiency gain.
Return the next entry from the services database.
Close the stream used by getservent. The return value is unspecified.