info guile

7.2.11.2 Network Databases

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.

Scheme Procedure: getaddrinfo name service [hint_flags [hint_family [hint_socktype [hint_protocol]]]]

C Function: scm_getaddrinfo (name, service, hint_flags, hint_family, hint_socktype, hint_protocol)

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_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_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_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_NODATA: This 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_SERVICE: service was not recognized for the specified socket type.
EAI_SOCKTYPE: hint_socktype was not recognized.
EAI_SYSTEM: A 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:

Scheme Procedure: addrinfo:flags ai: Return flags for ai as a bitwise or of AI_ values (see above).

Scheme Procedure: addrinfo:fam ai: Return the address family of ai (a AF_ value).

Scheme Procedure: addrinfo:socktype ai: Return the socket type for ai (a SOCK_ value).

Scheme Procedure: addrinfo:protocol ai: Return the protocol of ai.

Scheme Procedure: addrinfo:addr ai: Return the socket address associated with ai as a sockaddr object (see section Network Socket Address).

Scheme Procedure: addrinfo:canonname ai: Return a string for the canonical name associated with ai if the AI_CANONNAME flag was supplied.

The Host Database

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:

Scheme Procedure: hostent:name host: The “official” hostname for host.

Scheme Procedure: hostent:aliases host: A list of aliases for host.

Scheme Procedure: hostent:addrtype host: The host address type, one of the AF constants, such as AF_INET or AF_INET6.

Scheme Procedure: hostent:length host: The length of each address for host, in bytes.

Scheme Procedure: hostent:addr-list host: The list of network addresses associated with host. For AF_INET these are integer IPv4 address (see section 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.

Scheme Procedure: gethost [host]

Scheme Procedure: gethostbyname hostname

Scheme Procedure: gethostbyaddr address

C Function: scm_gethost (host)

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.

Scheme Procedure: sethostent [stayopen]: 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.

Scheme Procedure: gethostent: 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.

Scheme Procedure: endhostent: Close the stream used by gethostent. The return value is unspecified.

Scheme Procedure: sethost [stayopen]
C Function: scm_sethost (stayopen): If stayopen is omitted, this is equivalent to endhostent. Otherwise it is equivalent to sethostent stayopen.

The Network Database

The following functions accept an object representing a network and return a selected component:

Scheme Procedure: netent:name net: The “official” network name.

Scheme Procedure: netent:aliases net: A list of aliases for the network.

Scheme Procedure: netent:addrtype net: The type of the network number. Currently, this returns only AF_INET.

Scheme Procedure: netent:net net: The network number.

The following procedures are used to search the network database:

Scheme Procedure: getnet [net]
Scheme Procedure: getnetbyname net-name
Scheme Procedure: getnetbyaddr net-number
C Function: scm_getnet (net): 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.

Scheme Procedure: setnetent [stayopen]: 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.

Scheme Procedure: getnetent: Return the next entry from the network database.

Scheme Procedure: endnetent: Close the stream used by getnetent. The return value is unspecified.

Scheme Procedure: setnet [stayopen]
C Function: scm_setnet (stayopen): If stayopen is omitted, this is equivalent to endnetent. Otherwise it is equivalent to setnetent stayopen.

The Protocol Database

The following functions accept an object representing a protocol and return a selected component:

Scheme Procedure: protoent:name protocol: The “official” protocol name.

Scheme Procedure: protoent:aliases protocol: A list of aliases for the protocol.

Scheme Procedure: protoent:proto protocol: The protocol number.

The following procedures are used to search the protocol database:

Scheme Procedure: getproto [protocol]
Scheme Procedure: getprotobyname name
Scheme Procedure: getprotobynumber number
C Function: scm_getproto (protocol): 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.

Scheme Procedure: setprotoent [stayopen]: 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.

Scheme Procedure: getprotoent: Return the next entry from the protocol database.

Scheme Procedure: endprotoent: Close the stream used by getprotoent. The return value is unspecified.

Scheme Procedure: setproto [stayopen]
C Function: scm_setproto (stayopen): If stayopen is omitted, this is equivalent to endprotoent. Otherwise it is equivalent to setprotoent stayopen.

The Service Database

The following functions accept an object representing a service and return a selected component:

Scheme Procedure: servent:name serv: The “official” name of the network service.

Scheme Procedure: servent:aliases serv: A list of aliases for the network service.

Scheme Procedure: servent:port serv: The Internet port used by the service.

Scheme Procedure: servent:proto serv: 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:

Scheme Procedure: getserv [name [protocol]]

Scheme Procedure: getservbyname name protocol

Scheme Procedure: getservbyport port protocol

C Function: scm_getserv (name, protocol)

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 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.

Scheme Procedure: setservent [stayopen]: 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.

Scheme Procedure: getservent: Return the next entry from the services database.

Scheme Procedure: endservent: Close the stream used by getservent. The return value is unspecified.

Scheme Procedure: setserv [stayopen]
C Function: scm_setserv (stayopen): If stayopen is omitted, this is equivalent to endservent. Otherwise it is equivalent to setservent stayopen.

This document was generated on April 20, 2013 using texi2html 5.0.