Class: Mixlib::ShellOut

Inherits:

Object

• Object
• Mixlib::ShellOut

show all

Includes:

Unix, Windows

Defined in:

lib/mixlib/shellout.rb,
lib/mixlib/shellout/unix.rb,
lib/mixlib/shellout/version.rb,
lib/mixlib/shellout/windows.rb,
lib/mixlib/shellout/exceptions.rb

Defined Under Namespace

Modules: Unix, Windows Classes: CommandTimeout, InvalidCommandOption, ShellCommandFailed

Constant Summary

READ_WAIT_TIME =

0.01

READ_SIZE =

4096

DEFAULT_READ_TIMEOUT =

600

DEFAULT_ENVIRONMENT =

{'LC_ALL' => 'C'}

VERSION =

"1.0.0"

Constants included from Windows

Windows::IS_BATCH_FILE, Windows::TIME_SLICE

Instance Attribute Summary (collapse)

• - (Object) command readonly

  The command to be executed.

• - (Object) cwd

  Working directory for the subprocess.

• - (Object) environment readonly

  Environment variables that will be set for the subcommand.

• - (Object) execution_time readonly

  The amount of time the subcommand took to execute.

• - (Object) group

  Group the command will run as.

• - (Object) live_stream

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

• - (Object) log_level

  The log level at which ShellOut should log.

• - (Object) log_tag

  A string which will be prepended to the log message.

• - (Object) logger

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

• - (Object) process_status_pipe readonly

  Returns the value of attribute process_status_pipe.

• - (Object) status readonly

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

• - (Object) stderr readonly

  Data written to stderr by the subprocess.

• - (Object) stderr_pipe readonly

  Returns the value of attribute stderr_pipe.

• - (Object) stdin_pipe readonly

  Returns the value of attribute stdin_pipe.

• - (Object) stdout readonly

  Data written to stdout by the subprocess.

• - (Object) stdout_pipe readonly

  Returns the value of attribute stdout_pipe.

• - (Object) timeout
• - (Object) umask

  The umask that will be set for the subcommand.

• - (Object) user

  User the command will run as.

• - (Object) valid_exit_codes

  An Array of acceptable exit codes.

Instance Method Summary (collapse)

• - (Object) error!

  Checks the exitstatus against the set of valid_exit_codes.

• - (Object) exitstatus

  The exit status of the subprocess.

• - (Object) format_for_exception

  Creates a String showing the output of the command, including a banner showing the exact command executed.

• - (Object) gid

  The gid that the subprocess will switch to.

• - (ShellOut) initialize(*command_args) constructor

  Arguments:

  Takes a single command, or a list of command fragments.

• - (Object) inspect
• - (Object) invalid!(msg = nil)

  Raises a ShellCommandFailed exception, appending the command's stdout, stderr, and exitstatus to the exception message.

• - (Object) run_command

  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.

• - (Object) uid

  The uid that the subprocess will switch to.

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!

cmd = Mixlib::ShellOut.new("apachectl", "start", :user => 'www', :env => nil, :cwd => '/tmp')
cmd.run_command # etc.

140
141
142
143
144
145
146
147
148
149
150
151
152
153
154

# File 'lib/mixlib/shellout.rb', line 140

def initialize(*command_args)
  @stdout, @stderr = '', ''
  @live_stream = nil
  @log_level = :debug
  @log_tag = nil
  @environment = DEFAULT_ENVIRONMENT
  @cwd = nil
  @valid_exit_codes = [0]

  if command_args.last.is_a?(Hash)
    parse_options(command_args.pop)
  end

  @command = command_args.size == 1 ? command_args.first : command_args
end

69
70
71

# File 'lib/mixlib/shellout.rb', line 69

def command
  @command
end

47
48
49

# File 'lib/mixlib/shellout.rb', line 47

def cwd
  @cwd
end

76
77
78

# File 'lib/mixlib/shellout.rb', line 76

def environment
  @environment
end

83
84
85

# File 'lib/mixlib/shellout.rb', line 83

def execution_time
  @execution_time
end

44
45
46

# File 'lib/mixlib/shellout.rb', line 44

def group
  @group
end

56
57
58

# File 'lib/mixlib/shellout.rb', line 56

def live_stream
  @live_stream
end

63
64
65

# File 'lib/mixlib/shellout.rb', line 63

def log_level
  @log_level
end

66
67
68

# File 'lib/mixlib/shellout.rb', line 66

def log_tag
  @log_tag
end

60
61
62

# File 'lib/mixlib/shellout.rb', line 60

def logger
  @logger
end

95
96
97

# File 'lib/mixlib/shellout.rb', line 95

def process_status_pipe
  @process_status_pipe
end

93
94
95

# File 'lib/mixlib/shellout.rb', line 93

def status
  @status
end

89
90
91

# File 'lib/mixlib/shellout.rb', line 89

def stderr
  @stderr
end

95
96
97

# File 'lib/mixlib/shellout.rb', line 95

def stderr_pipe
  @stderr_pipe
end

95
96
97

# File 'lib/mixlib/shellout.rb', line 95

def stdin_pipe
  @stdin_pipe
end

86
87
88

# File 'lib/mixlib/shellout.rb', line 86

def stdout
  @stdout
end

95
96
97

# File 'lib/mixlib/shellout.rb', line 95

def stdout_pipe
  @stdout_pipe
end

176
177
178

# File 'lib/mixlib/shellout.rb', line 176

def timeout
  @timeout || DEFAULT_READ_TIMEOUT
end

72
73
74

# File 'lib/mixlib/shellout.rb', line 72

def umask
  @umask
end

41
42
43

# File 'lib/mixlib/shellout.rb', line 41

def user
  @user
end

51
52
53

# File 'lib/mixlib/shellout.rb', line 51

def valid_exit_codes
  @valid_exit_codes
end

226
227
228
229
230

# File 'lib/mixlib/shellout.rb', line 226

def error!
  unless Array(valid_exit_codes).include?(exitstatus)
    invalid!("Expected process to exit with #{valid_exit_codes.inspect}, but received '#{exitstatus}'")
  end
end

196
197
198

# File 'lib/mixlib/shellout.rb', line 196

def exitstatus
  @status && @status.exitstatus
end

183
184
185
186
187
188
189
190
191

# File 'lib/mixlib/shellout.rb', line 183

def format_for_exception
  msg = ""
  msg << "---- Begin output of #{command} ----\n"
  msg << "STDOUT: #{stdout.strip}\n"
  msg << "STDERR: #{stderr.strip}\n"
  msg << "---- End output of #{command} ----\n"
  msg << "Ran #{command} returned #{status.exitstatus}" if status
  msg
end

171
172
173
174

# File 'lib/mixlib/shellout.rb', line 171

def gid
  return nil unless group
  group.kind_of?(Integer) ? group : Etc.getgrnam(group.to_s).gid
end

245
246
247
248
249

# File 'lib/mixlib/shellout.rb', line 245

def inspect
  "<#{self.class.name}##{object_id}: command: '#@command' process_status: #{@status.inspect} " +
  "stdout: '#{stdout.strip}' stderr: '#{stderr.strip}' child_pid: #{@child_pid.inspect} " +
  "environment: #{@environment.inspect} timeout: #{timeout} user: #@user group: #@group working_dir: #@cwd >"
end

240
241
242
243

# File 'lib/mixlib/shellout.rb', line 240

def invalid!(msg=nil)
  msg ||= "Command produced unexpected results"
  raise ShellCommandFailed, msg + "\n" + format_for_exception
end

211
212
213
214
215
216
217

# File 'lib/mixlib/shellout.rb', line 211

def run_command
  if logger
    log_message = (log_tag.nil? ? "" : "#@log_tag ") << "sh(#@command)"
    logger.send(log_level, log_message)
  end
  super
end

164
165
166
167

# File 'lib/mixlib/shellout.rb', line 164

def uid
  return nil unless user
  user.kind_of?(Integer) ? user : Etc.getpwnam(user.to_s).uid
end