Raw syscall and x/sys

## What syscall.Errno is A Unix system call reports failure by handing back a small non-zero integer — the *errno*. Go models that integer directly: ```go type Errno uintptr ``` That is the whole type. It has a value-receiver `Error() string` method, so an `Errno` value *is* an `error` with no pointer and no allocation, and it is comparable with `==` like any integer. The named constants — `syscall.ENOENT`, `syscall.EACCES`, `syscall.EPERM`, `syscall.EEXIST`, `syscall.EINTR`, `syscall.EAGAIN` — are typed `Errno` values. Beyond `Error`, the type carries `Is(target error) bool`, `Temporary() bool` and `Timeout() bool`. Use the **named constant**, never the number. The name is portable across operating systems; the numeric value behind it is not, and a hard-coded `2` is a bug waiting for the first non-Linux build. ## Zero means success, and zero is not nil The generated low-level wrappers return the errno as an `Errno`, not as an `error`, precisely because zero means "no error": ```go var err error = syscall.Errno(0) fmt.Println(err == nil) // false ``` An interface value holds a (type, value) pair; assigning a zero `Errno` into an `error` makes the interface non-nil even though the errno says success. That is why hand-written wrappers check `if errno != 0 { return errno }` and return a literal `nil` otherwise. Getting this backwards produces a function that always looks like it failed. ## Where the errno actually reaches you The standard library almost never hands you a bare `Errno`. It wraps: - `os.Open`, `os.Stat`, `os.Remove` return `*os.PathError` — fields `Op`, `Path`, `Err`, where `Err` is the `Errno`. - `os.Rename`, `os.Link` return `*os.LinkError`. - Socket operations return `*net.OpError`, often wrapping `*os.SyscallError`, which wraps the `Errno`. So a direct comparison fails: ```go _, err := os.Open("/etc/does-not-exist") fmt.Println(err == syscall.ENOENT) // false: err is *os.PathError fmt.Println(errors.Is(err, syscall.ENOENT)) // true ``` `errors.Is` unwraps repeatedly, comparing at each level and consulting any `Is` method it finds, which is exactly what a layered error tree needs. A type assertion — `err.(syscall.Errno)` — fails for the same reason the `==` does: the dynamic type is the wrapper, not the errno. ## The portable check `Errno.Is` maps a handful of values onto the operating-system-independent sentinels, so `errors.Is(err, os.ErrNotExist)` matches ENOENT, `os.ErrPermission` matches EACCES and EPERM, and `os.ErrExist` matches EEXIST. Prefer those sentinels when the *category* is what you care about; drop to `syscall.ENOTEMPTY`, `syscall.ENOSPC`, `syscall.EMFILE` or `syscall.EINTR` when you need the specific kernel condition, because no portable sentinel exists for them. ## Why string matching is the wrong instinct Engineers arriving from languages where errors are strings reach for `strings.Contains(err.Error(), "no such file")`. That breaks in three ways: the wording differs between operating systems, it silently matches a path that happens to contain the phrase, and it couples your control flow to a message the runtime is free to reword. `errors.Is` is a value comparison through a documented chain; the string is a human-readable rendering of it. ## In a file-tree indexer A daemon walking directories hits errnos constantly, and the branch is usually three-way: ENOENT because a file was deleted between the directory read and the `stat` (skip it, this is normal), EACCES because a subtree is not readable by this user (log once and prune), and anything else (surface it). Writing that as three `errors.Is` checks against named constants keeps the walk readable and keeps the test honest, because a test can construct `&os.PathError{Err: syscall.EACCES}` and assert the walker's decision without needing a real unreadable directory on the CI machine. ## Checklist - Compare with `errors.Is`, not `==`, unless you produced the error yourself one line earlier. - Use named constants; never the numeric value. - Treat `Errno(0)` as success and return a real `nil`. - Reach for `os.ErrNotExist` / `os.ErrPermission` when the category suffices, the raw errno when it does not.