popen

Documentation

Index

• type Command
  • func (c *Command) Run(ctx context.Context) (stdout, stderr string, err error)

Types

type Command

type Command struct {
	// Directory if specified will be used as the working directory while
	// running the command, instead of the current working directory.
	Directory string

	// Command is the either the name of the command to execute, or its full
	// path.
	Command string

	// Arguments is the list of arguments to pass to the command. They are
	// passed as is, without any shell expansion.
	Arguments []string

	// Env is an optional list of environment variables formatted as
	// 'ENV=VALUE'. If the same environment is defined multiple time, only the
	// leater definition is retained.
	Env []string

	// OverwriteEnv prevents the target command from inheriting the current
	// process environment
	OverwriteEnv bool

	// DiscardStdout causes the stdout stream of the child process to not be
	// captured or returned as stdout.
	DiscardStdout bool

	// WriteStdoutToFile if not empty causes the stdout stream of the command to
	// be written to the specified file, instead of being captured into Stdout.
	WriteStdoutToFile string

	// StdoutReader if specified is expected to read the content of the command
	// stdout stream from w. If it returns an error, the command is aborted.
	StdoutReader func(r io.Reader) error

	// DiscardStderr causes the stderr stream of the child process to not be
	// captured or returned as stderr.
	DiscardStderr bool

	// WriteStderrToFile if not empty causes the stderr stream of the command to
	// be written to the specified file, instead of being captured into Stderr.
	WriteStderrToFile string

	// StderrReader if specified is expected to read the content of the command
	// stderr stream from w. If it returns an error, the command is aborted.
	StderrReader func(r io.Reader) error

	// ShutdownGracePeriod, if specified, changes the context handling
	// mechanism. By default, if the context becomes done before the command
	// completes, the child process is killed. If ShutdownGracePeriod is
	// non-zero, the child process is sent a first signal for graceful shutdown
	// (SIGINT by default), and is only killed if it has not exited by the end
	// of the grace period. This field is ignored on Windows which does not
	// implement unix signals.
	ShutdownGracePeriod time.Duration

	// ShutdownSignal is the initial signal sent to the child process when the
	// context becomes done before the command completes, if
	// `ShutdownGracePeriod` is non-zero. It defaults to syscall.SIGINT if not
	// set explicitly. This field is ignored on Windows which does not implement
	// unix signals.
	ShutdownSignal syscall.Signal

	// NoProcessGroup when true prevents the command for create a separate
	// process group for the child process. By default the child process is
	// created in its own process group, and signals are sent to the whole group
	// -- this is similar to ctrl-C in a terminal, which sends a SIGINT to the
	// whole process group. Note that when using NoProcessGroup, Run() can block
	// forever even when the context is canceled or timedout, if a grandchild
	// process keeps running after the child process is killed;
	// os.Process.Wait() will keep waiting for all descendants to exit. This
	// field is ignored on Windows which does not implement unix signals.
	NoProcessGroup bool
}

Command is an additional layer of abstraction over exec.Command aimed at simplifying common uses where the output of the process is captured or redirected. Unlike exec.Command, all the details of the command to run and what to do with its outputs are captured in public fields of the `Command` structure. The output streams, stdout and stderr, can be returned as a string, redirected to a file or stream-processed through an `io.Reader`.

Except for `StdoutReader` and `StderrReader` which are most likely stateful, the command object is stateless and can potentially be `Run()` multiple times, concurrently.

func (*Command) Run

func (c *Command) Run(ctx context.Context) (stdout, stderr string, err error)

Run executes the command as specified and returns the captured content of stdout and stderr if not discarded. If the process is executed successfully but returns a non-zero exit status, the returned error is an exec.ExitError that contains the actual status code.