Executing External Commands in Go

Sometimes we need to invoke operating system commands from our code. Most languages have APIs for this - Java has Runtime.exec(), Python has subprocess and Go has the os/exec package. This post briefly explores the Go API.

The APIs are part of the exec/os package. The Cmd abstraction encapsulates a command object, where various tweaks can be done including setting the standard output and error streams.

Simple execution of a command is very easy. However, if one wants finer control over the execution, including control over streams and the correct exit code, maybe when it's to be used in a framework or a library, the code becomes slightly more involved.

Creating the Cmd object is straighforward

cmd := exec.Command(binaryName, args...)

The output and error streams can be redirected as follows

stdout := &bytes.Buffer {}
 stderr := &bytes.Buffer {}
 cmd.Stdout = stdout
cmd.Stderr = stderr

Once the command has been executed, it returns an Error object if the execution failed.

err := cmd.Run()

The command execution can fail for various reasons - it might not have been a valid command, it might have exited with an error code or their might have been IO errors. We need to detect these cases so that the caller of the API gets the correct response. The Go source file exec.go documents the error types that can occur.An unsuccessful exit by a command. The ExitError object also has a "subset of the standard error output from the Cmd.Output method if standard error was not otherwise being collected." <quote docs>.

exec.Error

One of the cases where this Error can be returned is when the command could not be located. When the Command struct instance is created, it calls the LookPath method to locate the binary if the binaryName argument does not have path separators, which can return one of these Error instances when the executable could not be located. The actual implementation depends on the OS.

We can switch on the Error type

switch err.(type) {
   case *exec.ExitError:
    e := err.(*exec.ExitError)
    if status, ok := e.Sys().(syscall.WaitStatus); ok {
     exitcode = status.ExitStatus()
    }
   case *exec.Error:
    e := err.(*exec.Error)
    stderr.WriteString(e.Err.Error())
   default:
    panic("Unknown err type: " + reflect.TypeOf(err).String())

  }

If it's ExitError, we need to query the OS specific implementations using the Sys interface. The Unix implementation is syscall.WaitStatus.

if the err instance is nil, the command execution succeeded and we can get the exit code from the Cmd itself.

if status, ok := cmd.ProcessState.Sys().(syscall.WaitStatus); ok {
	exitcode = status.ExitStatus()
}

The complete source code is here.