pexec

Documentation

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) 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 (
	ExitErrorIncludeStderr = true
	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 {
	Err        error
	ExitErr    *exec.ExitError
	StatusCode int
	Signal     unix.Signal
	Stderr     []byte
}

func NewExitErrorData

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

NewExitErrorData returns once-retrieved data on a possible ExitError

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

func (*ExitErrorData) Error

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

func (*ExitErrorData) ExitErrorString

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

ExitErrorString returns a printable string if the err error chain contains an ExitError

• if no ExitError, the empty string
• for non-signal: status code: 1 ‘read error’
• for signal: signal: "abort trap" ‘signal: abort trap’
• prints stderr if includeStderr is ExitErrorIncludeStderr and stderr non-empty

func (*ExitErrorData) IsExitError

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

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

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
)