executil

README

executil

Package 'executil' lets to run system commands with advanced features like the found ones at shells.

Documentation online

Author

Jonás Melián (https://bitbucket.org/ares)

License

The source files are distributed under the Apache License, version 2.0.

Documentation

Overview

Package executil lets to call to system commands. By default, logs the commands to run.

To run the tests related to command 'sudo', there is to run:

go test -tags sudo

Index

• Variables
• func CheckStderr(stderr []byte, err error) error
• func CheckStderrSkipWarn(stderr, warning []byte, err error) error
• func LookDirExec(filename string) (string, error)
• func LookPath(filename ...string) (string, error)
• func RunAsBash(command string) (output []byte, err error)
• func RunAsBashWithMatch(command string) (output []byte, match bool, err error)
• func RunAsBashWithMatchf(format string, args ...interface{}) ([]byte, bool, error)
• func RunAsBashf(format string, args ...interface{}) ([]byte, error)
• type Command
  • func NewCommand(cmd string, args ...string) *Command
  • func NewCommandAsUser(usr, cmd string) *Command
  • func (c *Command) AddEnv(e []string) *Command
  • func (c *Command) BadExitCodes(codes []int) *Command
  • func (c *Command) Command(cmd string, args ...string) *Command
  • func (c *Command) Env(e []string) *Command
  • func (c *Command) ExitCode() int
  • func (c *Command) OkExitCodes(codes []int) *Command
  • func (c *Command) OutputCombined() (stdout, stderr []byte, err error)
  • func (c *Command) OutputStderr() (stderr []byte, err error)
  • func (c *Command) OutputStdout() (stdout []byte, err error)
  • func (c *Command) Run() (exitCode int, err error)
  • func (c *Command) StdCombinedTofile(dir, filename string, fnCheckStderr func([]byte) error) error
  • func (c *Command) Stderr(err io.Writer) *Command
  • func (c *Command) StderrTofile(dir, filename string, fnCheckStderr func([]byte) error) error
  • func (c *Command) Stdout(out io.Writer) *Command
  • func (c *Command) StdoutTofile(dir, filename string) error
  • func (c *Command) TimeKill(tm time.Duration) *Command

Variables

var DebugAsBash bool

DebugRunAsBash shows debug messages at functions related to 'RunAsBash()'.

var (

	// ErrNotFound indicates when a search does not find a file at 'LookPath()'.
	ErrNotFound = errors.New("file not found")
)

var ErrProcKilled = errors.New("the process hasn't exited or was terminated by a signal")

ErrProcKilled reports an error by a process killed.

var Log *log.Logger

Log is the logger by default.

var (

	// Sudo is the path of command 'sudo'.
	Sudo string = "/usr/bin/sudo"
)

Functions

func CheckStderr

func CheckStderr(stderr []byte, err error) error

CheckStderr returns an error whether 'stderr' is not empty or there is any error.

func CheckStderrSkipWarn

func CheckStderrSkipWarn(stderr, warning []byte, err error) error

CheckStderrSkipWarn returns an error whether 'stderr' is not empty and it is not a message which starts with 'warning', or there is any error.

func LookDirExec

func LookDirExec(filename string) (string, error)

LookDirExec looks up the directory of an executable.

func LookPath

func LookPath(filename ...string) (string, error)

LookPath searches for an executable named file in the system directories given one or several executables.

func RunAsBash

func RunAsBash(command string) (output []byte, err error)

RunAsBash executes external commands just like RunAsBashWithMatch, but does not return the boolean `match`.

func RunAsBashWithMatch

func RunAsBashWithMatch(command string) (output []byte, match bool, err error)

RunAsBashWithMatch executes external commands with access to shell features such as filename wildcards, shell pipes, environment variables, and expansion of the shortcut character "~" to home directory. It also logs the command.

This function avoids to have execute commands through a shell since an unsanitized input from an untrusted source makes a program vulnerable to shell injection, a serious security flaw which can result in arbitrary command execution.

The most of commands return a text in output or an error if any. `match` is used in commands like *grep*, *find*, or *cmp* to indicate if the search is matched.

func RunAsBashWithMatchf

func RunAsBashWithMatchf(format string, args ...interface{}) ([]byte, bool, error)

RunAsBashWithMatchf is like RunAsBashWithMatch, but formats its arguments according to the format. Analogous to Printf().

func RunAsBashf

func RunAsBashf(format string, args ...interface{}) ([]byte, error)

RunAsBashf is like RunAsBash, but formats its arguments according to the format. Analogous to Printf().

Types

type Command

type Command struct {
	// contains filtered or unexported fields
}

Command represents a command to execute.

func NewCommand

func NewCommand(cmd string, args ...string) *Command

NewCommand sets the basic arguments to execute a command.

func NewCommandAsUser

func NewCommandAsUser(usr, cmd string) *Command

NewCommandAsUser represents a command to be executed by an user using 'sudo'. Panics whether the command 'sudo' is not found.

func (*Command) AddEnv

func (c *Command) AddEnv(e []string) *Command

AddEnv adds environment variables.

func (*Command) BadExitCodes

func (c *Command) BadExitCodes(codes []int) *Command

BadExitCodes sets the exit codes with errors for the command.

func (*Command) Command

func (c *Command) Command(cmd string, args ...string) *Command

Command sets the arguments to run other command.

func (*Command) Env

func (c *Command) Env(e []string) *Command

Env sets the environment variables.

func (*Command) ExitCode

func (c *Command) ExitCode() int

ExitCode returns the exit status code which is returned after of call to Run().

func (*Command) OkExitCodes

func (c *Command) OkExitCodes(codes []int) *Command

OkExitCodes sets the exit codes without errors for the command.

func (*Command) OutputCombined

func (c *Command) OutputCombined() (stdout, stderr []byte, err error)

OutputCombined runs the command and returns both standard output and error.

func (*Command) OutputStderr

func (c *Command) OutputStderr() (stderr []byte, err error)

OutputStderr runs the command and returns the standard error.

func (*Command) OutputStdout

func (c *Command) OutputStdout() (stdout []byte, err error)

OutputStdout runs the command and returns the standard output.

func (*Command) Run

func (c *Command) Run() (exitCode int, err error)

Run executes the command. Logs the command, and the exit code if it is different to zero.

func (*Command) StdCombinedTofile

func (c *Command) StdCombinedTofile(
	dir, filename string, fnCheckStderr func([]byte) error,
) error

StdCombinedTofile runs the command and saves both standard output and error into files. The full names are formed with the values of 'filename' plus "_stdout.log" and 'filename' plus "_stderr.log".

func (*Command) Stderr

func (c *Command) Stderr(err io.Writer) *Command

Stderr sets the standard error.

func (*Command) StderrTofile

func (c *Command) StderrTofile(dir, filename string, fnCheckStderr func([]byte) error) error

StderrTofile runs the command and saves the standard error into a file. The full name is formed with the value of 'filename' plus "_stderr.log". fnCheckStderr is a function to check the standard error.

func (*Command) Stdout

func (c *Command) Stdout(out io.Writer) *Command

Stdout sets the standard out.

func (*Command) StdoutTofile

func (c *Command) StdoutTofile(dir, filename string) error

StdoutTofile runs the command and saves the standard output into a file. The full name is formed with the value of 'filename' plus "_stdout.log".

func (*Command) TimeKill

func (c *Command) TimeKill(tm time.Duration) *Command

TimeKill sets the time of waiting to finish the command before of kill it.