tur/io-error
IoError, the one error type of the fs / io / process surface.
An IoError carries the errno of a failed OS call. errno is a genuine machine integer, but it is wrapped so a signature reading (Result nil IoError) says what it means, and so the predicates below replace comparing against magic constants. Every fallible function in stdlib/fs.tur, stdlib/io.tur and stdlib/process.tur returns (Result T IoError); inline-C bodies build the err side with tur_err_int(errno).
Since: stdlib-os-surface P1
IoError
(defopaque IoError :int)
io-error/of-code
(io-error/of-code [code :int] :IoError)
wrap a raw errno value as an IoError.
| code | an errno value (e.g. from a C library you call yourself) |
The IoError carrying code.
(io-error/not-found? (io-error/of-code 2)) ; => true on POSIX (ENOENT)
Since: stdlib-os-surface P1
io-error/last
(io-error/last :IoError)
the IoError for the calling thread's current errno.
errno, wrapped. Only meaningful right after a failed OS call.
(io-error/last)
Since: stdlib-os-surface P1
io-error/code
(io-error/code [e :IoError] :int)
the raw errno an IoError carries, for interop.
| e | an IoError |
The errno value as an int.
(io-error/code e) ; => 2
Since: stdlib-os-surface P1
io-error/message
(io-error/message [e :IoError] :cstr)
the human-readable description of an IoError.
| e | an IoError |
strerror(3) text, e.g. "No such file or directory". Static storage: do not free it, and copy it before the next io-error/message call if you need to keep it.
(println (io-error/message e)) ; prints "No such file or directory"
Since: stdlib-os-surface P1
io-error/not-found?
(io-error/not-found? [e :IoError] :bool)
true when the error is "no such file or directory".
| e | an IoError |
true for ENOENT.
(io-error/not-found? e) ; => true
Since: stdlib-os-surface P1
io-error/exists?
(io-error/exists? [e :IoError] :bool)
true when the error is "already exists".
| e | an IoError |
true for EEXIST.
(io-error/exists? e) ; => true after fs/mkdir on an existing dir
Since: stdlib-os-surface P1
io-error/permission?
(io-error/permission? [e :IoError] :bool)
true when the error is a permission failure.
| e | an IoError |
true for EACCES or EPERM.
(io-error/permission? e) ; => true
Since: stdlib-os-surface P1
io-error/interrupted?
(io-error/interrupted? [e :IoError] :bool)
true when a signal cut a blocking call short.
A signal caught with signal/handle (stdlib/process.tur) wakes a call that was waiting -- net/accept, net/recv -- with this error rather than letting it wait on, so the program can look at the signal and decide. Nothing was done; calling again resumes the wait.
| e | an IoError |
true for EINTR.
(io-error/interrupted? e) ; => true
Since: stdlib-os-surface P3
io-error/connection-refused?
(io-error/connection-refused? [e :IoError] :bool)
true when nothing was listening.
What net/tcp-connect answers for a port with no server behind it -- the error a client retrying while its server starts up waits out.
| e | an IoError |
true for ECONNREFUSED (on Windows, also the WSAECONNREFUSED that stdlib/net.tur maps onto it).
(io-error/connection-refused? e) ; => true
Since: stdlib-os-surface P3
io-error/ok-unit
(io-error/ok-unit :(Result nil IoError))
(Ok nil) as a (Result nil IoError).
Written before Turmeric code could spell (Ok nil) itself; since 2026-10-07 (Ok nil) builds the same value (docs/archive/ok-nil-unconstructible-in-turmeric.md). Kept for the functions that already return through it.
(Ok nil).
(io-error/ok-unit) ; => (Ok nil)
Since: stdlib-os-surface P2