pexec

Documentation

Overview

Package pexec provides streaming, context-cancelable system command execution

Index

• Constants
• Variables
• func ExecBlocking(stdin []byte, wantStdout Stdouts, wantStderr Stderrs, ctx context.Context, ...) (stdout, stderr *bytes.Buffer, err error)
• func ExecStream(stdin io.Reader, stdout io.WriteCloser, stderr io.WriteCloser, ...) (statusCode int, isCancel bool, err error)
• func ExecStreamFull(stdin io.Reader, stdout io.WriteCloser, stderr io.WriteCloser, env []string, ...) (statusCode int, isCancel bool, err error)
• func ExitError(err error) (hasStatusCode bool, statusCode int, signal unix.Signal, stderr []byte)
• type ExitErrorData
  • func NewExitErrorData(err error, stderr ...[]byte) (exitErrorData *ExitErrorData)
  • func (e *ExitErrorData) AddStderr(err error) (err2 error)
  • func (e *ExitErrorData) Error() (exitErrorMessage string)
  • func (e *ExitErrorData) ExitErrorString(includeStderr ...bool) (errS string)
  • func (e *ExitErrorData) IsExitError() (isExitError bool)
  • func (e *ExitErrorData) IsSignalKill() (isSignalKill bool)
  • func (e *ExitErrorData) IsStatusCode1() (is1 bool)
• type StartCallback
• type Stderrs
• type Stdouts

Constants

const (
	// [ExitErrorData.ExitErrorString] should include standard error output
	ExitErrorIncludeStderr = true
	// status code 1, which in POSIX means a general error
	StatusCode1 = 1
)

const (
	TerminatedBySignal = -1
)

Variables

var ErrArgsListEmpty = errors.New("args list empty")

var NoStdin []byte

Functions

func ExecBlocking

func ExecBlocking(stdin []byte, wantStdout Stdouts, wantStderr Stderrs, ctx context.Context, args ...string) (stdout, stderr *bytes.Buffer, err error)

ExecBlocking executes a system command with independent control over stdin stdout stderr

• if stdin is nil, no stdin is provided to command
• if wantStdout is true, stdout contains any command output, if false stdout nil
• if wantStderr is true, stderr contains any command error output, if false stderr nil

func ExecStream

func ExecStream(stdin io.Reader, stdout io.WriteCloser, stderr io.WriteCloser,
	ctx context.Context, args ...string) (statusCode int, isCancel bool, err error)

ExecStream executes a system command using the exec.Cmd type and flexible streaming.

• ExecStream blocks during command execution
• ExecStream returns any error occurring during launch or execution including errors in copy threads
• successful exit is: statusCode == 0, isCancel == false, err == nil
• statusCode may be set by the process but is otherwise:
• — 0 successful exit
• — -1 process was killed by signal such as ^C or SIGTERM
• context cancel exit is: statusCode == -1, isCancel == true, err == nil
• failure exit is: statusCode != 0, isCancel == false, err != nil
• —
• args is the command followed by arguments.
• args[0] must specify an executable in the file system. env.PATH is used to resolve the command executable
• if stdin stdout or stderr are nil, the are /dev/null Additional threads are used to copy data when stdin stdout or stderr are non-nil
• os.Stdin os.Stdout os.Stderr can be provided
• for stdout and stderr pio has usable types:
• — pio.NewWriteCloserToString
• — pio.NewWriteCloserToChan
• — pio.NewWriteCloserToChanLine
• — pio.NewReadWriteCloserSlice
• any stream provided is not closed. However, upon return from ExecStream all i/o operations have completed and streams may be closed as the case may be
• ctx is used to kill the process (by calling os.Process.Kill) if the context becomes done before the command completes on its own
• use ExecStream with parl.EchoModerator
• if system commands slow down or lock-up, too many (dozens) invoking goroutines may cause increased memory consumption, thrashing or exhaust of file handles, ie. an uncontrollable host state

func ExecStreamFull

func ExecStreamFull(stdin io.Reader, stdout io.WriteCloser, stderr io.WriteCloser,
	env []string, ctx context.Context, startCallback StartCallback, extraFiles []*os.File,
	args ...string) (statusCode int, isCancel bool, err error)

ExecStreamFull executes a system command using the exec.Cmd type and flexible streaming.

• ExecStreamFull blocks during command execution
• ExecStreamFull returns any error occurring during launch or execution including errors in copy threads
• successful exit is: statusCode == 0, isCancel == false, err == nil
• statusCode may be set by the process but is otherwise:
• — 0 successful exit
• — -1 process was killed by signal such as ^C or SIGTERM
• context cancel exit is: statusCode == -1, isCancel == true, err == nil
• failure exit is: statusCode != 0, isCancel == false, err != nil
• —
• args is the command followed by arguments.
• args[0] must specify an executable in the file system. env.PATH is used to resolve the command executable
• if stdin stdout or stderr are nil, the are /dev/null Additional threads are used to copy data when stdin stdout or stderr are non-nil
• os.Stdin os.Stdout os.Stderr can be provided
• for stdout and stderr pio has usable types:
• — pio.NewWriteCloserToString
• — pio.NewWriteCloserToChan
• — pio.NewWriteCloserToChanLine
• — pio.NewReadWriteCloserSlice
• any stream provided is not closed. However, upon return from ExecStream all i/o operations have completed and streams may be closed as the case may be
• ctx is used to kill the process (by calling os.Process.Kill) if the context becomes done before the command completes on its own
• startCallback is invoked immediately after cmd.Exec.Start returns with its result. To not use a callback, set startCallback to nil
• If env is nil, the new process uses the current process’ environment
• use ExecStreamFull with parl.EchoModerator
• if system commands slow down or lock-up, too many (dozens) invoking goroutines may cause increased memory consumption, thrashing or exhaust of file handles, ie. an uncontrollable host state

func ExitError

func ExitError(err error) (hasStatusCode bool, statusCode int, signal unix.Signal, stderr []byte)

ExitError returns information on why the exec.Cmd.Start process terminated

• if hasStatusCode is true, the process terminated with a status code
• if hasStatusCode is false, exec.Cmd.Start failed prior to launch
• if StatusCode has value -1 or pexec.TerminatedBySignal, the process terminated due to the signal signal. Common signals are:
• — unix.SIGINT from ^C
• — unix.SIGKILL from context termination
• — unix.SIGTERM from operating-system process-termination

Types

type ExitErrorData

type ExitErrorData struct {
	// the original error
	Err error
	// Err interpreted as ExitError, possibly nil
	ExitErr *exec.ExitError
	// status code in ExitError, possibly 0
	StatusCode int
	// signal in ExitError, possibly 0
	Signal unix.Signal
	// stderr in ExitError or from argument, possibly nil
	Stderr []byte
}

ExitErrorData provides additional detail on pexec.ExitError values

func NewExitErrorData

func NewExitErrorData(err error, stderr ...[]byte) (exitErrorData *ExitErrorData)

NewExitErrorData returns parse-once data on a possible ExitError

• if ExitErr field is nil or IsExitError method returns false, err does not contain an ExitError
• the returned value is an error implementation

func (*ExitErrorData) AddStderr

func (e *ExitErrorData) AddStderr(err error) (err2 error)

AddStderr adds standard error output at the end of the error message for err. Also ensures stack trace.

• ExitError has standard error if the Output method was used
• NewExitErrorData can also have been provided stderr

func (*ExitErrorData) Error

func (e *ExitErrorData) Error() (exitErrorMessage string)

the Error method returns the message from any ExitError, otherwise empty string

• Error also makes ExitErrorData implementing the error interface

func (*ExitErrorData) ExitErrorString

func (e *ExitErrorData) ExitErrorString(includeStderr ...bool) (errS string)

ExitErrorString returns the ExitError error message and data from Err and stderr, not an error value

• for non-signal: “status code: 1 ‘read error’”
• for signal: “signal: "abort trap" ‘signal: abort trap’”
• the error message for err: “message: ‘failure’”
• stderr if non-empty from ExitErr or stderr argument and includeStderr is ExitErrorIncludeStderr:
• “stderr: ‘I/O error’”
• returned value is never empty

func (*ExitErrorData) IsExitError

func (e *ExitErrorData) IsExitError() (isExitError bool)

IsExitError returns true if an pexec.ExitError is present

• false if Err was nil or some other type of error

func (*ExitErrorData) IsSignalKill

func (e *ExitErrorData) IsSignalKill() (isSignalKill bool)

IsSignalKill returns true if the err error chain contains an ExitError with signal kill

• signal kill is the response to a command’s context being canceled. This should be checked together with context.Context.Err
• SIGKILL can also be sent to the process by the operating system trying to reclaim memory or by other processes

func (*ExitErrorData) IsStatusCode1

func (e *ExitErrorData) IsStatusCode1() (is1 bool)

IsStatusCode1 returns if the err error chain contains an ExitError that indicates status code 1

• Status code 1 indicates an unspecified failure of a process
• Success has no ExitError and status code 0
• Terminated by signal is status code -1
• Input syntax error is status code 2

type StartCallback

type StartCallback func(execCmd *exec.Cmd, err error)

type Stderrs

type Stderrs uint8

const (
	NoStderr Stderrs = iota + 1
	WantStderr
	StderrIsError
)

type Stdouts

type Stdouts bool

const (
	NoStdout   Stdouts = false
	WantStdout Stdouts = true
)