mirror of https://github.com/dzavalishin/oskit/
133 lines
4.7 KiB
TeX
Executable File
133 lines
4.7 KiB
TeX
Executable File
%
|
|
% Copyright (c) 1997-1998 University of Utah and the Flux Group.
|
|
% All rights reserved.
|
|
%
|
|
% The University of Utah grants you the right to copy and reproduce this
|
|
% document or portions thereof for academic, research, evaluation, and
|
|
% personal use only, provided that (1) the title page appears prominently,
|
|
% and (2) these copyright and permission notices are retained in all copies.
|
|
% To arrange for alternate terms, contact the University of Utah at
|
|
% csl-dist@cs.utah.edu or +1-801-585-3271.
|
|
%
|
|
\label{fsread}
|
|
|
|
\section{Introduction}
|
|
|
|
The \texttt{fsread} library provides simple read-only access to
|
|
Linux ext2fs, BSD FFS, and MINIX filesystems and is useful for small programs,
|
|
such as boot loaders, that need to read files from the local disk but
|
|
don't have the space for or need the features of the larger \oskit{}
|
|
filesystem libraries.
|
|
|
|
Typically this library is used with the disk partitioning library
|
|
(Section~\ref{diskpart}) and one of the driver libraries.
|
|
|
|
\section{External dependencies}
|
|
|
|
This depends on several memory and string routines from the \oskit{} C library,
|
|
more specifically it depends on
|
|
|
|
% nm -u liboskit_fsread.a | sort -u
|
|
\begin{itemize}
|
|
\item \texttt{free}, \texttt{malloc}
|
|
\item \texttt{memcpy}, \texttt{memmove}, \texttt{memset}
|
|
\item \texttt{oskit_blkio_iid}, \texttt{oskit_iunknown_iid}
|
|
\item \texttt{strcmp}, \texttt{strcpy}, \texttt{strncpy}
|
|
\end{itemize}
|
|
|
|
\section{Limitations}
|
|
|
|
\begin{itemize}
|
|
\item Absolute symbolic links are interpreted relative to the root of the FS,
|
|
since the FS readers have no notion of a ``global root.''
|
|
\item For ext2fs, the ``sb'' mount option is not supported,
|
|
the super block is assumed to be at block 1.
|
|
\item The MINIX support has not been tested in the \oskit{}.
|
|
but worked in a previous incarnation in Mach.
|
|
\end{itemize}
|
|
|
|
\section{API reference}
|
|
|
|
Each of these functions takes an
|
|
\texttt{oskit_blkio_t} (Section~\ref{oskit-blkio})
|
|
interface to the underlying device
|
|
and a pathname relative to the root directory of the file system,
|
|
and if the specified file can be found,
|
|
returns an \texttt{oskit_blkio_t} object that can be used to
|
|
read from that file.
|
|
The \texttt{blkio} object returned will have a block size of 1,
|
|
meaning that there are no alignment restrictions on file reads.
|
|
The \texttt{blkio} object passed, representing the underlying device,
|
|
can have a block size greater than 1,
|
|
but if it is larger than the file system's block size,
|
|
file system interpretation will fail.
|
|
Also, any absolute symlinks followed during the open
|
|
will be interpreted as if this is the root file system.
|
|
|
|
\api{fsread_open}{Open a file on various filesystems}
|
|
\begin{apisyn}
|
|
\cinclude{oskit/fs/read.h}
|
|
|
|
\funcproto oskit_error_t fsread_open(oskit_blkio_t *device,
|
|
const~char *path,
|
|
\outparam oskit_blkio_t **out_file);
|
|
\end{apisyn}
|
|
\begin{apidesc}
|
|
Tries to open a file named by \emph{path} in the filesystem
|
|
on \emph{device}.
|
|
If successful, returns a \texttt{blkio} into \emph{out_file}
|
|
that can be used to read the file.
|
|
|
|
This function is just a wrapper that calls the various
|
|
filesystem-specific \texttt{fsread} functions,
|
|
failing if none of them recognize the filesystem.
|
|
\end{apidesc}
|
|
\begin{apiparm}
|
|
\item[device]
|
|
An \texttt{oskit_blkio_t} (Section~\ref{oskit-blkio})
|
|
representing a device containing a filesystem.
|
|
\item[path]
|
|
A pathname indicating an existing file to open.
|
|
This pathname is taken relative to the root of the filesystem
|
|
\item[out_file]
|
|
Upon success, this is set to an \texttt{oskit_blkio_t}
|
|
that can be used to read from the file.
|
|
\end{apiparm}
|
|
\begin{apiret}
|
|
Returns 0 on success, or an error code specified in
|
|
{\tt <oskit/error.h>}, on error.
|
|
\end{apiret}
|
|
|
|
\api{fsread_\emph{FSTYPE}_open}{Open a file on the \emph{FSTYPE} filesystem}
|
|
\begin{apisyn}
|
|
\cinclude{oskit/fs/read.h}
|
|
|
|
\funcproto oskit_error_t fsread_\emph{FSTYPE}_open(oskit_blkio_t *device,
|
|
const~char *path,
|
|
\outparam oskit_blkio_t **out_file);
|
|
\end{apisyn}
|
|
\begin{apidesc}
|
|
Tries to open a file named by \emph{path} in the
|
|
\emph{FSTYPE} filesystem
|
|
on \emph{device}.
|
|
If successful, returns a \texttt{blkio} into \emph{out_file}
|
|
that can be used to read the file.
|
|
|
|
\emph{FSTYPE} can be one of \texttt{ext2}, \texttt{ffs}, \texttt{minix}.
|
|
\end{apidesc}
|
|
\begin{apiparm}
|
|
\item[device]
|
|
An \texttt{oskit_blkio_t} (Section~\ref{oskit-blkio})
|
|
representing a device containing a \emph{FSTYPE} filesystem.
|
|
\item[path]
|
|
A pathname indicating an existing file to open.
|
|
This pathname is taken relative to the root of the filesystem
|
|
\item[out_file]
|
|
Upon success, this is set to an \texttt{oskit_blkio_t}
|
|
that can be used to read from the file.
|
|
\end{apiparm}
|
|
\begin{apiret}
|
|
Returns 0 on success, or an error code specified in
|
|
{\tt <oskit/error.h>}, on error.
|
|
\end{apiret}
|