<!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 - OPEN
</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="null+en">Previous</a>&nbsp;
<a href="optional+en">Next</a>&nbsp;
</td></tr></table>
<div class="notab">
<h1>
OPEN
</h1>
<div class="black"><font size="-2"><b>Syntax</b></font></div>
<pre class="syntax"><u>hStream</u> <b>= OPEN</b> <u>sFileName</u> <b>FOR</b> [ <b>READ</b> | <b>INPUT</b> ] [ <b>WRITE</b> | <b>OUTPUT</b> ] [ <b>CREATE</b> | <b>APPEND</b> ] [ <b>WATCH</b> ]</pre><p>

Opens a file for reading, writing, creating or appending data. The file must exist, unless the <tt><b>CREATE</b></tt> keyword is specified.
<p>
<ul>
<li>If the <tt><b>CREATE</b></tt> keyword is specified, then the file is created, or cleared if it already exists.
<p>
<li>If the <tt><b>APPEND</b></tt> keyword is specified, then the file pointer is moved to the end of file just after the file is opened.
<p>
<li>If the <tt><b>READ</b></tt> or <tt><b>WRITE</b></tt> keyword are specified, then the input-output are not buffered.
<p>
<li>If the <tt><b>INPUT</b></tt> or <tt><b>OUTPUT</b></tt> keyword are specified, then the input-output are buffered.
<p>
<li>If the <tt><b>WATCH</b></tt> keyword is specified, the file is watched by the interpreter&nbsp;:
<ul>
<li>If at least one byte can be read from the file, then the event handler <tt>File_Read()</tt> is called.
<li>If at least one byte can be written into the file, then the event handler <tt>File_Write()</tt> is called.
<p>
</ul>
</ul>

If the file 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">
By default, streams are buffered.
<p>
If you want to have an unbuffered <a href="../def/stream+en">stream</a>, you must use the <tt><b>READ</b></tt> or <tt><b>WRITE</b></tt> keyword explicitely.
</td></tr></table></div>
<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 other Basic dialects, <a href="../def/gambas+en">Gambas</a> will never delete a file
when it is opened by the <tt><b>WRITE</b></tt> keyword for instance.
&nbsp;So if the new contents is smaller than the old one,
some garbage of the old file version will remain at the end of the new file.
To avoid this, open the file including the <tt><b>CREATE</b></tt> keyword.
</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 file is not allowed,
or search permission is denied for one of the
directories in the path prefix of pathname, or the
file did not exist yet and write access to the parent directory is not  allowed.
</td></tr>
<tr><td valign="top">
<a href="../error/dir+en">File is a directory (#46)</a>
</td><td valign="top">
<u>File name</u> refers to a directory.
</td></tr>
<tr class="dark"><td valign="top">
<a href="../error/nexist+en">File or directory does not exist (#45)</a>
</td><td valign="top">
<u>File name</u> does not exist, or a directory component in pathname does not exist or is a dangling symbolic link.
</td></tr>
<tr><td valign="top">
<a href="../error/memory+en">Out of memory (#1)</a>
</td><td valign="top">
The system ran out of memory.
</td></tr>
<tr class="dark"><td valign="top">
<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>File name</u> has no room for the new file.
</td></tr>
<tr><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>File name</u> is not, in fact, a directory.
</td></tr>
<tr class="dark"><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 <u>File name</u>.
<li>The process already has the maximum number of files open.
<li>The  system limit  on  the  total number of open files has been reached.
<li><u>File name</u> refers to a device special file  and  no  corresponding device  exists.
<li>The named file is a named pipe and no process has the file open for reading.
<li><u>File name</u> refers to a file on a read-only  filesystem  and  write access was requested.
<li><u>File name</u> refers to an executable image which is currently being executed 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 contents of a text file to the screen

DIM hFile AS File
DIM sLine AS String

hFile = OPEN &quot;/etc/passwd&quot; FOR INPUT

WHILE NOT Eof(hFile)
  LINE INPUT #hFile, sLine
  PRINT sLine
WEND</pre>
<div class="gray"><font size="-2"><b>Example</b></font></div>
<pre class="example">' Watching a serial port

DIM hFile AS File

hFile = OPEN &quot;/dev/ttyS0&quot; FOR READ WRITE WATCH

...

PUBLIC SUB File_Read()

  DIM iByte AS Byte

  READ #hFile, iByte
  PRINT &quot;Got one byte: &quot;; iByte

END</pre>
<div class="gray"><font size="-2"><b>Example</b></font></div>
<pre class="example">' Reading data from a BMP file, known to use little-endian format :

DIM hFile AS File
DIM iData AS Integer

hFile = OPEN &quot;image.bmp&quot; FOR INPUT
hFile.ByteOrder = gb.LittleEndian
...
READ #hFile, iData</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>

