<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../../style.css">
<title>
Gambas Documentation - SHELL
</title>
</head>
<body>
<table class="none" width="100%" cellpadding="0" cellspacing="0" border="0">
<tr><td align="left">
<font size="-1">
<a href="../../help%3Fen"><img class="flag" alt="Home" border="0" src="../../img/lang/en.png" align="center"></a>&nbsp;&nbsp;
<a href="../lang%3Fen">Up</a>&nbsp;&nbsp;
<a href="sgn%3Fen">Previous</a>&nbsp;&nbsp;
<a href="shl%3Fen">Next</a>&nbsp;&nbsp;
</td></tr></table>
<div class="notab">
<h1>
SHELL
</h1>
<div class="black"><font color="white" size="-2"><b>Syntax</b></font></div>
<pre class="syntax">[ <u>Process</u> <b>=</b> ] <b>SHELL</b> <u>Command</u> [ <b>WAIT</b> ] [ <b>FOR</b> { { <b>READ</b> | <b>INPUT</b> } | { <b>WRITE</b> | <b>OUTPUT</b> } }<br>
<b>SHELL</b> <u>Command</u> <b>TO</b> <u>Variable</u></pre><p>

Executes a command. An internal <a href="../comp/gb/process%3Fen">Process</a> object is created to manage the command.
<p>
The command is a string containing a command passed to the system shell (<tt>/bin/sh</tt>).
<p>
<ul>
<li>If <tt><b>WAIT</b></tt> is specified, then the interpreter waits for the command ending. Otherwise, the command is executed in background.
<p>
<li>If <tt><b>FOR</b></tt> is specified, then the command input-outputs are redirected so that your program intercepts them:
<p>
<ul>
<li>If <tt><b>WRITE</b></tt> is specified, you can send data to the command standard input by using the <a href="../comp/gb/process%3Fen">Process</a> object with common output instructions: <a href="print%3Fen">PRINT</a>, <a href="write%3Fen">WRITE</a>, ... Note that you need a reference to the <a href="../comp/gb/process%3Fen">Process</a> object for that.
<p>
<li>If <tt><b>READ</b></tt> is specified, then events will be generated each time the command sends data to its standard output streams: the event <a href="../comp/gb/process/_read%3Fen">Read</a> is raised when data are sent to the standard output <a href="../def/stream%3Fen">stream</a>, and the event <a href="../comp/gb/process/_error%3Fen">Error</a> is raised when data are sent to the standard error <a href="../def/stream%3Fen">stream</a>. Use the process object with <a href="../cat/stream%3Fen">Stream &amp; Input/Output functions</a> to read the process standard output:.
<p>
</ul>
</ul>

If you use the <tt><b>INPUT</b></tt> and <tt><b>OUTPUT</b></tt> keywords instead of <tt><b>READ</b></tt> and <tt><b>WRITE</b></tt>, then the process is executed inside a virtual terminal. It means that the process will think running inside a true terminal.
<p>
Lastly, you can get a reference to the internal <a href="../comp/gb/process%3Fen">Process</a> object created by using an assignment.
<p>
If you use the second syntax, the command is executed, the interpreter waiting for its end, and the complete command output is put in the specified string.
<p>
<div class="gray"><font color="white" size="-2"><b>Example</b></font></div>
<pre class="example">' Get the content of a directory

SHELL &quot;ls -la /tmp&quot; WAIT</pre>
<p>
<div class="gray"><font color="white" size="-2"><b>Example</b></font></div>
<pre class="example">' Same thing, but in background

DIM Content AS String

EXEC &quot;ls -la /tmp&quot; FOR READ

...

PUBLIC SUB Process_Read()

  DIM sLine AS String

  LINE INPUT #LAST, sLine

  Content = Content & sLine
  PRINT sLine

END</pre>
<p>
<div class="warning"><table class="none" border="0"><tr><td width="40" valign="top"><img border="0" src="../../img/info.png" align="center"></td><td valign="top">
</pre>If you want to know how many bytes you can read in a <tt>Process_Read</tt> event handler, use the <a href="lof%3Fen">Lof</a> function.<pre>
</td></tr></table></div>
<p>
<div class="warning"><table class="none" border="0"><tr><td width="40" valign="top"><img border="0" src="../../img/warning.png" align="center"></td><td valign="top">
As arguments are sent to a shell, you have to quote them, as if you type a command directly in it.
<p>
<div class="gray"><font color="white" size="-2"><b>Example</b></font></div>
<pre class="example">SHELL &quot;perl -e 'print while <>;'&quot; FOR READ WRITE</pre>
</td></tr></table></div>
<p>
<div class="warning"><table class="none" border="0"><tr><td width="40" valign="top"><img border="0" src="../../img/info.png" align="center"></td><td valign="top">
You may have noticed that all <a href="../comp/gb/process%3Fen">Process</a> events fire the same event handlers, namely Process_Read, Process_Kill, etc.
<p>
You can differentiate between processes in two ways:
<ul>
<li>Make each <a href="../comp/gb/process%3Fen">Process</a> object global to your class and use <tt><a href="if%3Fen">IF</a> <a href="last%3Fen">LAST</a> = Process1 <a href="then%3Fen">THEN</a>...</tt>
<li>Use <a href="../comp/gb/object%3Fen">Object</a>.<a href="../comp/gb/object/attach%3Fen">Attach</a> to change the event name of the <a href="../comp/gb/process%3Fen">Process</a> object and redirect its events to a different set of handlers.
</ul>

</td></tr></table></div>
<p>
<div class="warning"><table class="none" border="0"><tr><td width="40" valign="top"><img border="0" src="../../img/vb.png" align="center"></td><td valign="top">
Unlike the VB Shell command, which returns a process ID and relies on the programmer to make API calls to control the process, the <a href="../def/gambas%3Fen">Gambas</a> Shell function optionally returns a <a href="../comp/gb/process%3Fen">Process</a> object (if used as an assignment to a variable declared <a href="as%3Fen">AS</a> <a href="../comp/gb/process%3Fen">Process</a>) which can be used to directly kill or otherwise control the spawned process.  Additionally, the process may be run synchronously or asynchronously, in contrast to the VB equivalent.
</td></tr></table></div>
<p>
<hr><b>See also</b><br>
<a href="../cat/process%3Fen">Process Management</a>&nbsp;&nbsp; <a href="../comp/gb/process%3Fen">Process</a>&nbsp;&nbsp; <a href="lof%3Fen">Lof</a>&nbsp;&nbsp;

</div>
<hr>
</body>
</html>

