Class: LegacyMixlib::ShellOut

Inherits:
Object
  • Object
show all
Includes:
Unix, Windows
Defined in:
src/mintpress-common/lib/legacymixlib/shellout/exceptions.rb,
src/mintpress-common/lib/legacymixlib/shellout/helper.rb,
src/mintpress-common/lib/legacymixlib/shellout/unix.rb,
src/mintpress-common/lib/legacymixlib/shellout/windows.rb,
src/mintpress-common/lib/legacymixlib/shellout.rb

Defined Under Namespace

Modules: Helper, Unix, Windows Classes: CommandTimeout, EmptyWindowsCommand, Error, InvalidCommandOption, ShellCommandFailed

Properties (Read/Write)

Properties (Read Only)

Constant Summary collapse

READ_WAIT_TIME = 
0.01
READ_SIZE = 
4096
DEFAULT_READ_TIMEOUT = 
600

Constants included from Unix

Unix::ONE_DOT_EIGHT_DOT_SEVEN

Constants included from Windows

Windows::TIME_SLICE

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Unix

#all_seconderies, #logon_environment, #process_environment, #sgids, #using_login?

Constructor Details

#initialize(*command_args) ⇒ ShellOut

=== Arguments: Takes a single command, or a list of command fragments. These are used as arguments to Kernel.exec. See the Kernel.exec documentation for more explanation of how arguments are evaluated. The last argument can be an options Hash. === Options: If the last argument is a Hash, it is removed from the list of args passed to exec and used as an options hash. The following options are available: * +user+: the user the commmand should run as. if an integer is given, it is used as a uid. A string is treated as a username and resolved to a uid with Etc.getpwnam * +group+: the group the command should run as. works similarly to +user+ * +cwd+: the directory to chdir to before running the command * +umask+: a umask to set before running the command. If given as an Integer, be sure to use two leading zeros so it's parsed as Octal. A string will be treated as an octal integer * +returns+: one or more Integer values to use as valid exit codes for the subprocess. This only has an effect if you call +error!+ after +run_command+. * +environment+: a Hash of environment variables to set before the command is run. * +timeout+: a Numeric value for the number of seconds to wait on the child process before raising an Exception. This is calculated as the total amount of time that ShellOut waited on the child process without receiving any output (i.e., IO.select returned nil). Default is 600 seconds. Note: the stdlib Timeout library is not used. * +input+: A String of data to be passed to the subcommand. This is written to the child process' stdin stream before the process is launched. The child's stdin stream will be a pipe, so the size of input data should not exceed the system's default pipe capacity (4096 bytes is a safe value, though on newer Linux systems the capacity is 64k by default). * +live_stream+: An IO or Logger-like object (must respond to the append operator +<<+) that will receive data as ShellOut reads it from the child process. Generally this is used to copy data from the child to the parent's stdout so that users may observe the progress of long-running commands. * +login+: Whether to simulate a login (set secondary groups, primary group, environment variables etc) as done by the OS in an actual login === Examples: Invoke find(1) to search for .rb files: find = LegacyMixlib::ShellOut.new("find . -name '*.rb'") find.run_command # If all went well, the results are on +stdout+ puts find.stdout # find(1) prints diagnostic info to STDERR: puts "error messages" + find.stderr # Raise an exception if it didn't exit with 0 find.error! Run a command as the +www+ user with no extra ENV settings from +/tmp+ cmd = LegacyMixlib::ShellOut.new("apachectl", "start", :user => 'www', :env => nil, :cwd => '/tmp') cmd.run_command # etc.

Instance Attribute Details

#command ⇒ Object (readonly)

The command to be executed.

#cwd ⇒ Object

Working directory for the subprocess. Normally set via options to new

#domain ⇒ Object

Returns the value of attribute domain.

#elevated ⇒ Object

Runs windows process with elevated privileges. Required for Powershell commands which need elevated privileges

#environment ⇒ Object

Environment variables that will be set for the subcommand. Refer to the documentation of new to understand how ShellOut interprets this.

#execution_time ⇒ Object (readonly)

The amount of time the subcommand took to execute

#group ⇒ Object

Group the command will run as. Normally set via options passed to new

#input ⇒ Object

ShellOut will push data from :input down the stdin of the subprocess. Normally set via options passed to new. Default: nil

#live_stderr ⇒ Object

When live_stderr is set, the stderr of the subprocess will be copied to it as the subprocess is running.

#live_stdout ⇒ Object

When live_stdout is set, the stdout of the subprocess will be copied to it as the subprocess is running.

#log_level ⇒ Object

The log level at which ShellOut should log.

#log_tag ⇒ Object

A string which will be prepended to the log message.

#logger ⇒ Object

If a logger is set, ShellOut will log a message before it executes the command.

#login ⇒ Object

Whether to simulate logon as the user. Normally set via options passed to new Always enabled on windows

#password ⇒ Object

Returns the value of attribute password.

#process_status_pipe ⇒ Object (readonly)

Returns the value of attribute process_status_pipe.

#sensitive ⇒ Object

Returns the value of attribute sensitive.

#status ⇒ Object (readonly)

A Process::Status (or ducktype) object collected when the subprocess is reaped.

#stderr ⇒ Object (readonly)

Data written to stderr by the subprocess

#stderr_pipe ⇒ Object (readonly)

Returns the value of attribute stderr_pipe.

#stdin_pipe ⇒ Object (readonly)

Returns the value of attribute stdin_pipe.

#stdout ⇒ Object (readonly)

Data written to stdout by the subprocess

#stdout_pipe ⇒ Object (readonly)

Returns the value of attribute stdout_pipe.

#timeout ⇒ Object

#umask ⇒ Object

The umask that will be set for the subcommand.

#user ⇒ Object

User the command will run as. Normally set via options passed to new

#valid_exit_codes ⇒ Object

An Array of acceptable exit codes. #error? (and #error!) use this list to determine if the command was successful. Normally set via options to new

#with_logon ⇒ Object

TODO remove

Instance Method Details

#error! ⇒ Object

If #error? is true, calls +invalid!+, which raises an Exception. === Returns nil::: always returns nil when it does not raise === Raises ::ShellCommandFailed::: via +invalid!+

#error? ⇒ Boolean

Checks the +exitstatus+ against the set of +valid_exit_codes+. === Returns +true+ if +exitstatus+ is not in the list of +valid_exit_codes+, false otherwise.

Returns:

  • (Boolean)

#exitstatus ⇒ Object

The exit status of the subprocess. Will be nil if the command is still running or died without setting an exit status (e.g., terminated by `kill -9`).

#format_for_exception ⇒ Object

Creates a String showing the output of the command, including a banner showing the exact command executed. Used by +invalid!+ to show command results when the command exited with an unexpected status.

#gid ⇒ Object

The gid that the subprocess will switch to. If the group attribute is given as a group name, it is converted to a gid by Etc.getgrnam TODO migrate to shellout/unix.rb

#inspect ⇒ Object

#invalid!(msg = nil) ⇒ Object

Raises a ShellCommandFailed exception, appending the command's stdout, stderr, and exitstatus to the exception message. === Arguments +msg+: A String to use as the basis of the exception message. The default explanation is very generic, providing a more informative message is highly encouraged. === Raises ShellCommandFailed always

Raises:

#live_stream ⇒ Object

Returns the stream that both is being used by both live_stdout and live_stderr, or nil

#live_stream=(stream) ⇒ Object

A shortcut for setting both live_stdout and live_stderr, so that both the stdout and stderr from the subprocess will be copied to the same stream as the subprocess is running.

#run_command ⇒ Object

Run the command, writing the command's standard out and standard error to +stdout+ and +stderr+, and saving its exit status object to +status+ === Returns returns +self+; +stdout+, +stderr+, +status+, and +exitstatus+ will be populated with results of the command === Raises * Errno::EACCES when you are not privileged to execute the command * Errno::ENOENT when the command is not available on the system (or not in the current $PATH) * CommandTimeout when the command does not complete within +timeout+ seconds (default: 600s)

#uid ⇒ Object

The uid that the subprocess will switch to. If the user attribute was given as a username, it is converted to a uid by Etc.getpwnam TODO migrate to shellout/unix.rb