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
addrinfostructures 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#fservice 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_PASSIVE- Socket address is intended for
bind.AI_CANONNAME- Request for canonical host name, available via
addrinfo:canonname. This makes sense mainly when DNS lookups are involved.AI_NUMERICHOST- Specifies that name is a numeric host address string (e.g.,
"127.0.0.1"), meaning that name resolution will not be used.AI_NUMERICSERV- Likewise, specifies that service is a numeric port string (e.g.,
"80").AI_ADDRCONFIG- Return 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_V4MAPPED- When looking up IPv6 addresses, return mapped IPv4 addresses if there is no IPv6 address available at all.
AI_ALL- If this flag is set along with
AI_V4MAPPEDwhen 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 interpretered as in calls tosocket).On error, an exception with key
getaddrinfo-erroris 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_AGAIN- The name or service could not be resolved at this time. Future attempts may succeed.
EAI_BADFLAGS- hint_flags contains an invalid value.
EAI_FAIL- A non-recoverable error occurred when attempting to resolve the name.
EAI_FAMILY- hint_family was not recognized.
EAI_NONAME- Either name does not resolve for the supplied parameters, or neither name nor service were supplied.
EAI_SERVICE- service was not recognized for the specified socket type.
EAI_SOCKTYPE- hint_socktype was not recognized.
EAI_SYSTEM- A system error occurred; the error code can be found in
errno.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 socket address associated with ai as a
sockaddrobject (see Network Socket Address).
Return a string for the canonical name associated with ai if the
AI_CANONNAMEflag 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 host address type, one of the
AFconstants, such asAF_INETorAF_INET6.
The list of network addresses associated with host. For
AF_INETthese 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
gethostprocedure will accept either a string name or an integer address; if given no arguments, it behaves likegethostent(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-recoveryorno-data, corresponding to the equivalenth_errorvalues. Unusual conditions may result in errors thrown to thesystem-errorormisc_errorkeys.(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 subsequentgethostbynameorgethostbyaddrcalls, possibly giving an efficiency gain.
Return the next host object from the host database, or
#fif there are no more hosts to be found (or an error has been encountered). This procedure may not be used beforesethostenthas 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 tosethostent stayopen.
The following functions accept an object representing a network and return a selected component:
The type of the network number. Currently, this returns only
AF_INET.
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.
getnetwill accept either type of argument, behaving likegetnetent(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 subsequentgetnetbynameorgetnetbyaddrcalls, possibly giving an efficiency gain.
If stayopen is omitted, this is equivalent to
endnetent. Otherwise it is equivalent tosetnetent stayopen.
The following functions accept an object representing a protocol and return a selected component:
The following procedures are used to search the protocol database:
Look up a network protocol by name or by number.
getprotobynametakes a string argument, andgetprotobynumbertakes an integer argument.getprotowill accept either type, behaving likegetprotoent(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 subsequentgetprotobynameorgetprotobynumbercalls, possibly giving an efficiency gain.
Close the stream used by
getprotoent. The return value is unspecified.
If stayopen is omitted, this is equivalent to
endprotoent. Otherwise it is equivalent tosetprotoent stayopen.
The following functions accept an object representing a service and return a selected component:
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 signalled.
The
getservprocedure will take either a service name or number as its first argument; if given no arguments, it behaves likegetservent(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 subsequentgetservbynameorgetservbyportcalls, possibly giving an efficiency gain.