Reference

std/os/network

std/os/src/network.trb

NetworkInterface - a network interface of the machine with its addresses - and the values it is made of: InterfaceAddress, InterfaceStatus and InterfaceKind.

NetworkInterface.all is a match OperatingSystem.current whose arm hands the question to the directory of that system; only the arm of the build's target is compiled. The interface's traffic is a later step of docs/design/OS.md slice 5.

type NetworkInterface

type NetworkInterface with Show, Equals

A network interface and its addresses.

Examples

for interface in NetworkInterface.all()? {
  print "{interface.name} {interface.kind} {interface.status} {interface.addresses}"
}

Pitfalls

  • An interface can have no address at all: one that is down, or one that has not been configured.
  • status is what the system says about the link. A system that does not say, or an interface that is being brought up, is Unknown, and Unknown is not Down.

Related

field name

name: String

eth0, en0, and on Windows the friendly name: Ethernet 2, WLAN.

field description

description: String?

The adapter's description where the system has one: Intel(R) Ethernet Controller I225-V.

field index

index: Int

The system's index, what a scoped IPv6 address and a socket option refer to.

field hardwareAddress

hardwareAddress: MacAddress?

The link-layer address, where the interface has one: a loopback or a tunnel interface has none.

field addresses

addresses: List<InterfaceAddress>

Every address of it, IPv4 and IPv6, in the order the system lists them.

field mtu

mtu: Int

The largest packet it carries, in bytes; 0 where the system does not say.

field status

status: InterfaceStatus

Whether the link is up.

field kind

kind: InterfaceKind

What kind of interface it is.

fn all

static fn all(): Result<List<Self>, OsError>

The interfaces of the machine, with their addresses, in the order of their indexes. It asks the system once and waits for nothing.

Errors

  • OsError.Malformed where an answer of the system is not in the form its reader expects.
  • OsError.Unsupported on macOS, Windows and FreeBSD for now, and in a browser, which has no interfaces.
  • OsError.Failed where the system's call fails, with its words.

Examples

const interfaces = NetworkInterface.all()?
print "{interfaces.length()} interfaces"

type InterfaceAddress

type InterfaceAddress with Show, Equals

One address of an interface, with the length of its network prefix: 192.168.1.23/24, fe80::1/64. The address is the interface's own, not the network's: InterfaceAddress.subnet is the network.

Examples

const address = InterfaceAddress(IpAddress.tryFrom("192.168.1.23")?, 24)
print address
// prints 192.168.1.23/24

field address

address: IpAddress

The address, without a zone: the interface that scopes a link-local address is the one that holds it.

field prefixLength

prefixLength: Int

The leading bits of it that name the network: 0 to 32 for IPv4, 0 to 128 for IPv6.

fn show

fn show(): String

192.168.1.23/24.

fn subnet

fn subnet(): Result<Subnet, OsError>

The network the address is in: its first prefixLength bits and zeros after them, so 192.168.1.23/24 is in 192.168.1.0/24 and fe80::1/64 in fe80::/64. The prefix length of 0 is the whole address space and the full length (32, 128) a network of that one address.

Errors

  • OsError.Malformed where prefixLength is negative or longer than the address, which the system never writes and a value built by hand can.

Examples

const address = InterfaceAddress(IpAddress.tryFrom("192.168.1.23")?, 24)
print(address.subnet()?)
// prints 192.168.1.0/24

type InterfaceStatus

type InterfaceStatus with Show, Equals

Whether the link of an interface is up.

case Up

case Up

The link is up.

case Down

case Down

The link is down.

case Unknown

case Unknown

The system does not say, or the interface is being brought up.

type InterfaceKind

type InterfaceKind with Show, Equals

What kind of interface a NetworkInterface is.

case Ethernet

case Ethernet

A wired network adapter, or a virtual one that behaves as one: a bridge, a virtual machine's.

case Wireless

case Wireless

A wireless adapter.

case Loopback

case Loopback

The machine talking to itself: lo.

case Tunnel

case Tunnel

A point-to-point link into another network: a VPN, wg0, tun0, a GRE or SIT tunnel, PPP.

case Other

case Other

Anything else, and an interface whose kind the system does not say.