Class Mixlib::ShellOut
In: lib/mixlib/shellout.rb
lib/mixlib/shellout/unix.rb
lib/mixlib/shellout/windows.rb
lib/mixlib/shellout/exceptions.rb
lib/mixlib/shellout/version.rb
Parent: Object

Methods

error!   exitstatus   format_for_exception   gid   inspect   invalid!   new   run_command   timeout   uid   umask=  

Included Modules

ShellOut::Windows ShellOut::Unix

Classes and Modules

Module Mixlib::ShellOut::Unix
Module Mixlib::ShellOut::Windows
Class Mixlib::ShellOut::CommandTimeout
Class Mixlib::ShellOut::InvalidCommandOption
Class Mixlib::ShellOut::ShellCommandFailed

Constants

READ_WAIT_TIME = 0.01
READ_SIZE = 4096
DEFAULT_READ_TIMEOUT = 600
DEFAULT_ENVIRONMENT = {'LC_ALL' => 'C'}
VERSION = "1.2.0"

Attributes

command  [R]  The command to be executed.
cwd  [RW]  Working directory for the subprocess. Normally set via options to new
domain  [RW] 
environment  [R]  Environment variables that will be set for the subcommand. Refer to the documentation of new to understand how ShellOut interprets this.
execution_time  [R]  The amount of time the subcommand took to execute
group  [RW]  Group the command will run as. Normally set via options passed to new
input  [RW]  ShellOut will push data from :input down the stdin of the subprocss. Normally set via options passed to new. Default: nil
live_stream  [RW]  When live_stream is set, stdout of the subprocess will be copied to it as the subprocess is running. For example, if live_stream is set to STDOUT, the command‘s output will be echoed to STDOUT.
log_level  [RW]  The log level at which ShellOut should log.
log_tag  [RW]  A string which will be prepended to the log message.
logger  [RW]  If a logger is set, ShellOut will log a message before it executes the command.
password  [RW] 
process_status_pipe  [R] 
status  [R]  A Process::Status (or ducktype) object collected when the subprocess is reaped.
stderr  [R]  Data written to stderr by the subprocess
stderr_pipe  [R] 
stdin_pipe  [R] 
stdout  [R]  Data written to stdout by the subprocess
stdout_pipe  [R] 
timeout  [W]  The maximum time this command is allowed to run. Usually set via options to new
umask  [R]  The umask that will be set for the subcommand.
user  [RW]  User the command will run as. Normally set via options passed to new
valid_exit_codes  [RW]  An Array of acceptable exit codes. error! uses this list to determine if the command was successful. Normally set via options to new
with_logon  [RW] 

Public Class methods

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. By default, the environment will always be set to ‘LC_ALL’ => ‘C’ to prevent issues with multibyte characters in Ruby 1.8. To avoid this, use :environment => nil for no extra environment settings, or :environment => {‘LC_ALL’=>nil, …} to set other environment settings without changing the locale.
  • 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 60 seconds. Note: the stdlib Timeout library is not used.

Examples:

Invoke find(1) to search for .rb files:

  find = Mixlib::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 = Mixlib::ShellOut.new("apachectl", "start", :user => 'www', :env => nil, :cwd => '/tmp')
  cmd.run_command # etc.

Public Instance methods

Checks the exitstatus against the set of valid_exit_codes. If exitstatus is not in the list of valid_exit_codes, calls +invalid!+, which raises an Exception.

Returns

nil::always returns nil when it does not raise

Raises

::ShellCommandFailed::via +invalid!+

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`).

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.

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

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

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)

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

Set the umask that the subprocess will have. If given as a string, it will be converted to an integer by String#oct.

[Validate]