doc/classes/MCollective/Shell.html

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <!DOCTYPE html
   3      PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   4      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   5
   6 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   7 <head>
   8   <title>Class: MCollective::Shell</title>
   9   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
  10   <meta http-equiv="Content-Script-Type" content="text/javascript" />
  11   <link rel="stylesheet" href="../.././rdoc-style.css" type="text/css" media="screen" />
  12   <script type="text/javascript">
  13   // <![CDATA[
  14
  15   function popupCode( url ) {
  16     window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
  17   }
  18
  19   function toggleCode( id ) {
  20     if ( document.getElementById )
  21       elem = document.getElementById( id );
  22     else if ( document.all )
  23       elem = eval( "document.all." + id );
  24     else
  25       return false;
  26
  27     elemStyle = elem.style;
  28
  29     if ( elemStyle.display != "block" ) {
  30       elemStyle.display = "block"
  31     } else {
  32       elemStyle.display = "none"
  33     }
  34
  35     return true;
  36   }
  37
  38   // Make codeblocks hidden by default
  39   document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
  40
  41   // ]]>
  42   </script>
  43
  44 </head>
  45 <body>
  46
  47
  48
  49     <div id="classHeader">
  50         <table class="header-table">
  51         <tr class="top-aligned-row">
  52           <td><strong>Class</strong></td>
  53           <td class="class-name-in-header">MCollective::Shell</td>
  54         </tr>
  55         <tr class="top-aligned-row">
  56             <td><strong>In:</strong></td>
  57             <td>
  58                 <a href="../../files/lib/mcollective/shell_rb.html">
  59                 lib/mcollective/shell.rb
  60                 </a>
  61         <br />
  62             </td>
  63         </tr>
  64
  65         <tr class="top-aligned-row">
  66             <td><strong>Parent:</strong></td>
  67             <td>
  68                 Object
  69             </td>
  70         </tr>
  71         </table>
  72     </div>
  73   <!-- banner header -->
  74
  75   <div id="bodyContent">
  76
  77
  78
  79   <div id="contextContent">
  80
  81     <div id="description">
  82       <p>
  83 Wrapper around systemu that handles executing of system commands in a way
  84 that makes stdout, stderr and status available. Supports timeouts and sets
  85 a default sane environment.
  86 </p>
  87 <pre>
  88   s = Shell.new(&quot;date&quot;, opts)
  89   s.runcommand
  90   puts s.stdout
  91   puts s.stderr
  92   puts s.status.exitstatus
  93 </pre>
  94 <p>
  95 Options hash can have:
  96 </p>
  97 <pre>
  98   cwd         - the working directory the command will be run from
  99   stdin       - a string that will be sent to stdin of the program
 100   stdout      - a variable that will receive stdout, must support &lt;&lt;
 101   stderr      - a variable that will receive stdin, must support &lt;&lt;
 102   environment - the shell environment, defaults to include LC_ALL=C
 103                 set to nil to clear the environment even of LC_ALL
 104 </pre>
 105
 106     </div>
 107
 108
 109    </div>
 110
 111     <div id="method-list">
 112       <h3 class="section-bar">Methods</h3>
 113
 114       <div class="name-list">
 115       <a href="#M000371">new</a>&nbsp;&nbsp;
 116       <a href="#M000372">runcommand</a>&nbsp;&nbsp;
 117       </div>
 118     </div>
 119
 120   </div>
 121
 122
 123     <!-- if includes -->
 124
 125     <div id="section">
 126
 127
 128
 129
 130
 131     <div id="attribute-list">
 132       <h3 class="section-bar">Attributes</h3>
 133
 134       <div class="name-list">
 135         <table>
 136         <tr class="top-aligned-row context-row">
 137           <td class="context-item-name">command</td>
 138           <td class="context-item-value">&nbsp;[R]&nbsp;</td>
 139           <td class="context-item-desc"></td>
 140         </tr>
 141         <tr class="top-aligned-row context-row">
 142           <td class="context-item-name">cwd</td>
 143           <td class="context-item-value">&nbsp;[R]&nbsp;</td>
 144           <td class="context-item-desc"></td>
 145         </tr>
 146         <tr class="top-aligned-row context-row">
 147           <td class="context-item-name">environment</td>
 148           <td class="context-item-value">&nbsp;[R]&nbsp;</td>
 149           <td class="context-item-desc"></td>
 150         </tr>
 151         <tr class="top-aligned-row context-row">
 152           <td class="context-item-name">status</td>
 153           <td class="context-item-value">&nbsp;[R]&nbsp;</td>
 154           <td class="context-item-desc"></td>
 155         </tr>
 156         <tr class="top-aligned-row context-row">
 157           <td class="context-item-name">stderr</td>
 158           <td class="context-item-value">&nbsp;[R]&nbsp;</td>
 159           <td class="context-item-desc"></td>
 160         </tr>
 161         <tr class="top-aligned-row context-row">
 162           <td class="context-item-name">stdin</td>
 163           <td class="context-item-value">&nbsp;[R]&nbsp;</td>
 164           <td class="context-item-desc"></td>
 165         </tr>
 166         <tr class="top-aligned-row context-row">
 167           <td class="context-item-name">stdout</td>
 168           <td class="context-item-value">&nbsp;[R]&nbsp;</td>
 169           <td class="context-item-desc"></td>
 170         </tr>
 171         </table>
 172       </div>
 173     </div>
 174
 175
 176
 177     <!-- if method_list -->
 178     <div id="methods">
 179       <h3 class="section-bar">Public Class methods</h3>
 180
 181       <div id="method-M000371" class="method-detail">
 182         <a name="M000371"></a>
 183
 184         <div class="method-heading">
 185           <a href="#M000371" class="method-signature">
 186           <span class="method-name">new</span><span class="method-args">(command, options={})</span>
 187           </a>
 188         </div>
 189
 190         <div class="method-description">
 191           <p><a class="source-toggle" href="#"
 192             onclick="toggleCode('M000371-source');return false;">[Source]</a></p>
 193           <div class="method-source-code" id="M000371-source">
 194 <pre>
 195     <span class="ruby-comment cmt"># File lib/mcollective/shell.rb, line 24</span>
 196 24:     <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">initialize</span>(<span class="ruby-identifier">command</span>, <span class="ruby-identifier">options</span>={})
 197 25:       <span class="ruby-ivar">@environment</span> = {<span class="ruby-value str">&quot;LC_ALL&quot;</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-value str">&quot;C&quot;</span>}
 198 26:       <span class="ruby-ivar">@command</span> = <span class="ruby-identifier">command</span>
 199 27:       <span class="ruby-ivar">@status</span> = <span class="ruby-keyword kw">nil</span>
 200 28:       <span class="ruby-ivar">@stdout</span> = <span class="ruby-value str">&quot;&quot;</span>
 201 29:       <span class="ruby-ivar">@stderr</span> = <span class="ruby-value str">&quot;&quot;</span>
 202 30:       <span class="ruby-ivar">@stdin</span> = <span class="ruby-keyword kw">nil</span>
 203 31:       <span class="ruby-ivar">@cwd</span> = <span class="ruby-constant">Dir</span>.<span class="ruby-identifier">tmpdir</span>
 204 32:
 205 33:       <span class="ruby-identifier">options</span>.<span class="ruby-identifier">each</span> <span class="ruby-keyword kw">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">opt</span>, <span class="ruby-identifier">val</span><span class="ruby-operator">|</span>
 206 34:         <span class="ruby-keyword kw">case</span> <span class="ruby-identifier">opt</span>.<span class="ruby-identifier">to_s</span>
 207 35:           <span class="ruby-keyword kw">when</span> <span class="ruby-value str">&quot;stdout&quot;</span>
 208 36:             <span class="ruby-identifier">raise</span> <span class="ruby-value str">&quot;stdout should support &lt;&lt;&quot;</span> <span class="ruby-keyword kw">unless</span> <span class="ruby-identifier">val</span>.<span class="ruby-identifier">respond_to?</span>(<span class="ruby-value str">&quot;&lt;&lt;&quot;</span>)
 209 37:             <span class="ruby-ivar">@stdout</span> = <span class="ruby-identifier">val</span>
 210 38:
 211 39:           <span class="ruby-keyword kw">when</span> <span class="ruby-value str">&quot;stderr&quot;</span>
 212 40:             <span class="ruby-identifier">raise</span> <span class="ruby-value str">&quot;stderr should support &lt;&lt;&quot;</span> <span class="ruby-keyword kw">unless</span> <span class="ruby-identifier">val</span>.<span class="ruby-identifier">respond_to?</span>(<span class="ruby-value str">&quot;&lt;&lt;&quot;</span>)
 213 41:             <span class="ruby-ivar">@stderr</span> = <span class="ruby-identifier">val</span>
 214 42:
 215 43:           <span class="ruby-keyword kw">when</span> <span class="ruby-value str">&quot;stdin&quot;</span>
 216 44:             <span class="ruby-identifier">raise</span> <span class="ruby-value str">&quot;stdin should be a String&quot;</span> <span class="ruby-keyword kw">unless</span> <span class="ruby-identifier">val</span>.<span class="ruby-identifier">is_a?</span>(<span class="ruby-constant">String</span>)
 217 45:             <span class="ruby-ivar">@stdin</span> = <span class="ruby-identifier">val</span>
 218 46:
 219 47:           <span class="ruby-keyword kw">when</span> <span class="ruby-value str">&quot;cwd&quot;</span>
 220 48:             <span class="ruby-identifier">raise</span> <span class="ruby-node">&quot;Directory #{val} does not exist&quot;</span> <span class="ruby-keyword kw">unless</span> <span class="ruby-constant">File</span>.<span class="ruby-identifier">directory?</span>(<span class="ruby-identifier">val</span>)
 221 49:             <span class="ruby-ivar">@cwd</span> = <span class="ruby-identifier">val</span>
 222 50:
 223 51:           <span class="ruby-keyword kw">when</span> <span class="ruby-value str">&quot;environment&quot;</span>
 224 52:             <span class="ruby-keyword kw">if</span> <span class="ruby-identifier">val</span>.<span class="ruby-identifier">nil?</span>
 225 53:               <span class="ruby-ivar">@environment</span> = {}
 226 54:             <span class="ruby-keyword kw">else</span>
 227 55:               <span class="ruby-ivar">@environment</span>.<span class="ruby-identifier">merge!</span>(<span class="ruby-identifier">val</span>.<span class="ruby-identifier">dup</span>)
 228 56:             <span class="ruby-keyword kw">end</span>
 229 57:         <span class="ruby-keyword kw">end</span>
 230 58:       <span class="ruby-keyword kw">end</span>
 231 59:     <span class="ruby-keyword kw">end</span>
 232 </pre>
 233           </div>
 234         </div>
 235       </div>
 236
 237       <h3 class="section-bar">Public Instance methods</h3>
 238
 239       <div id="method-M000372" class="method-detail">
 240         <a name="M000372"></a>
 241
 242         <div class="method-heading">
 243           <a href="#M000372" class="method-signature">
 244           <span class="method-name">runcommand</span><span class="method-args">()</span>
 245           </a>
 246         </div>
 247
 248         <div class="method-description">
 249           <p>
 250 Actually does the systemu call passing in the correct environment, stdout
 251 and stderr
 252 </p>
 253           <p><a class="source-toggle" href="#"
 254             onclick="toggleCode('M000372-source');return false;">[Source]</a></p>
 255           <div class="method-source-code" id="M000372-source">
 256 <pre>
 257     <span class="ruby-comment cmt"># File lib/mcollective/shell.rb, line 62</span>
 258 62:     <span class="ruby-keyword kw">def</span> <span class="ruby-identifier">runcommand</span>
 259 63:       <span class="ruby-identifier">opts</span> = {<span class="ruby-value str">&quot;env&quot;</span>    =<span class="ruby-operator">&gt;</span> <span class="ruby-ivar">@environment</span>,
 260 64:               <span class="ruby-value str">&quot;stdout&quot;</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-ivar">@stdout</span>,
 261 65:               <span class="ruby-value str">&quot;stderr&quot;</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-ivar">@stderr</span>,
 262 66:               <span class="ruby-value str">&quot;cwd&quot;</span>    =<span class="ruby-operator">&gt;</span> <span class="ruby-ivar">@cwd</span>}
 263 67:
 264 68:       <span class="ruby-identifier">opts</span>[<span class="ruby-value str">&quot;stdin&quot;</span>] = <span class="ruby-ivar">@stdin</span> <span class="ruby-keyword kw">if</span> <span class="ruby-ivar">@stdin</span>
 265 69:
 266 70:       <span class="ruby-comment cmt"># Check if the parent thread is alive. If it should die,</span>
 267 71:       <span class="ruby-comment cmt"># and the process spawned by systemu is still alive,</span>
 268 72:       <span class="ruby-comment cmt"># fire off a blocking waitpid and wait for the process to</span>
 269 73:       <span class="ruby-comment cmt"># finish so that we can avoid zombies.</span>
 270 74:       <span class="ruby-identifier">thread</span> = <span class="ruby-constant">Thread</span>.<span class="ruby-identifier">current</span>
 271 75:       <span class="ruby-ivar">@status</span> = <span class="ruby-identifier">systemu</span>(<span class="ruby-ivar">@command</span>, <span class="ruby-identifier">opts</span>) <span class="ruby-keyword kw">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">cid</span><span class="ruby-operator">|</span>
 272 76:         <span class="ruby-keyword kw">begin</span>
 273 77:           <span class="ruby-keyword kw">while</span>(<span class="ruby-identifier">thread</span>.<span class="ruby-identifier">alive?</span>)
 274 78:             <span class="ruby-identifier">sleep</span> <span class="ruby-value">0</span><span class="ruby-value">.1</span>
 275 79:           <span class="ruby-keyword kw">end</span>
 276 80:
 277 81:           <span class="ruby-constant">Process</span>.<span class="ruby-identifier">waitpid</span>(<span class="ruby-identifier">cid</span>) <span class="ruby-keyword kw">if</span> <span class="ruby-constant">Process</span>.<span class="ruby-identifier">getpgid</span>(<span class="ruby-identifier">cid</span>)
 278 82:         <span class="ruby-keyword kw">rescue</span> <span class="ruby-constant">SystemExit</span>
 279 83:         <span class="ruby-keyword kw">rescue</span> <span class="ruby-constant">Errno</span><span class="ruby-operator">::</span><span class="ruby-constant">ESRCH</span>
 280 84:         <span class="ruby-keyword kw">rescue</span> <span class="ruby-constant">Errno</span><span class="ruby-operator">::</span><span class="ruby-constant">ECHILD</span>
 281 85:         <span class="ruby-keyword kw">rescue</span> <span class="ruby-constant">Exception</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-identifier">e</span>
 282 86:           <span class="ruby-constant">Log</span>.<span class="ruby-identifier">info</span>(<span class="ruby-node">&quot;Unexpected exception received while waiting for child process: #{e.class}: #{e}&quot;</span>)
 283 87:         <span class="ruby-keyword kw">end</span>
 284 88:       <span class="ruby-keyword kw">end</span>
 285 89:     <span class="ruby-keyword kw">end</span>
 286 </pre>
 287           </div>
 288         </div>
 289       </div>
 290
 291
 292     </div>
 293
 294
 295   </div>
 296
 297
 298 <div id="validator-badges">
 299   <p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
 300 </div>
 301
 302 </body>
 303 </html>