module Puppet::Util::Execution

Wraps execution of {execute} with mapping of exception to given exception (and output as argument). @raise [exception] under same conditions as {execute}, but raises the given `exception` with the output as argument @return (see execute)

# File lib/puppet/util/execution.rb, line 65
def self.execfail(command, exception)
  output = execute(command)
  return output
rescue ExecutionFailure
  raise exception, output
end

Executes the provided command with STDIN connected to a pipe, yielding the pipe object. This allows data to be fed to the subprocess.

The command can be a simple string, which is executed as-is, or an Array, which is treated as a set of command arguments to pass through.

In all cases this is passed directly to the shell, and STDOUT and STDERR are connected together during execution. @param command [String, Array<String>] the command to execute as one string, or as parts in an array.

the parts of the array are joined with one separating space between each entry when converting to
the command line string to execute.

@param failonfail [Boolean] (true) if the execution should fail with Exception on failure or not. @yield [pipe] to a block executing a subprocess @yieldparam pipe [IO] the opened pipe @yieldreturn [String] the output to return @raise [ExecutionFailure] if the executed chiled process did not exit with status == 0 and `failonfail` is

`true`.

@return [String] a string with the output from the subprocess executed by the given block

# File lib/puppet/util/execution.rb, line 34
def self.execpipe(command, failonfail = true)
  if respond_to? :debug
    debug "Executing '#{command}'"
  else
    Puppet.debug "Executing '#{command}'"
  end

  # Paste together an array with spaces.  We used to paste directly
  # together, no spaces, which made for odd invocations; the user had to
  # include whitespace between arguments.
  #
  # Having two spaces is really not a big drama, since this passes to the
  # shell anyhow, while no spaces makes for a small developer cost every
  # time this is invoked. --daniel 2012-02-13
  command_str = command.respond_to?(:join) ? command.join(' ') : command
  output = open("| #{command_str} 2>&1") do |pipe|
    yield pipe
  end

  if failonfail
    unless $CHILD_STATUS == 0
      raise ExecutionFailure, output
    end
  end

  output
end

Executes the desired command, and return the status and output. def execute(command, options) @param command [Array<String>, String] the command to execute. If it is

an Array the first element should be the executable and the rest of the
elements should be the individual arguments to that executable.

@param options [Hash] a Hash of options @option options [Boolean] :failonfail if this value is set to true, then this method will raise an error if the

command is not executed successfully.

@option options [?] :uid (nil) the user id of the user that the process should be run as @option options [?] :gid (nil) the group id of the group that the process should be run as @option options [Boolean] :combine sets whether or not to combine stdout/stderr in the output @option options [String] :stdinfile (nil) sets a file that can be used for stdin. Passing a string for stdin is not currently

supported.

@option options [Boolean] :squelch (true) if true, ignore stdout / stderr completely. @option options [Boolean] :override_locale (true) by default (and if this option is set to true), we will temporarily override

the user/system locale to "C" (via environment variables LANG and LC_*) while we are executing the command.
This ensures that the output of the command will be formatted consistently, making it predictable for parsing.
Passing in a value of false for this option will allow the command to be executed using the user/system locale.

@option options [Hash<{String => String}>] :custom_environment ({}) a hash of key/value pairs to set as environment variables for the duration

of the command.

@return [String] output as specified by options @note Unfortunately, the default behavior for failonfail and combine (since

0.22.4 and 0.24.7, respectively) depend on whether options are specified
or not. If specified, then failonfail and combine default to false (even
when the options specified are neither failonfail nor combine). If no
options are specified, then failonfail and combine default to true.

@comment See commits efe9a833c and d32d7f30

# File lib/puppet/util/execution.rb, line 103
def self.execute(command, options = NoOptionsSpecified)
  # specifying these here rather than in the method signature to allow callers to pass in a partial
  # set of overrides without affecting the default values for options that they don't pass in
  default_options = {
      :failonfail => NoOptionsSpecified.equal?(options),
      :uid => nil,
      :gid => nil,
      :combine => NoOptionsSpecified.equal?(options),
      :stdinfile => nil,
      :squelch => false,
      :override_locale => true,
      :custom_environment => {},
  }

  options = default_options.merge(options)

  if command.is_a?(Array)
    command = command.flatten.map(&:to_s)
    str = command.join(" ")
  elsif command.is_a?(String)
    str = command
  end

  if respond_to? :debug
    debug "Executing '#{str}'"
  else
    Puppet.debug "Executing '#{str}'"
  end

  null_file = Puppet.features.microsoft_windows? ? 'NUL' : '/dev/null'

  stdin = File.open(options[:stdinfile] || null_file, 'r')
  stdout = options[:squelch] ? File.open(null_file, 'w') : Tempfile.new('puppet')
  stderr = options[:combine] ? stdout : File.open(null_file, 'w')

  exec_args = [command, options, stdin, stdout, stderr]

  if execution_stub = Puppet::Util::ExecutionStub.current_value
    return execution_stub.call(*exec_args)
  elsif Puppet.features.posix?
    child_pid = execute_posix(*exec_args)
    exit_status = Process.waitpid2(child_pid).last.exitstatus
  elsif Puppet.features.microsoft_windows?
    process_info = execute_windows(*exec_args)
    begin
      exit_status = Puppet::Util::Windows::Process.wait_process(process_info.process_handle)
    ensure
      Process.CloseHandle(process_info.process_handle)
      Process.CloseHandle(process_info.thread_handle)
    end
  end

  [stdin, stdout, stderr].each {|io| io.close rescue nil}

  # read output in if required
  unless options[:squelch]
    output = wait_for_output(stdout)
    Puppet.warning "Could not get output" unless output
  end

  if options[:failonfail] and exit_status != 0
    raise ExecutionFailure, "Execution of '#{str}' returned #{exit_status}: #{output}"
  end

  output
end

Returns the path to the ruby executable (available via Config object, even if it’s not in the PATH… so this is slightly safer than just using Puppet::Util.which) @return [String] the path to the Ruby executable

# File lib/puppet/util/execution.rb, line 174
def self.ruby_path()
  File.join(RbConfig::CONFIG['bindir'],
            RbConfig::CONFIG['ruby_install_name'] + RbConfig::CONFIG['EXEEXT']).
    sub(/.*\s.*/, '"\&"')
end