Standard Library

os

os gives platform-independent access to files, environment variables, and process state. Use ReadFile/WriteFile when a file fits comfortably in memory, and Open/Create with streaming otherwise.

Examples

Skips open/close boilerplate for small files.

err := os.WriteFile("config.json", []byte("{\"env\":\"prod\"}"), 0644)
if err != nil {
    log.Fatal(err)
}

data, err := os.ReadFile("config.json")
if err != nil {
    log.Fatal(err)
}
fmt.Println(string(data))

Output

{"env":"prod"}

The idiomatic existence check.

func ensureDir(path string) error {
    _, err := os.Stat(path)
    if errors.Is(err, fs.ErrNotExist) {
        return os.MkdirAll(path, 0750)
    }
    return err
}

err := ensureDir("./data/logs")
fmt.Println(err)

Output

Copies bytes without loading the whole file into memory.

src, err := os.Open("input.csv")
if err != nil {
    log.Fatal(err)
}
defer src.Close()

dst, err := os.Create("input.csv.bak")
if err != nil {
    log.Fatal(err)
}
defer dst.Close()

written, err := io.Copy(dst, src)
if err != nil {
    log.Fatal(err)
}
fmt.Println("copied", written, "bytes")

Output

copied 843 bytes

Function	Description
Open(name string) (*File, error) `f, err := os.Open("a.txt")`	Check err, then defer f.Close().
Input `name`, the path to an existing file. Output An open `*os.File` handle, read-only, and an `error`. Use when You want to stream the file rather than load it, with `bufio.Scanner` or `io.Copy`. Call `Close` on the handle, normally `defer` f.Close() on the line after the error check. Equivalent to `os.OpenFile(name, os.O_RDONLY, 0)`
Create(name string) (*File, error) `f, err := os.Create("a.txt")`	Truncates if it exists. defer f.Close().
Input `name`, the path to create. Output An open `*os.File` handle, read-write, and an `error`. Behavior Creates the file when it is missing. Truncates it to zero length when it already exists. Equivalent to `os.OpenFile(name, os.O_RDWR\|os.O_CREATE\|os.O_TRUNC, 0666)`
OpenFile(name string, flag int, perm FileMode) (*File, error) `f, err := os.OpenFile(n, os.O_APPEND, 0644)`	Like Open/Create, with explicit flags.
Input `name`, the path. `flag`, one or more `O_` constants combined with `\|`. `perm`, the permission bits, used only when the file gets created. Output An open `*os.File` handle and an `error`. Use when `Open` and `Create` do not cover the case, most often appending with `O_APPEND`.
ReadFile(name string) ([]byte, error) `data, err := os.ReadFile("a.txt")`	Whole file in memory. Check err first.
Input `name`, the path to the file. Output The entire contents as `[]byte`, and an `error`. Behavior Opens and closes the file itself. The whole file is held in memory before it returns. Use when The file is small enough to fit comfortably in memory, such as config. Past that, stream it with `bufio.Scanner`.
WriteFile(name string, data []byte, perm FileMode) error `err := os.WriteFile("a.txt", b, 0644)`	Error only, the write already happened.
Input `name`, the path. `data`, the bytes to write. `perm`, the permission bits, for example `0644`. Output An `error`, non-nil on failure. Behavior Creates the file when it is missing. Truncates and overwrites it when it exists. Use when The file should end up holding exactly these bytes. Appending needs `OpenFile` with `O_APPEND`.
Stat(name string) (FileInfo, error) `info, err := os.Stat("a.txt")`	info.Size(), info.IsDir() once err is nil.
Input `name`, the path to inspect. Output A `FileInfo` carrying size, mode, and modification time, and an `error`. Behavior A missing path returns an error wrapping `os.ErrNotExist`. Test it with `errors.Is` or `os.IsNotExist`.
Mkdir(name string, perm FileMode) error `err := os.Mkdir("logs", 0750)`	Fails if the parent doesn't exist.
Input `name`, the directory to create. `perm`, its permission bits. Output An `error`, non-nil on failure. Behavior Creates exactly one level. Fails when the parent is missing, and fails when the directory already exists.
MkdirAll(path string, perm FileMode) error `err := os.MkdirAll("a/b/c", 0750)`	Creates parents too. Safe if it exists.
Input `path`, the directory to create. `perm`, the permission bits applied to any level it creates. Output An `error`, non-nil on failure. Behavior Creates every missing parent along the path. Returns nil when the path already exists.
Remove(name string) error `err := os.Remove("a.txt")`	Deletes one file or empty dir.
Input `name`, the file or empty directory to delete. Output An `error`, non-nil on failure. Behavior Deletes one entry. Fails on a directory that still has anything in it.
RemoveAll(path string) error `err := os.RemoveAll("tmp/")`	Deletes the path and everything under it.
Input `path`, the file or directory tree to delete. Output An `error`, non-nil on failure. Behavior Deletes the path and everything beneath it. Returns nil when the path was already absent.
ReadDir(name string) ([]DirEntry, error) `entries, err := os.ReadDir(".")`	Range over the result, call entry.Name().
Input `name`, the directory to list. Output A `[]DirEntry` sorted by filename, and an `error`. Behavior Reads one level. Walking a whole tree is `filepath.WalkDir`.
Getenv(key string) string `port := os.Getenv("PORT")`	Empty string if unset. No error.
Input `key`, the environment variable name. Output Its value as a `string`. Behavior An unset variable and a variable set to the empty string both return `""`. Use `LookupEnv` to tell them apart.
LookupEnv(key string) (string, bool) `v, ok := os.LookupEnv("PORT")`	Check the bool, not the string.
Input `key`, the environment variable name. Output Its value, and a `bool` reporting whether the variable is set at all.
Exit(code int) `os.Exit(1)`	Deferred calls never run.
Input `code`, the process exit status. Zero means success. Output Nothing. The call does not return. Behavior Stops the process immediately. Deferred calls do not run, and buffered writers do not flush.
Args []string `name := os.Args[1]`	Package var. Args[0] is the binary path.
Output A `[]string` of the command-line arguments. Behavior `Args[0]` is the path the binary was invoked as. The real arguments start at `Args[1]`.

bufio Wraps os.Open/os.Create for buffered reads and writes.io.Reader / io.Writer *os.File implements both interfaces directly.errors errors.Is(err, fs.ErrNotExist) is the standard existence check.

Previous net/http Next Topic path

os

Examples

Related