# std/oserrors

Theme:

- Manual
- Standard library
- Index
- Compiler docs
- Fusion docs
- devel, stable

Search:
Source Edit

The `std/oserrors` module implements OS error reporting.

# Types

    OSErrorCode = distinct int32

  Specifies an OS Error Code. Source Edit

# Procs

    proc `$`(err: OSErrorCode): string {.borrow, ...raises: [], tags: [], forbids: [].}

  Source Edit

    proc `==`(err1, err2: OSErrorCode): bool {.borrow, ...raises: [], tags: [],
        forbids: [].}

  Source Edit

    proc newOSError(errorCode: OSErrorCode; additionalInfo = ""): owned(ref OSError) {.
        noinline, ...raises: [], tags: [], forbids: [].}

  Creates a new OSError exception.

  The `errorCode` will determine the message, osErrorMsg proc will be used to get this message.

  The error code can be retrieved using the osLastError proc.

  If the error code is `0` or an error message could not be retrieved, the message `unknown OS error` will be used.

  See also:

  - osErrorMsg proc
  - osLastError proc
  Source Edit

    proc osErrorMsg(errorCode: OSErrorCode): string {....raises: [], tags: [],
        forbids: [].}

  Converts an OS error code into a human readable string.

  The error code can be retrieved using the osLastError proc.

  If conversion fails, or `errorCode` is `0` then `""` will be returned.

  See also:

  - raiseOSError proc
  - osLastError proc

  Example:

      when defined(linux):
        assert osErrorMsg(OSErrorCode(0)) == ""
        assert osErrorMsg(OSErrorCode(1)) == "Operation not permitted"
        assert osErrorMsg(OSErrorCode(2)) == "No such file or directory"

  Source Edit

    proc osLastError(): OSErrorCode {.sideEffect, ...raises: [], tags: [], forbids: [].}

  Retrieves the last operating system error code.

  This procedure is useful in the event when an OS call fails. In that case this procedure will return the error code describing the reason why the OS call failed. The `OSErrorMsg` procedure can then be used to convert this code into a string.

  Warning: The behaviour of this procedure varies between Windows and POSIX systems. On Windows some OS calls can reset the error code to `0` causing this procedure to return `0`. It is therefore advised to call this procedure immediately after an OS call fails. On POSIX systems this is not a problem.

  See also:

  - osErrorMsg proc
  - raiseOSError proc
  Source Edit

    proc raiseOSError(errorCode: OSErrorCode; additionalInfo = "") {.noinline,
        ...raises: [OSError], tags: [], forbids: [].}

  Raises an OSError exception.

  Read the description of the newOSError proc to learn how the exception object is created.

  Source Edit