Subversion Repositories shark

%----------------------------------------------------------------------------
\chapter{The File Management}
%----------------------------------------------------------------------------

S.Ha.R.K. provides a built-in File System that currently supports Hard Disk
Drivers and FAT16 partitions.

If you are using the DOS eXtender X to run the application, you can use some
callback to the DOS 0x21 interrupt, to write/read some bytes from the
filesystem \footnote{These callbacks are useful when you don't have any
partition that can be read by the filesystem... for example when running
S.Ha.R.K. applications from a FAT32 filesystem!}. These functions directly
interact with the underlying DOS, and can not be used when the system is in
protected mode. In particular, you can only use these functions into the
\_\_kernel\_register\_levels\_\_() function and in the RUNLEVEL\_AFTER\_EXIT
exit functions.

In the case of errors, a \texttt{NULL} or zero value is returned;
\texttt{DOS\_ferror()} can be used to get the DOS error code; the header file
\texttt{<ll/i386/x-dos.h>} must be included to use these functions. A running
(we hope) well documented example can be foun in the \texttt{demos/dosfs}
directory.

\vspace{7mm}

\begin{intest}
DOS\_FOPEN\index{DOS\_fopen()}
\end{intest}

\begin{description}
\item [\textbf{DOS\_FILE {*}DOS\_fopen(char {*}name, char {*}mode);}]
\item [\textbf{Description:}] It opens a file and returns a pointer to a file structure.
The \texttt{name} parameter contains the name of the file to be opened. The
\texttt{mode} parameter contains a string whose value can be one of the
following constants: {}``r'' to read, {}``w'' to write, and {}``rw'' to read and
write. In the case of error, \texttt{NULL} is returned; otherwise the returned
value can be used as last parameter in the functions listed below.
\end{description}

\begin{intest}
DOS\_FCLOSE\index{DOS\_fclose()}
\end{intest}

\begin{description}
\item [\textbf{void DOS\_fclose(DOS\_FILE {*}f);}]
\item [\textbf{Description:}] It closes the specified file and releases all allocated DOS
resources.
\end{description}

\begin{intest}
DOS\_FREAD\index{DOS\_fread()}
\end{intest}

\begin{description}
\item [\textbf{DWORD DOS\_fread(void {*}buf, DWORD size, DWORD num, DOS\_FILE {*}f);}]
\item [\textbf{Description:}] It reads \texttt{num} objects of \texttt{size} bytes from
file \texttt{f} and place them in a buffer pointed by \texttt{buf}. This
function returns the actual number of bytes read from the file (it can be less
than $num*size$ bytes). Zero is returned if an error occurs or
\textit{end-of-file} is found.
\end{description}

\begin{intest}
DOS\_FWRITE\index{DOS\_fwrite()}
\end{intest}

\begin{description}
\item [\textbf{DWORD DOS\_fwrite(void {*}buf,DWORD size,DWORD num,DOS\_FILE {*}f);}]
\item [\textbf{Description:}] It writes \texttt{num} objects of \texttt{size} bytes into
file \texttt{f}. Data are picked from the buffer pointed by \texttt{buf}. This
function returns the actual number of bytes written (it can be less than
$num*size$ bytes). Zero is returned if an error occurs.
\end{description}

\begin{intest}
DOS\_ERROR\index{DOS\_error()}
\end{intest}

\begin{description}
\item [\textbf{unsigned DOS\_error(void);}]
\item [\textbf{Description:}] Returns the error code of the latest \texttt{DOS\_xxx}
function.
\end{description}