chickadee » socket » ai/passive

Looks up node name and service name and translates them to numeric values. Returns a list of addrinfo objects, each of which contains a socket address (sockaddr object) suitable for use in socket calls such as socket-bind and socket-connect.

node is either a node name (string) or IP address (string). service may be a string representing a service name or port number, or an integer. If node is #f, it is treated as the loopback address; however, if ai/passive is set it is treated as the unspecified address. If service is #f, it is treated as unspecified (0).

Keyword arguments accept numeric constants and restrict the returned addresses accordingly:

family

Address family, either af/inet or af/inet6, defaulting to #f. If #f, both IPv6 and IPv4 addresses may be returned, depending on your system's configuration and IP stack.

type

Socket type; usually sock/stream or sock/dgram, defaulting to sock/stream. Can be #f, but results may vary between systems, so it is safer to specify one. See examples.

protocol

Protocol type, usually #f. Can also be ipproto/tcp or ipproto/udp; however, some systems (such as Windows) do not construct a proper socket address when type is unspecified, so it is safer to just provide a value for type and leave this as #f.

The behavior of address-information can be influenced by the value of flags, which should be the bitwise-ior (or simply +) of any of the following constants:

ai/numerichost

The host is an IP address string; do not attempt to resolve it.

ai/passive

The socket address is intended to be used in a call to bind(). The only difference is that an address of #f is translated into the unspecified address "::" or "0.0.0.0", rather than the loopback address.

ai/canonname

Include the canonical (usually FQDN) hostname in the addrinfo object. If not provided, that field will be #f.

Examples:

(address-information "localhost" "http")
  ; => (#<addrinfo "[::1]:80" af/inet6 sock/stream ipproto/tcp>
        #<addrinfo "[fe80::1%lo0]:80" af/inet6 sock/stream ipproto/tcp>
        #<addrinfo "127.0.0.1:80" af/inet sock/stream ipproto/tcp>)
(address-information "127.0.0.1" 53 type: sock/dgram)
  ; => (#<addrinfo "127.0.0.1:53" af/inet sock/stream ipproto/udp>)
(address-information "he.net" 80)
  ; => (#<addrinfo "[2001:470:0:76::2]:80" af/inet6 sock/stream ipproto/tcp>
        #<addrinfo "216.218.186.2:80" af/inet sock/stream ipproto/tcp>)
(address-information "he.net" 80 type: #f)
  ; Possible response on UNIX -- return both TCP and UDP addresses.
  ; Might also just return TCP.
  ; => (#<addrinfo "[2001:470:0:76::2]:80" af/inet6 sock/dgram ipproto/udp>
        #<addrinfo "[2001:470:0:76::2]:80" af/inet6 sock/stream ipproto/tcp>
        #<addrinfo "216.218.186.2:80" af/inet sock/dgram ipproto/udp>
        #<addrinfo "216.218.186.2:80" af/inet sock/stream ipproto/tcp>)
  ; Possible response on Windows -- socket addresses are not valid for use
  ; => (#<addrinfo "[2001:470:0:76::2]:80" af/inet6 0 0>
        #<addrinfo "216.218.186.2:80" af/inet 0 0>)
(address-information #f "http")
  ; => (#<addrinfo "[::1]:80" af/inet6 sock/stream ipproto/tcp>
        #<addrinfo "127.0.0.1:80" af/inet sock/stream ipproto/tcp>)
(address-information #f "http" flags: ai/passive)
  ; => (#<addrinfo "[::]:80" af/inet6 sock/stream ipproto/tcp>
        #<addrinfo "0.0.0.0:80" af/inet sock/stream ipproto/tcp>)
  ; As an example of inconsistent per-platform behavior, note that
  ; recent Ubuntu among others returns the above in reverse order.
(address-information "allie" 0 flags: ai/canonname)
  ; => (#<addrinfo "192.168.1.7" af/inet sock/stream ipproto/tcp
                   canonical: "allie.xorinia.dim">)
(address-information #f #f)
  ; => ()