<!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 - PIPE
</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="pi+en">Previous</a>&nbsp;
<a href="print+en">Next</a>&nbsp;
</td></tr></table>
<div class="notab">
<h1>
PIPE
</h1>
<div class="black"><font size="-2"><b>Syntax</b></font></div>
<pre class="syntax"><u>hStream</u> <b>= PIPE</b> <u>sPipeName</u> <b>FOR</b> [ <b>READ</b> ] [ <b>WRITE</b> ] [ <b>WATCH</b> ]</pre><p>

Opens a named pipe for reading, writing or creating. If the pipe does not exist it will be automatically created.
<p>
A pipe provides unidirectional flow of communication between processes within the same system. In other words, they are half-duplex, that is, data flows in only one direction.
<p>
One major feature of a pipe is that the data flowing through the communication medium is transient -
data once read from the read descriptor cannot be read again.
Also, if we write data continuously into the write descriptor,
then we will be able to read the data only in the order in which the data was written.
<p>
However, a pipe has to be open at both ends simultaneously before you can proceed to do any input or output operations on it. Opening a pipe for reading normally blocks until some other process opens the same pipe for writing.
<p>
<a href="../def/gambas+en">Gambas</a> implements a FIFO(First-In, First-out) pipe. For further information look at MKFIFO in the <a href="../def/linux+en">Linux</a>/ Unix manual pages.
<p>
<ul>
<li>If the <tt><b>READ</b></tt> keyword is specified, then the pipe is opened for reading.
<p>
<li>If the <tt><b>WRITE</b></tt> keyword is specified, then the pipe is opened for writing.
<p>
<li>If the <tt><b>WATCH</b></tt> keyword is specified, the pipe is watched by the interpreter&nbsp;:
<ul>
<li>If at least one byte can be read from the file, then the event handler <tt>Pipe_Read()</tt> is called.
<li>If at least one byte can be written into the file, then the event handler <tt>Pipe_Write()</tt> is called.
<p>
</ul>
</ul>

If the pipe is successfully opened, a <a href="../def/stream+en">stream</a> <a href="../def/object+en">object</a> is returned to the variable <u>hStream</u>.
<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">
Pipe streams are never buffered.
</td></tr></table></div>
<p>
<div class="gray"><font size="-2"><b>Errors</b></font></div>
<table class="table" border="0" bordercolor="#000000" cellpadding="6" cellspacing="0" width="100%">
<tr><th>Message</th><th>Description</th></tr><tr class="dark"><td valign="top">
<a href="../error/access+en">Access forbidden (#43)</a>
</td><td valign="top">
The  requested access to the pipe is not allowed, or search permission is denied for one of the directories in the path  prefix of  pathname,  or write access to the parent directory is not  allowed.
</td></tr>
<tr><td valign="top">
<p>
<a href="../error/full+en">Device is full (#37)</a>
</td><td valign="top">
<u>File name</u> was to be created but the  device  containing  <u>Pipe name</u> has no room for the new file.
</td></tr>
<tr class="dark"><td valign="top">
<a href="../error/ndir+en">Not a directory (#49)</a>
</td><td valign="top">
A  component  used as a directory in <u>Pipe name</u> is not, in fact, a directory.
</td></tr>
<tr><td valign="top">
<a href="../error/system+en">System error... (#42)</a>
</td><td valign="top">
Other possible system errors:
<ul>
<li>Too many symbolic links were encountered in resolving path.
<li>The length of the path argument exceeds maximum path or a pathname component is longer than maximum name.
<li>A component of the path prefix specified by path does not name an existing directory or path is an empty string.
<li>The directory that would contain the new file cannot be extended or the file system is out of file-allocation resources.
<li>The  system limit  on  the  total number of open files has been reached.
<li><u>Pipe name</u> refers to a file on a read-only  filesystem  and  write access was requested.
</ul>

</td></tr>
</table>
<p>
<div class="gray"><font size="-2"><b>Example</b></font></div>
<pre class="example">' Prints the messages sent to a pipe

DIM hFile AS File
DIM sLine AS String

hFile = PIPE &quot;/tmp/FIFO1&quot; FOR INPUT

WHILE NOT Eof(hFile)
  LINE INPUT #hFile, sLine
  PRINT sLine
WEND

Start the above running in one window then do : ls > /tmp/FIFO1</pre>
<p>
<hr><b>See also</b><br>
<a href="../cat/stream+en">Stream &amp; Input/Output functions</a>&nbsp;
<a href="../cat/file+en">File &amp; Directory Functions</a>&nbsp;
<a href="../comp/gb/stream+en">Stream</a>&nbsp;

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

