<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en" dir="ltr">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../../style.css">
<title>
Gambas Documentation - SHELL
</title>
</head>
<table class="none" width="100%" cellpadding="0" cellspacing="0" border="0">
<tr><td align="left">
<font size="-1">
<a href="../../help+en"><img class="flag" alt="Home" border="0" src="../../img/lang/en.png" align="center"></a>&nbsp;
<a href="../lang+en">Up</a>&nbsp;
<a href="sgn+en">Previous</a>&nbsp;
<a href="shl+en">Next</a>&nbsp;
</td></tr></table>
<div class="notab">
<h1>
SHELL
</h1>
<div class="black"><font 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> } } ] [ <b>AS</b> <u>Name</u> ]<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+en">Process</a> <a href="../def/object+en">object</a> 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+en">Process</a> <a href="../def/object+en">object</a> with common output instructions: <a href="print+en">PRINT</a>, <a href="write+en">WRITE</a>, ... Note that you need a reference to the <a href="../comp/gb/process+en">Process</a> <a href="../def/object+en">object</a> 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+en">Read</a> is raised when data are sent to the standard output <a href="../def/stream+en">stream</a>, and the event <a href="../comp/gb/process/_error+en">Error</a> is raised when data are sent to the standard error <a href="../def/stream+en">stream</a>. Use the process <a href="../def/object+en">object</a> with <a href="../cat/stream+en">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>
<tt><u>Name</u></tt> is the event name used by the <a href="../comp/gb/process+en">Process</a> <a href="../def/object+en">object</a>. By default, it is <tt>&quot;Process&quot;</tt>.
<p>
You can get a reference to the internal <a href="../comp/gb/process+en">Process</a> <a href="../def/object+en">object</a> 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 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 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

  READ #LAST, sLine, -256

  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+en">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 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/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+en">Gambas</a> Shell function optionally returns a <a href="../comp/gb/process+en">Process</a> <a href="../def/object+en">object</a> (if used as an assignment to a variable declared <a href="as+en">AS</a> <a href="../comp/gb/process+en">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+en">Process Management</a>&nbsp; <a href="../comp/gb/process+en">Process</a>&nbsp; <a href="lof+en">Lof</a>&nbsp;

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

