8.5 os — Specification¶

A formal reference for the os, os/exec, and os/signal surface covered in this leaf. Field-by-field tables, signal numbers per platform, lifecycle states, error sentinels. Use the package docs on pkg.go.dev for the authoritative source; this is a cross-reference for the patterns covered in earlier files.

1. Process functions¶

2. Environment functions¶

Notes: - Setenv/Unsetenv are process-global. Mutex protect if multiple goroutines call them concurrently. - Environ() returns a copy. Mutating the slice doesn't change the environment; use Setenv.

3. Process management¶

4. os.ProcAttr fields¶

type ProcAttr struct {
    Dir   string         // child's working directory
    Env   []string       // child's environment; nil = inherit
    Files []*os.File     // child's FDs; index = FD number
    Sys   *syscall.SysProcAttr // OS-specific
}

5. *os.ProcessState accessors¶

6. *exec.Cmd field reference¶

type Cmd struct {
    Path        string          // resolved binary path
    Args        []string        // including Args[0] (the program name)
    Env         []string        // nil = inherit from parent
    Dir         string          // working directory
    Stdin       io.Reader       // nil = /dev/null
    Stdout      io.Writer       // nil = /dev/null
    Stderr      io.Writer       // nil = /dev/null
    ExtraFiles  []*os.File      // FDs 3, 4, ... in the child
    SysProcAttr *syscall.SysProcAttr

    Process     *os.Process     // set after Start
    ProcessState *os.ProcessState // set after Wait

    Err         error           // populated by NewCmd-time errors

    Cancel      func() error    // 1.20+: called when context cancels
    WaitDelay   time.Duration   // 1.20+: hard timeout after Cancel

    // Internal: fd0, fd1, fd2 wiring goroutines
}

7. *exec.Cmd lifecycle states¶

[Construct] ── exec.Command(...) ─────▶ Cmd struct, no syscall
       │
[Started] ── cmd.Start() ─────────────▶ fork+exec; pipes ready
       │                                Cmd.Process != nil
       ▼
[Running] ── (child runs; pipes flow)
       │
[Waited] ── cmd.Wait() ───────────────▶ child reaped; goroutines done
                                        Cmd.ProcessState != nil

A Cmd is single-use: after Wait, build a new Cmd for the next invocation. Run, Output, CombinedOutput all internally do Start then Wait.

8. *exec.Cmd runner methods¶

9. os/signal functions¶

Channel rules: - The channel must be buffered (size ≥ 1). Notify does a non- blocking send; if the buffer is full, the signal is dropped. - A single channel can be registered for multiple signals. - Stop is safe to call multiple times.

10. Common signals (Unix)¶

Numbers vary across architectures (Linux MIPS, Alpha, etc.). Use the named constants from syscall rather than literals. Some constants (SIGUSR1, SIGCHLD) are only present on Unix builds — guard with build tags.

11. Signals and Windows¶

Windows has only a small set of signals:

Windows does not have SIGUSR1, SIGHUP, SIGSTOP, etc. Don't import those constants in Windows-targeted code without //go:build unix.

12. syscall.SysProcAttr (Linux subset)¶

type SysProcAttr struct {
    Chroot     string
    Credential *Credential
    Ptrace     bool
    Setsid     bool          // create new session
    Setpgid    bool          // create new process group
    Pgid       int           // group ID; 0 = use child's PID
    Setctty    bool          // set controlling tty
    Noctty     bool          // detach from controlling tty
    Ctty       int           // tty FD
    Foreground bool
    Pdeathsig  Signal        // signal sent if parent dies
    Cloneflags uintptr       // CLONE_NEWNS, CLONE_NEWPID, ...
    Unshareflags uintptr
    UidMappings []SysProcIDMap
    GidMappings []SysProcIDMap
    GidMappingsEnableSetgroups bool
    AmbientCaps []uintptr    // ambient capabilities
    UseCgroupFD bool
    CgroupFD    int
}

Many fields are Linux-specific. Cloneflags is the gateway to namespaces (i.e., the kernel API containers are built on).

13. syscall.SysProcAttr (Windows subset)¶

type SysProcAttr struct {
    HideWindow         bool
    CmdLine            string  // raw command line
    CreationFlags      uint32  // CREATE_NEW_PROCESS_GROUP, etc.
    Token              syscall.Token
    ProcessAttributes  *SecurityAttributes
    ThreadAttributes   *SecurityAttributes
    NoInheritHandles   bool
    ParentProcess      syscall.Handle
    AdditionalInheritedHandles []syscall.Handle
}

Windows has its own model: process groups exist but mean something different; signals are mostly synthesized.

14. Error sentinels¶

Use errors.Is(err, sentinel) rather than direct comparison; many errors are wrapped in *os.PathError or *exec.Error.

15. Error types¶

All implement Unwrap(); errors.Is/As work as expected.

16. Standard streams¶

Closing them is generally a bad idea; the runtime and other goroutines may write to them.

17. os/exec lookup precedence¶

1. If name contains a path separator (/ or \), use it directly as a path. No PATH lookup.
2. Otherwise, search each directory in $PATH (Unix) or %PATH% (Windows) for an executable named name.
3. On Windows, also search for name.exe, name.bat, name.cmd, etc. according to %PATHEXT%.
4. Since Go 1.19, if step 2 resolves to a file in the current directory via a relative PATH entry ("", "."), LookPath returns exec.ErrDot. To opt in, prepend ./ to the name.

18. runtime constants relevant to os¶

19. Cross-references¶

• [io and File Handling](../01-io-and-file-handling/specification.md) for*os.Fileoperations andfs.FileMode` semantics.
• flag for os.Args parsing.
• time for context.WithTimeout shutdown bounds.