The os Package

Satisfies io.Reader, io.Writer, io.Closer, io.Seeker, io.ReaderAt, io.WriterAt, io.ReaderFrom, io.WriterTo, io.StringWriter

A handle is a reader, a writer, and a seeker at once, so anything in the standard library that takes one of those interfaces takes a file. Sync is the call that forces the bytes past the kernel's cache and onto the disk.

f, err := os.Create("notes.txt")
if err != nil {
    log.Fatal(err)
}
defer f.Close()

f.WriteString("first line\n")
f.Sync() // on disk, not just in the page cache

f.Seek(0, io.SeekStart)
info, _ := f.Stat()
fmt.Println(info.Name(), info.Size()) // notes.txt 11

Implemented by the unexported values os.Stat returns, plus every fs.FS implementation

Six methods and no fields, so everything comes through a call. Mode carries the permission bits and the type bits together, which is why Perm exists to mask the type off again.

info, err := os.Stat("notes.txt")
if err != nil {
    log.Fatal(err)
}

fmt.Println(info.Name(), info.Size(), info.IsDir()) // notes.txt 11 false
fmt.Println(info.Mode(), info.Mode().Perm())        // -rw-r--r-- -rw-r--r--
fmt.Println(info.ModTime().Format(time.RFC3339))

Implemented by the values os.ReadDir returns, plus every fs.FS implementation

The name and the type bits arrive with the listing itself, so testing IsDir costs nothing. Info is the one that goes back to the filesystem, which is why you call it after the filtering rather than before.

entries, err := os.ReadDir(".")
if err != nil {
    log.Fatal(err)
}

for _, e := range entries {
    if e.IsDir() {
        continue
    }
    info, err := e.Info() // the extra syscall, only where it is needed
    if err != nil {
        continue
    }
    fmt.Printf("%-20s %6d\n", e.Name(), info.Size())
}

Satisfies fmt.Stringer

One integer holding two unrelated things. Printing it gives the ls rendering, and %#o on the permission bits gives the octal you wrote in the first place.

mode := info.Mode()

fmt.Println(mode)                      // -rw-r--r--
fmt.Printf("%#o\n", mode.Perm())       // 0644
fmt.Println(mode.IsRegular(), mode.IsDir()) // true false

Every method takes a path and resolves it inside the directory, so a name that climbs out fails instead of succeeding somewhere it should not. This is the answer for any filename that came from a request.

root, err := os.OpenRoot("uploads")
if err != nil {
    log.Fatal(err)
}
defer root.Close()

root.WriteFile("ok.txt", []byte("safe"), 0644)

_, err = root.Open("../../etc/passwd")
fmt.Println("escape refused:", err != nil) // escape refused: true

A handle you signal and then wait on. Wait only works on a process you started yourself, which is why this goes through os/exec rather than FindProcess.

cmd := exec.Command("sleep", "30")
if err := cmd.Start(); err != nil {
    log.Fatal(err)
}

p := cmd.Process
fmt.Println("started", p.Pid)

p.Signal(syscall.SIGTERM)
state, err := p.Wait()

Satisfies fmt.Stringer

What Wait hands back once the process is gone. A signalled process reports an exit code of -1, so Exited is the check that separates "finished with a status" from "was killed".

state, err := p.Wait()
if err != nil {
    log.Fatal(err)
}

fmt.Println(state.Exited())   // false, it was signalled
fmt.Println(state.ExitCode()) // -1
fmt.Println(state)            // signal: terminated

Implemented by syscall.Signal on Unix, which is what os.Interrupt and os.Kill are

Signals arrive on a channel you register with signal.Notify. Give the channel a buffer of at least one, since a signal delivered while nothing is receiving is dropped.

ch := make(chan os.Signal, 1)
signal.Notify(ch, os.Interrupt, syscall.SIGTERM)

sig := <-ch
fmt.Println("got", sig) // got interrupt

signal.Stop(ch)

Satisfies error

errors.As unpacks the error into the struct, which is how you recover the path and the operation that failed. errors.Is answers the different question of what went wrong.

_, err := os.Open("nope/missing.txt")

var pe *os.PathError
if errors.As(err, &pe) {
    fmt.Println(pe.Op, pe.Path) // open nope/missing.txt
}

fmt.Println(errors.Is(err, fs.ErrNotExist)) // true