Class | Chef::ShellOut
In: | lib/chef/shell_out/windows.rb lib/chef/shell_out/unix.rb lib/chef/shell_out.rb
Parent: | Object

## Chef::ShellOut

Provides a simplified interface to shelling out yet still collecting both standard out and standard error and providing full control over environment, working directory, uid, gid, etc.

No means for passing input to the subprocess is provided, nor is there any way to inspect the output of the command as it is being read. If you need to do that, you have to use popen4 (in Chef::Mixin::Command)

### Platform Support

Chef::ShellOut uses Kernel.fork() and is therefore unsuitable for Windows or jruby.

### 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 Chef::ShellOut::Unix
Module Chef::ShellOut::Windows

### Constants

READ_WAIT_TIME | = | 0.01
READ_SIZE | = | 4096
DEFAULT_READ_TIMEOUT | = | 600
DEFAULT_ENVIRONMENT | = | {'LC_ALL' => 'C'}

### Attributes

command | [R] |
command_log_level | [RW] |
command_log_prepend | [RW] |
cwd | [RW] |
environment | [R] |
execution_time | [R] |
group | [RW] |
live_stream | [RW] |
process_status_pipe | [R] |
status | [R] |
stderr | [R] |
stderr_pipe | [R] |
stdin_pipe | [R] |
stdout | [R] |
stdout_pipe | [R] |
timeout | [W] |
umask | [R] |
user | [RW] |
valid_exit_codes | [RW] |

### Public Class methods

new(*command_args)

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

### Public Instance methods

error!()

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

Chef::Exceptions::ShellCommandFailed:: | via +invalid!+

exitstatus()
format_for_exception()

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()
inspect()
invalid!(msg=nil)

Raises a Chef::Exceptions::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

Chef::Exceptions::ShellCommandFailed always

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)
- Chef::Exceptions::CommandTimeout when the command does not complete within `timeout` seconds (default: 60s)

timeout()
uid()
umask=(new_umask)

[Validate]