`std/os/error`

std/os/src/error.trb

OsError, what asking the operating system can go wrong with, and outcome, the one function that turns the answer of a native of runtime/os/ into a Result.

Every native of std/os answers an Int outcome and writes its payload through var parameters, because a function of the runtime may not build a type of the program (docs/design/OS.md section 4). The per-system modules hand that outcome to outcome and never look at the number themselves.

type OsError

type OsError with Show, Equals, Error

What asking the operating system went wrong with. question is what was asked: the host name, the version, the cache directory.

No error code of a system is carried: a code is a number of one system, and a portable caller that could read it would compare it. The natives classify it instead (ERROR_ACCESS_DENIED and EACCES both become Denied), and the message keeps the system's own words.

Examples

use System from "std/os"

match System.hostName() {
  Ok(name) => print name
  Fail(.Unsupported(question, system)) => print "{system} cannot tell {question}"
  Fail(problem) => printError "{problem}"
}

outcome - where a native's number becomes one of these cases.

case Unsupported

case Unsupported(question: String, operatingSystem: OperatingSystem)

This operating system cannot answer the question at all.

case Denied

case Denied(question: String, reason: String)

The operating system refused: a permission, a container that hides /proc, a policy.

case Missing

case Missing(question: String, reason: String)

The question has no answer on this machine: no HOME and no account entry, no such registry value.

case Failed

case Failed(question: String, message: String)

The call failed, in the operating system's own words.

case Malformed

case Malformed(source: String, detail: String)

An answer came back in a form its reader did not expect: a /proc line, a registry value of the wrong type.

fn show

fn show(): String

One sentence that names the question and why it has no answer: the host name: access is denied.

std/os/error