net::dial +linux +x86_64

net::dial provides a single function to facilitate the establishment of outgoing network connections. It handles port selection, address parsing, protocol and service lookup, DNS lookup (via /etc/hosts, /etc/resolv.conf, etc), SRV record resolution, and so on. See dial for details.

Modules implementing their own network protocols are also able to add themselves to the protocol and service registry. The protocol registry is used for transport-level protocols (such as TCP) and is managed via registerproto; the service registry is used for application-level protocols (such as SSH) and is managed via registersvc.

Some useful functions for IP-related protocols to interpret the "addr" parameter of the dial function are also provided, namely resolve.

Index

Types

type dialer;

Errors

type error;
type invalid_address;
type unknown_service;

Functions

fn dial(str, str, str) (net::socket | error);
fn registerproto(str, *dialer) void;
fn registersvc(str, str, []str, u16) void;
fn resolve(str, str, str) (([]ip::addr, u16) | error);
fn strerror(error) const str;

Types

type dialer[link]

type dialer = fn(addr: str, service: str) (net::socket | error);

A dialer is a function which implements dial for a specific protocol.

Errors

type error[link]

type error = !(invalid_address | unknown_service | net::error | dns::error);

Errors which can occur from dial.

type invalid_address[link]

type invalid_address = !void;

Returned if the address parameter was invalid, for example if it specifies an invalid port number.

type unknown_service[link]

type unknown_service = !void;

Returned if the service parameter does not name a service known to the system.

Functions

fn dial[link]

fn dial(proto: str, address: str, service: str) (net::socket | error);

Dials a remote address, establishing a connection and returning the resulting net::socket. The proto parameter should be the transport protocol (e.g. "tcp"), the address parameter should be the remote address, and the service should be the name of the service, or the default port to use.

The interpretation of the address and service parameters is dependent on the protocol in use. For IP-based protocols (such as TCP or UDP), the address parameter may be either an IPv4 or IPv6 address, or a name, and may include a port separated by a colon (':'). If an IPv6 address and a port are both desired, use brackets ('[' and ']') to separate the address from the port (e.g. "[::1]:80"). If the port is not specified, it is inferred from the service parameter. If a name is used instead of an IP address, a DNS lookup is performed, consulting the local /etc/hosts file or equivalent, if possible.

The service parameter can be a service name (e.g. "submission") or a default port to use, if one is not specified by address. If a service name is used, an internal list of services is consulted (see registersvc), and if not known to Hare, the system service list (e.g. /etc/services) will be consulted. If the connection port cannot be established, errors::invalid is returned. The special service name "unknown" will always consult the address parameter for a desired port, and will return errors::invalid if one is not provided there.

If the address parameter includes a name, but not a port, an SRV lookup will be performed alongside the A or AAAA record lookup for that name. If the name server provides an SRV record for the given service, it will be utilized in lieu of the service database.

fn registerproto[link]

fn registerproto(name: str, dial: *dialer) void;

Registers a new transport-level protocol (e.g. TCP) with the dialer. The name should be statically allocated.

fn registersvc[link]

fn registersvc(proto: str, name: str, alias: []str, port: u16) void;

Registers a new application-level service (e.g. SSH) with the dialer. Note that the purpose of services is simply to establish the default outgoing port for TCP and UDP connections. The name and alias list should be statically allocated.

fn resolve[link]

fn resolve(proto: str, addr: str, service: str) (([]ip::addr, u16) | error);

Performs DNS resolution on a given address string for a given service, including /etc/hosts lookup and SRV resolution, and returns a list of candidate IP addresses and the appropriate port, or an error.

The caller must free the net::ip::addr slice.

fn strerror[link]

fn strerror(err: error) const str;

Converts an error to a human-readable string.