exec package - os/exec - Go Packages (original) (raw)

Package exec runs external commands. It wraps os.StartProcess to make it easier to remap stdin and stdout, connect I/O with pipes, and do other adjustments.

Unlike the "system" library call from C and other languages, the os/exec package intentionally does not invoke the system shell and does not expand any glob patterns or handle other expansions, pipelines, or redirections typically done by shells. The package behaves more like C's "exec" family of functions. To expand glob patterns, either call the shell directly, taking care to escape any dangerous input, or use the path/filepath package's Glob function. To expand environment variables, use package os's ExpandEnv.

Note that the examples in this package assume a Unix system. They may not run on Windows, and they do not run in the Go Playground used by go.dev and pkg.go.dev.

Executables in the current directory

The functions Command and LookPath look for a program in the directories listed in the current path, following the conventions of the host operating system. Operating systems have for decades included the current directory in this search, sometimes implicitly and sometimes configured explicitly that way by default. Modern practice is that including the current directory is usually unexpected and often leads to security problems.

To avoid those security problems, as of Go 1.19, this package will not resolve a program using an implicit or explicit path entry relative to the current directory. That is, if you run LookPath("go"), it will not successfully return ./go on Unix nor .\go.exe on Windows, no matter how the path is configured. Instead, if the usual path algorithms would result in that answer, these functions return an error err satisfying errors.Is(err, ErrDot).

For example, consider these two program snippets:

path, err := exec.LookPath("prog") if err != nil { log.Fatal(err) } use(path)

and

cmd := exec.Command("prog") if err := cmd.Run(); err != nil { log.Fatal(err) }

These will not find and run ./prog or .\prog.exe, no matter how the current path is configured.

Code that always wants to run a program from the current directory can be rewritten to say "./prog" instead of "prog".

Code that insists on including results from relative path entries can instead override the error using an errors.Is check:

path, err := exec.LookPath("prog") if errors.Is(err, exec.ErrDot) { err = nil } if err != nil { log.Fatal(err) } use(path)

and

cmd := exec.Command("prog") if errors.Is(cmd.Err, exec.ErrDot) { cmd.Err = nil } if err := cmd.Run(); err != nil { log.Fatal(err) }

Setting the environment variable GODEBUG=execerrdot=0 disables generation of ErrDot entirely, temporarily restoring the pre-Go 1.19 behavior for programs that are unable to apply more targeted fixes. A future version of Go may remove support for this variable.

Before adding such overrides, make sure you understand the security implications of doing so. See https://go.dev/blog/path-security for more information.

This section is empty.

ErrDot indicates that a path lookup resolved to an executable in the current directory due to ‘.’ being in the path, either implicitly or explicitly. See the package documentation for details.

Note that functions in this package do not return ErrDot directly. Code should use errors.Is(err, ErrDot), not err == ErrDot, to test whether a returned error err is due to this condition.

ErrNotFound is the error resulting if a path search failed to find an executable file.

ErrWaitDelay is returned by Cmd.Wait if the process exits with a successful status code but its output pipes are not closed before the command's WaitDelay expires.

LookPath searches for an executable named file in the directories named by the PATH environment variable. If file contains a slash, it is tried directly and the PATH is not consulted. Otherwise, on success, the result is an absolute path.

In older versions of Go, LookPath could return a path relative to the current directory. As of Go 1.19, LookPath will instead return that path along with an error satisfyingerrors.Is(err, ErrDot). See the package documentation for more details.

package main

import ( "fmt" "log" "os/exec" )

func main() { path, err := exec.LookPath("fortune") if err != nil { log.Fatal("installing fortune is in your future") } fmt.Printf("fortune is available at %s\n", path) }

Cmd represents an external command being prepared or run.

A Cmd cannot be reused after calling its Cmd.Run, Cmd.Output or Cmd.CombinedOutputmethods.

func Command

Command returns the Cmd struct to execute the named program with the given arguments.

It sets only the Path and Args in the returned structure.

If name contains no path separators, Command uses LookPath to resolve name to a complete path if possible. Otherwise it uses name directly as Path.

The returned Cmd's Args field is constructed from the command name followed by the elements of arg, so arg should not include the command name itself. For example, Command("echo", "hello"). Args[0] is always name, not the possibly resolved Path.

On Windows, processes receive the whole command line as a single string and do their own parsing. Command combines and quotes Args into a command line string with an algorithm compatible with applications using CommandLineToArgvW (which is the most common way). Notable exceptions are msiexec.exe and cmd.exe (and thus, all batch files), which have a different unquoting algorithm. In these or other similar cases, you can do the quoting yourself and provide the full command line in SysProcAttr.CmdLine, leaving Args empty.

package main

import ( "fmt" "log" "os/exec" "strings" )

func main() { cmd := exec.Command("tr", "a-z", "A-Z") cmd.Stdin = strings.NewReader("some input") var out strings.Builder cmd.Stdout = &out err := cmd.Run() if err != nil { log.Fatal(err) } fmt.Printf("in all caps: %q\n", out.String()) }

package main

import ( "log" "os" "os/exec" )

func main() { cmd := exec.Command("prog") cmd.Env = append(os.Environ(), "FOO=duplicate_value", // ignored "FOO=actual_value", // this value is used ) if err := cmd.Run(); err != nil { log.Fatal(err) } }

func CommandContext added in go1.7

CommandContext is like Command but includes a context.

The provided context is used to interrupt the process (by calling cmd.Cancel or os.Process.Kill) if the context becomes done before the command completes on its own.

CommandContext sets the command's Cancel function to invoke the Kill method on its Process, and leaves its WaitDelay unset. The caller may change the cancellation behavior by modifying those fields before starting the command.

package main

import ( "context" "os/exec" "time" )

func main() { ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond) defer cancel()

if err := exec.CommandContext(ctx, "sleep", "5").Run(); err != nil {
    // This will fail after 100 milliseconds. The 5 second sleep
    // will be interrupted.
}

}

CombinedOutput runs the command and returns its combined standard output and standard error.

package main

import ( "fmt" "log" "os/exec" )

func main() { cmd := exec.Command("sh", "-c", "echo stdout; echo 1>&2 stderr") stdoutStderr, err := cmd.CombinedOutput() if err != nil { log.Fatal(err) } fmt.Printf("%s\n", stdoutStderr) }

Environ returns a copy of the environment in which the command would be run as it is currently configured.

package main

import ( "fmt" "log" "os/exec" )

func main() { cmd := exec.Command("pwd")

// Set Dir before calling cmd.Environ so that it will include an
// updated PWD variable (on platforms where that is used).
cmd.Dir = ".."
cmd.Env = append(cmd.Environ(), "POSIXLY_CORRECT=1")

out, err := cmd.Output()
if err != nil {
    log.Fatal(err)
}
fmt.Printf("%s\n", out)

}

Output runs the command and returns its standard output. Any returned error will usually be of type *ExitError. If c.Stderr was nil and the returned error is of type*ExitError, Output populates the Stderr field of the returned error.

package main

import ( "fmt" "log" "os/exec" )

func main() { out, err := exec.Command("date").Output() if err != nil { log.Fatal(err) } fmt.Printf("The date is %s\n", out) }

Run starts the specified command and waits for it to complete.

The returned error is nil if the command runs, has no problems copying stdin, stdout, and stderr, and exits with a zero exit status.

If the command starts but does not complete successfully, the error is of type *ExitError. Other error types may be returned for other situations.

If the calling goroutine has locked the operating system thread with runtime.LockOSThread and modified any inheritable OS-level thread state (for example, Linux or Plan 9 name spaces), the new process will inherit the caller's thread state.

package main

import ( "log" "os/exec" )

func main() { cmd := exec.Command("sleep", "1") log.Printf("Running command and waiting for it to finish...") err := cmd.Run() log.Printf("Command finished with error: %v", err) }

Start starts the specified command but does not wait for it to complete.

If Start returns successfully, the c.Process field will be set.

After a successful call to Start the Cmd.Wait method must be called in order to release associated system resources.

package main

import ( "log" "os/exec" )

func main() { cmd := exec.Command("sleep", "5") err := cmd.Start() if err != nil { log.Fatal(err) } log.Printf("Waiting for command to finish...") err = cmd.Wait() log.Printf("Command finished with error: %v", err) }

StderrPipe returns a pipe that will be connected to the command's standard error when the command starts.

Cmd.Wait will close the pipe after seeing the command exit, so most callers need not close the pipe themselves. It is thus incorrect to call Wait before all reads from the pipe have completed. For the same reason, it is incorrect to use Cmd.Run when using StderrPipe. See the StdoutPipe example for idiomatic usage.

package main

import ( "fmt" "io" "log" "os/exec" )

func main() { cmd := exec.Command("sh", "-c", "echo stdout; echo 1>&2 stderr") stderr, err := cmd.StderrPipe() if err != nil { log.Fatal(err) }

if err := cmd.Start(); err != nil {
    log.Fatal(err)
}

slurp, _ := io.ReadAll(stderr)
fmt.Printf("%s\n", slurp)

if err := cmd.Wait(); err != nil {
    log.Fatal(err)
}

}

StdinPipe returns a pipe that will be connected to the command's standard input when the command starts. The pipe will be closed automatically after Cmd.Wait sees the command exit. A caller need only call Close to force the pipe to close sooner. For example, if the command being run will not exit until standard input is closed, the caller must close the pipe.

package main

import ( "fmt" "io" "log" "os/exec" )

func main() { cmd := exec.Command("cat") stdin, err := cmd.StdinPipe() if err != nil { log.Fatal(err) }

go func() {
    defer stdin.Close()
    io.WriteString(stdin, "values written to stdin are passed to cmd's standard input")
}()

out, err := cmd.CombinedOutput()
if err != nil {
    log.Fatal(err)
}

fmt.Printf("%s\n", out)

}

StdoutPipe returns a pipe that will be connected to the command's standard output when the command starts.

Cmd.Wait will close the pipe after seeing the command exit, so most callers need not close the pipe themselves. It is thus incorrect to call Wait before all reads from the pipe have completed. For the same reason, it is incorrect to call Cmd.Run when using StdoutPipe. See the example for idiomatic usage.

package main

import ( "encoding/json" "fmt" "log" "os/exec" )

func main() { cmd := exec.Command("echo", "-n", {"Name": "Bob", "Age": 32}) stdout, err := cmd.StdoutPipe() if err != nil { log.Fatal(err) } if err := cmd.Start(); err != nil { log.Fatal(err) } var person struct { Name string Age int } if err := json.NewDecoder(stdout).Decode(&person); err != nil { log.Fatal(err) } if err := cmd.Wait(); err != nil { log.Fatal(err) } fmt.Printf("%s is %d years old\n", person.Name, person.Age) }

String returns a human-readable description of c. It is intended only for debugging. In particular, it is not suitable for use as input to a shell. The output of String may vary across Go releases.

Wait waits for the command to exit and waits for any copying to stdin or copying from stdout or stderr to complete.

The command must have been started by Cmd.Start.

The returned error is nil if the command runs, has no problems copying stdin, stdout, and stderr, and exits with a zero exit status.

If the command fails to run or doesn't complete successfully, the error is of type *ExitError. Other error types may be returned for I/O problems.

If any of c.Stdin, c.Stdout or c.Stderr are not an *os.File, Wait also waits for the respective I/O loop copying to or from the process to complete.

Wait releases any resources associated with the Cmd.

Error is returned by LookPath when it fails to classify a file as an executable.

An ExitError reports an unsuccessful exit by a command.