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}