Documentation
¶
Overview ¶
Package command provide utilities around os/exec package
Index ¶
- Constants
- Variables
- func CmdArgsFromString(s string) ([]string, error)
- func ShLimitCommands(l limits.T) string
- func WithArgs(args []string) funcopt.O
- func WithBufferedStderr() funcopt.O
- func WithBufferedStdout() funcopt.O
- func WithCWD(cwd string) funcopt.O
- func WithCommandLogLevel(l zerolog.Level) funcopt.O
- func WithContext(ctx context.Context) funcopt.O
- func WithEnv(env []string) funcopt.O
- func WithErrorExitCodeLogLevel(l zerolog.Level) funcopt.O
- func WithGroup(group string) funcopt.O
- func WithIgnoredExitCodes(codes ...int) funcopt.O
- func WithLogLevel(l zerolog.Level) funcopt.O
- func WithLogger(l *plog.Logger) funcopt.O
- func WithName(name string) funcopt.O
- func WithOnStderrLine(f func(string)) funcopt.O
- func WithOnStdoutLine(f func(string)) funcopt.O
- func WithProcessGroup() funcopt.O
- func WithPrompt(l *bufio.Reader) funcopt.O
- func WithStderrLogLevel(l zerolog.Level) funcopt.O
- func WithStdoutLogLevel(l zerolog.Level) funcopt.O
- func WithTimeout(timeout time.Duration) funcopt.O
- func WithUser(user string) funcopt.O
- func WithVarArgs(args ...string) funcopt.O
- func WithVarEnv(env ...string) funcopt.O
- func WithWaitDelay(d time.Duration) funcopt.O
- type ErrExitCode
- type T
Constants ¶
const DefaultWaitDelay = 5 * time.Second
DefaultWaitDelay is how long a command is given, after it has exited, for the output it wrote to reach this process.
It is the grace a well-behaved command never uses: what it wrote is already in the pipe when it exits, and the pipe reaches EOF as soon as the last holder of its write end is gone. The delay is for the command that hands a write end to something that outlives it, where EOF never comes at all.
Variables ¶
Functions ¶
func CmdArgsFromString ¶
CmdArgsFromString returns args for exec.Command from a string command 's' When string command 's' contains multiple commands,
exec.Command("/bin/sh", "-c", s)
else
exec.Command from shlex.Split(s)
func ShLimitCommands ¶
ShLimitCommands provides ulimit commands for sh launcher max value of LimitVMem, LimitAs is used to set virtual memory limit
func WithBufferedStderr ¶
WithBufferedStderr activates the buffering of the lines emitted by the process on stderr
func WithBufferedStdout ¶
WithBufferedStdout activates the buffering of the lines emitted by the process on stdout
func WithCommandLogLevel ¶
WithCommandLogLevel show command name and args during Start
default zerolog.DebugLevel
func WithContext ¶
WithContext sets a custom context.Context for the command execution, using context.Background() if none is provided.
func WithErrorExitCodeLogLevel ¶
WithErrorExitCodeLogLevel sets the level of the log entries for error exit code.
func WithIgnoredExitCodes ¶
WithIgnoredExitCodes set alternate list of successful exit codes.
exit codes are checked during Wait(). - default successful exit code is 0 when WithIgnoredExitCodes is not used - Ignore all exit codes: WithIgnoredExitCodes() - Accept 0, 1 or 6 exit code: WithIgnoredExitCodes(0, 1, 6)
func WithLogLevel ¶
WithLogLevel sets the level of the log entries.
func WithLogger ¶
WithLogger defines the Logger that will receive this pkg logs and process outputs
func WithOnStderrLine ¶
func WithOnStdoutLine ¶
func WithProcessGroup ¶
WithProcessGroup runs the command in a process group of its own, which a cancel of its context kills as a whole: the processes the command started die with it, rather than outliving it holding its output.
func WithPrompt ¶
WithLogger defines the Logger that will receive this pkg logs and process outputs
func WithStderrLogLevel ¶
WithStderrLogLevel sets the level of the log entries coming from the process stderr If not set, stderr lines are not logged.
func WithStdoutLogLevel ¶
WithStdoutLogLevel sets the level of the log entries coming from the process stdout. If not set, stdout lines are not logged.
func WithTimeout ¶
WithTimeout sets the max duration the process is allowed to run. After this duration, the process is killed and an error is reported.
func WithVarArgs ¶
WithVarArgs sets the process args[1:] from a variadic string slice
func WithVarEnv ¶
func WithWaitDelay ¶
WithWaitDelay bounds how long a command is given, after it has exited, for the output it wrote to reach this process.
Zero waits for the output pipes to reach EOF however long that takes, which is never when the command left something behind holding them open. The default is DefaultWaitDelay, and a command whose output is worth waiting longer for can say so.
Types ¶
type ErrExitCode ¶
type ErrExitCode struct {
// contains filtered or unexported fields
}
func (*ErrExitCode) Error ¶
func (e *ErrExitCode) Error() string
func (*ErrExitCode) ExitCode ¶
func (e *ErrExitCode) ExitCode() int
type T ¶
type T struct {
// contains filtered or unexported fields
}
func (*T) NormalizedExitCode ¶
NormalizedExitCode returns the process exit status, and 128 + the signal number when the process was terminated by one, which is the shell convention and the value this package's own error and log entries already carry.
ExitCode returns the raw os/exec value, which is -1 for a signaled process and says nothing about which signal. A caller comparing against a command's documented codes wants that one. A caller reporting the outcome to a person wants this one, and wants it to agree with the error text beside it.
It is -1 when the process never ran, which is the one case no exit status exists for.
func (*T) Output ¶
Output returns stdout results of command (meaningful after Wait() or Run()), command created without funcopt WithBufferedStdout() return nil valid results
func (*T) Start ¶
Start prepare command, then call underlying cmd.Start() it takes care of preparing logging, timeout, stdout and stderr watchers
func (*T) Stderr ¶
Stderr returns stderr results of command (meaningful after Wait() or Run()) command created without funcopt WithBufferedStderr() return nil
Source Files