pexec

package
v0.4.165 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 30, 2024 License: ISC Imports: 15 Imported by: 0

Documentation

Overview

Package pexec provides streaming, context-cancelable system command execution

Index

Constants

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

Variables

View Source 
var ErrArgsListEmpty = errors.New("args list empty")
View Source 
var NoStdin []byte

Functions

func ExecBlocking added in v0.4.87 

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 added in v0.4.38 

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 added in v0.4.40 

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 added in v0.4.106 

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 added in v0.4.106 

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 added in v0.4.111 

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 added in v0.4.106 

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 added in v0.4.106 

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 added in v0.4.106 

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 added in v0.4.106 

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 added in v0.4.106 

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 added in v0.4.104 

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

type Stderrs added in v0.4.87 

type Stderrs uint8
const (
	NoStderr Stderrs = iota + 1
	WantStderr
	StderrIsError
)

type Stdouts added in v0.4.87 

type Stdouts bool
const (
	NoStdout   Stdouts = false
	WantStdout Stdouts = true
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.