\section{FOPEN File Open Function}

\subsection{Usage}

Opens a file and returns a handle which can be used for subsequent
file manipulations.  The general syntax for its use is
\begin{verbatim}
  fp = fopen(fname,mode,byteorder)
\end{verbatim}
Here \verb|fname| is a string containing the name of the file to be 
opened.  \verb|mode| is the mode string for the file open command.
The first character of the mode string is one of the following:
\begin{itemize}
\item  \verb|'r'|  Open  file  for  reading.  The file pointer is placed at
          the beginning of the file.  The file can be read from, but
	  not written to.

\item  \verb|'r+'|   Open for reading and writing.  The file pointer is
          placed at the beginning of the file.  The file can be read
	  from and written to, but must exist at the outset.

\item  \verb|'w'|    Open file for writing.  If the file already exists, it is
          truncated to zero length.  Otherwise, a new file is
	  created.  The file pointer is placed at the beginning of
	  the file.

\item  \verb|'w+'|   Open for reading and writing.  The file is created  if  
          it  does not  exist, otherwise it is truncated to zero
	  length.  The file pointer placed at the beginning of the file.

\item  \verb|'a'|    Open for appending (writing at end of file).  The file  is  
          created  if it does not exist.  The file pointer is placed at
	  the end of the file.

\item  \verb|'a+'|   Open for reading and appending (writing at end of file).   The
          file  is created if it does not exist.  The file pointer is
	  placed at the end of the file.

\end{itemize}
On some platforms (e.g. Win32) it is necessary to add a 'b' for 
binary files to avoid the operating system's 'CR/LF<->CR' translation.

Finally, FreeMat has the ability to read and write files of any
byte-sex (endian).  The third (optional) input indicates the 
byte-endianness of the file.  If it is omitted, the native endian-ness
of the machine running FreeMat is used.  Otherwise, the third
argument should be one of the following strings:
\begin{itemize}
\item  \verb|'le','ieee-le','little-endian','littleEndian','little'|

\item  \verb|'be','ieee-be','big-endian','bigEndian','big'|

\end{itemize}
	
If the file cannot be opened, or the file mode is illegal, then
an error occurs. Otherwise, a file handle is returned (which is
an integer).  This file handle can then be used with \verb|fread|,
\verb|fwrite|, or \verb|fclose| for file access.

Note that three handles are assigned at initialization time:
\begin{itemize}
\item  Handle 0 - is assigned to standard input

\item  Handle 1 - is assigned to standard output

\item  Handle 2 - is assigned to standard error

\end{itemize}
These handles cannot be closed, so that user created file handles start at \verb|3|.

\subsection{Examples}

Here are some examples of how to use \verb|fopen|.  First, we create a new 
file, which we want to be little-endian, regardless of the type of the machine.
We also use the \verb|fwrite| function to write some floating point data to
the file.
\begin{verbatim}
--> fp = fopen('test.dat','wb','ieee-le')

fp = 

 8 

--> fwrite(fp,float([1.2,4.3,2.1]))

ans = 

 3 

--> fclose(fp)

ans = 

 0 


\end{verbatim}
Next, we open the file and read the data back
\begin{verbatim}
--> fp = fopen('test.dat','rb','ieee-le')

fp = 

 8 

--> fread(fp,[1,3],'float')

ans = 

    1.2000    4.3000    2.1000 

--> fclose(fp)

ans = 

 0 


\end{verbatim}
Now, we re-open the file in append mode and add two additional \verb|float|s to the
file.
\begin{verbatim}
--> fp = fopen('test.dat','a+','le')

fp = 

 8 

--> fwrite(fp,float([pi,e]))

ans = 

 2 

--> fclose(fp)

ans = 

 0 


\end{verbatim}
Finally, we read all 5 \verb|float| values from the file
\begin{verbatim}
--> fp = fopen('test.dat','rb','ieee-le')

fp = 

 8 

--> fread(fp,[1,5],'float')

ans = 

    1.2000    4.3000    2.1000    3.1416    2.7183 

--> fclose(fp)

ans = 

 0 


\end{verbatim}
