\section{P\+H\+Y\+S\+F\+S\+\_\+\+Io Struct Reference}
\label{structPHYSFS__Io}\index{P\+H\+Y\+S\+F\+S\+\_\+\+Io@{P\+H\+Y\+S\+F\+S\+\_\+\+Io}}


An abstract i/o interface.  




{\ttfamily \#include $<$physfs.\+h$>$}

\subsection*{Data Fields}
\begin{DoxyCompactItemize}
\item 
\textbf{ P\+H\+Y\+S\+F\+S\+\_\+uint32} \textbf{ version}
\begin{DoxyCompactList}\small\item\em Binary compatibility information. \end{DoxyCompactList}\item 
void $\ast$ \textbf{ opaque}
\begin{DoxyCompactList}\small\item\em Instance data for this struct. \end{DoxyCompactList}\item 
\textbf{ P\+H\+Y\+S\+F\+S\+\_\+sint64}($\ast$ \textbf{ read} )(struct \textbf{ P\+H\+Y\+S\+F\+S\+\_\+\+Io} $\ast$io, void $\ast$buf, \textbf{ P\+H\+Y\+S\+F\+S\+\_\+uint64} len)
\begin{DoxyCompactList}\small\item\em Read more data. \end{DoxyCompactList}\item 
\textbf{ P\+H\+Y\+S\+F\+S\+\_\+sint64}($\ast$ \textbf{ write} )(struct \textbf{ P\+H\+Y\+S\+F\+S\+\_\+\+Io} $\ast$io, const void $\ast$buffer, \textbf{ P\+H\+Y\+S\+F\+S\+\_\+uint64} len)
\begin{DoxyCompactList}\small\item\em Write more data. \end{DoxyCompactList}\item 
int($\ast$ \textbf{ seek} )(struct \textbf{ P\+H\+Y\+S\+F\+S\+\_\+\+Io} $\ast$io, \textbf{ P\+H\+Y\+S\+F\+S\+\_\+uint64} offset)
\begin{DoxyCompactList}\small\item\em Move i/o position to a given byte offset from start. \end{DoxyCompactList}\item 
\textbf{ P\+H\+Y\+S\+F\+S\+\_\+sint64}($\ast$ \textbf{ tell} )(struct \textbf{ P\+H\+Y\+S\+F\+S\+\_\+\+Io} $\ast$io)
\begin{DoxyCompactList}\small\item\em Report current i/o position. \end{DoxyCompactList}\item 
\textbf{ P\+H\+Y\+S\+F\+S\+\_\+sint64}($\ast$ \textbf{ length} )(struct \textbf{ P\+H\+Y\+S\+F\+S\+\_\+\+Io} $\ast$io)
\begin{DoxyCompactList}\small\item\em Determine size of the i/o instance\textquotesingle{}s dataset. \end{DoxyCompactList}\item 
struct \textbf{ P\+H\+Y\+S\+F\+S\+\_\+\+Io} $\ast$($\ast$ \textbf{ duplicate} )(struct \textbf{ P\+H\+Y\+S\+F\+S\+\_\+\+Io} $\ast$io)
\begin{DoxyCompactList}\small\item\em Duplicate this i/o instance. \end{DoxyCompactList}\item 
int($\ast$ \textbf{ flush} )(struct \textbf{ P\+H\+Y\+S\+F\+S\+\_\+\+Io} $\ast$io)
\begin{DoxyCompactList}\small\item\em Flush resources to media, or wherever. \end{DoxyCompactList}\item 
void($\ast$ \textbf{ destroy} )(struct \textbf{ P\+H\+Y\+S\+F\+S\+\_\+\+Io} $\ast$io)
\begin{DoxyCompactList}\small\item\em Cleanup and deallocate i/o instance. \end{DoxyCompactList}\end{DoxyCompactItemize}


\subsection{Detailed Description}
An abstract i/o interface. 

\begin{DoxyWarning}{Warning}
This is advanced, hardcore stuff. You don\textquotesingle{}t need this unless you really know what you\textquotesingle{}re doing. Most apps will not need this.
\end{DoxyWarning}
Historically, Physics\+FS provided access to the physical filesystem and archives within that filesystem. However, sometimes you need more power than this. Perhaps you need to provide an archive that is entirely contained in R\+AM, or you need to bridge some other file i/o A\+PI to Physics\+FS, or you need to translate the bits (perhaps you have a a standard .zip file that\textquotesingle{}s encrypted, and you need to decrypt on the fly for the unsuspecting zip archiver).

A \doxyref{P\+H\+Y\+S\+F\+S\+\_\+\+Io}{p.}{structPHYSFS__Io} is the interface that Archivers use to get archive data. Historically, this has mapped to file i/o to the physical filesystem, but as of Physics\+FS 2.\+1, applications can provide their own i/o implementations at runtime.

This interface isn\textquotesingle{}t necessarily a good universal fit for i/o. There are a few requirements of note\+:


\begin{DoxyItemize}
\item They only do blocking i/o (at least, for now).
\item They need to be able to duplicate. If you have a file handle from fopen(), you need to be able to create a unique clone of it (so we have two handles to the same file that can both seek/read/etc without stepping on each other).
\item They need to know the size of their entire data set.
\item They need to be able to seek and rewind on demand.
\end{DoxyItemize}

...in short, you\textquotesingle{}re probably not going to write an H\+T\+TP implementation.

Thread safety\+: \doxyref{P\+H\+Y\+S\+F\+S\+\_\+\+Io}{p.}{structPHYSFS__Io} implementations are not guaranteed to be thread safe in themselves. Under the hood where Physics\+FS uses them, the library provides its own locks. If you plan to use them directly from separate threads, you should either use mutexes to protect them, or don\textquotesingle{}t use the same \doxyref{P\+H\+Y\+S\+F\+S\+\_\+\+Io}{p.}{structPHYSFS__Io} from two threads at the same time.

\begin{DoxySeeAlso}{See also}
\doxyref{P\+H\+Y\+S\+F\+S\+\_\+mount\+Io}{p.}{physfs_8h_a7ac107cf895f50f0d2219cdf44b8b758} 
\end{DoxySeeAlso}


\subsection{Field Documentation}
\mbox{\label{structPHYSFS__Io_a7c444d656db5b0a5fe61b9476d0643f7}} 
\index{P\+H\+Y\+S\+F\+S\+\_\+\+Io@{P\+H\+Y\+S\+F\+S\+\_\+\+Io}!destroy@{destroy}}
\index{destroy@{destroy}!P\+H\+Y\+S\+F\+S\+\_\+\+Io@{P\+H\+Y\+S\+F\+S\+\_\+\+Io}}
\subsubsection{destroy}
{\footnotesize\ttfamily void($\ast$ P\+H\+Y\+S\+F\+S\+\_\+\+Io\+::destroy) (struct \textbf{ P\+H\+Y\+S\+F\+S\+\_\+\+Io} $\ast$io)}



Cleanup and deallocate i/o instance. 

Free associated resources, including (opaque) if applicable.

This function must always succeed\+: as such, it returns void. The system may call your \doxyref{flush()}{p.}{structPHYSFS__Io_adf157fcf4bd5d9c7a738d1b8964688cd} method before this. You may report failure there if necessary. This method may still be called if \doxyref{flush()}{p.}{structPHYSFS__Io_adf157fcf4bd5d9c7a738d1b8964688cd} fails, in which case you\textquotesingle{}ll have to abandon unflushed data and other failing conditions and clean up.

Once this method is called for a given instance, the system will assume it is unsafe to touch that instance again and will discard any references to it.


\begin{DoxyParams}{Parameters}
{\em s} & The i/o instance to destroy. \\
\hline
\end{DoxyParams}
\mbox{\label{structPHYSFS__Io_af8ab04d1e1492a2bd480cce6132fc44b}} 
\index{P\+H\+Y\+S\+F\+S\+\_\+\+Io@{P\+H\+Y\+S\+F\+S\+\_\+\+Io}!duplicate@{duplicate}}
\index{duplicate@{duplicate}!P\+H\+Y\+S\+F\+S\+\_\+\+Io@{P\+H\+Y\+S\+F\+S\+\_\+\+Io}}
\subsubsection{duplicate}
{\footnotesize\ttfamily struct \textbf{ P\+H\+Y\+S\+F\+S\+\_\+\+Io}$\ast$($\ast$ P\+H\+Y\+S\+F\+S\+\_\+\+Io\+::duplicate) (struct \textbf{ P\+H\+Y\+S\+F\+S\+\_\+\+Io} $\ast$io)}



Duplicate this i/o instance. 

This needs to result in a full copy of this \doxyref{P\+H\+Y\+S\+F\+S\+\_\+\+Io}{p.}{structPHYSFS__Io}, that can live completely independently. The copy needs to be able to perform all its operations without altering the original, including either object being destroyed separately (so, for example\+: they can\textquotesingle{}t share a file handle; they each need their own).

If you can\textquotesingle{}t duplicate a handle, it\textquotesingle{}s legal to return N\+U\+LL, but you almost certainly need this functionality if you want to use this to \doxyref{P\+H\+Y\+S\+F\+S\+\_\+\+Io}{p.}{structPHYSFS__Io} to back an archive.


\begin{DoxyParams}{Parameters}
{\em io} & The i/o instance to duplicate. \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
A new value for a stream\textquotesingle{}s (opaque) field, or N\+U\+LL on error. 
\end{DoxyReturn}
\mbox{\label{structPHYSFS__Io_adf157fcf4bd5d9c7a738d1b8964688cd}} 
\index{P\+H\+Y\+S\+F\+S\+\_\+\+Io@{P\+H\+Y\+S\+F\+S\+\_\+\+Io}!flush@{flush}}
\index{flush@{flush}!P\+H\+Y\+S\+F\+S\+\_\+\+Io@{P\+H\+Y\+S\+F\+S\+\_\+\+Io}}
\subsubsection{flush}
{\footnotesize\ttfamily int($\ast$ P\+H\+Y\+S\+F\+S\+\_\+\+Io\+::flush) (struct \textbf{ P\+H\+Y\+S\+F\+S\+\_\+\+Io} $\ast$io)}



Flush resources to media, or wherever. 

This is the chance to report failure for writes that had claimed success earlier, but still had a chance to actually fail. This method can be N\+U\+LL if flushing isn\textquotesingle{}t necessary.

This function may be called before \doxyref{destroy()}{p.}{structPHYSFS__Io_a7c444d656db5b0a5fe61b9476d0643f7}, as it can report failure and \doxyref{destroy()}{p.}{structPHYSFS__Io_a7c444d656db5b0a5fe61b9476d0643f7} can not. It may be called at other times, too.


\begin{DoxyParams}{Parameters}
{\em io} & The i/o instance to flush. \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
Zero on error, non-\/zero on success. 
\end{DoxyReturn}
\mbox{\label{structPHYSFS__Io_a193b2182d7101533d68afd4ba385e2b8}} 
\index{P\+H\+Y\+S\+F\+S\+\_\+\+Io@{P\+H\+Y\+S\+F\+S\+\_\+\+Io}!length@{length}}
\index{length@{length}!P\+H\+Y\+S\+F\+S\+\_\+\+Io@{P\+H\+Y\+S\+F\+S\+\_\+\+Io}}
\subsubsection{length}
{\footnotesize\ttfamily \textbf{ P\+H\+Y\+S\+F\+S\+\_\+sint64}($\ast$ P\+H\+Y\+S\+F\+S\+\_\+\+Io\+::length) (struct \textbf{ P\+H\+Y\+S\+F\+S\+\_\+\+Io} $\ast$io)}



Determine size of the i/o instance\textquotesingle{}s dataset. 

Return number of bytes available in the file, or -\/1 if you aren\textquotesingle{}t able to determine. A failure will almost certainly be fatal to further use of this stream, so you may not leave this unimplemented.


\begin{DoxyParams}{Parameters}
{\em io} & The i/o instance to query. \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
Total size, in bytes, of the dataset. 
\end{DoxyReturn}
\mbox{\label{structPHYSFS__Io_ad5feb5c1c53823a89e339832961e76fa}} 
\index{P\+H\+Y\+S\+F\+S\+\_\+\+Io@{P\+H\+Y\+S\+F\+S\+\_\+\+Io}!opaque@{opaque}}
\index{opaque@{opaque}!P\+H\+Y\+S\+F\+S\+\_\+\+Io@{P\+H\+Y\+S\+F\+S\+\_\+\+Io}}
\subsubsection{opaque}
{\footnotesize\ttfamily void$\ast$ P\+H\+Y\+S\+F\+S\+\_\+\+Io\+::opaque}



Instance data for this struct. 

Each instance has a pointer associated with it that can be used to store anything it likes. This pointer is per-\/instance of the stream, so presumably it will change when calling \doxyref{duplicate()}{p.}{structPHYSFS__Io_af8ab04d1e1492a2bd480cce6132fc44b}. This can be deallocated during the \doxyref{destroy()}{p.}{structPHYSFS__Io_a7c444d656db5b0a5fe61b9476d0643f7} method. \mbox{\label{structPHYSFS__Io_aaec94416bfe259ef747c2fe09ac110c0}} 
\index{P\+H\+Y\+S\+F\+S\+\_\+\+Io@{P\+H\+Y\+S\+F\+S\+\_\+\+Io}!read@{read}}
\index{read@{read}!P\+H\+Y\+S\+F\+S\+\_\+\+Io@{P\+H\+Y\+S\+F\+S\+\_\+\+Io}}
\subsubsection{read}
{\footnotesize\ttfamily \textbf{ P\+H\+Y\+S\+F\+S\+\_\+sint64}($\ast$ P\+H\+Y\+S\+F\+S\+\_\+\+Io\+::read) (struct \textbf{ P\+H\+Y\+S\+F\+S\+\_\+\+Io} $\ast$io, void $\ast$buf, \textbf{ P\+H\+Y\+S\+F\+S\+\_\+uint64} len)}



Read more data. 

Read (len) bytes from the interface, at the current i/o position, and store them in (buffer). The current i/o position should move ahead by the number of bytes successfully read.

You don\textquotesingle{}t have to implement this; set it to N\+U\+LL if not implemented. This will only be used if the file is opened for reading. If set to N\+U\+LL, a default implementation that immediately reports failure will be used.


\begin{DoxyParams}{Parameters}
{\em io} & The i/o instance to read from. \\
\hline
{\em buf} & The buffer to store data into. It must be at least (len) bytes long and can\textquotesingle{}t be N\+U\+LL. \\
\hline
{\em len} & The number of bytes to read from the interface. \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
number of bytes read from file, 0 on E\+OF, -\/1 if complete failure. 
\end{DoxyReturn}
\mbox{\label{structPHYSFS__Io_a2e63ce07597ac7899c562cdbcb26aac4}} 
\index{P\+H\+Y\+S\+F\+S\+\_\+\+Io@{P\+H\+Y\+S\+F\+S\+\_\+\+Io}!seek@{seek}}
\index{seek@{seek}!P\+H\+Y\+S\+F\+S\+\_\+\+Io@{P\+H\+Y\+S\+F\+S\+\_\+\+Io}}
\subsubsection{seek}
{\footnotesize\ttfamily int($\ast$ P\+H\+Y\+S\+F\+S\+\_\+\+Io\+::seek) (struct \textbf{ P\+H\+Y\+S\+F\+S\+\_\+\+Io} $\ast$io, \textbf{ P\+H\+Y\+S\+F\+S\+\_\+uint64} offset)}



Move i/o position to a given byte offset from start. 

This method moves the i/o position, so the next read/write will be of the byte at (offset) offset. Seeks past the end of file should be treated as an error condition.


\begin{DoxyParams}{Parameters}
{\em io} & The i/o instance to seek. \\
\hline
{\em offset} & The new byte offset for the i/o position. \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
non-\/zero on success, zero on error. 
\end{DoxyReturn}
\mbox{\label{structPHYSFS__Io_a56f3c06a280033c3db6d416dd080345c}} 
\index{P\+H\+Y\+S\+F\+S\+\_\+\+Io@{P\+H\+Y\+S\+F\+S\+\_\+\+Io}!tell@{tell}}
\index{tell@{tell}!P\+H\+Y\+S\+F\+S\+\_\+\+Io@{P\+H\+Y\+S\+F\+S\+\_\+\+Io}}
\subsubsection{tell}
{\footnotesize\ttfamily \textbf{ P\+H\+Y\+S\+F\+S\+\_\+sint64}($\ast$ P\+H\+Y\+S\+F\+S\+\_\+\+Io\+::tell) (struct \textbf{ P\+H\+Y\+S\+F\+S\+\_\+\+Io} $\ast$io)}



Report current i/o position. 

Return bytes offset, or -\/1 if you aren\textquotesingle{}t able to determine. A failure will almost certainly be fatal to further use of this stream, so you may not leave this unimplemented.


\begin{DoxyParams}{Parameters}
{\em io} & The i/o instance to query. \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
The current byte offset for the i/o position, -\/1 if unknown. 
\end{DoxyReturn}
\mbox{\label{structPHYSFS__Io_aeeacb84ee2afaa3ef4012d54ecef7273}} 
\index{P\+H\+Y\+S\+F\+S\+\_\+\+Io@{P\+H\+Y\+S\+F\+S\+\_\+\+Io}!version@{version}}
\index{version@{version}!P\+H\+Y\+S\+F\+S\+\_\+\+Io@{P\+H\+Y\+S\+F\+S\+\_\+\+Io}}
\subsubsection{version}
{\footnotesize\ttfamily \textbf{ P\+H\+Y\+S\+F\+S\+\_\+uint32} P\+H\+Y\+S\+F\+S\+\_\+\+Io\+::version}



Binary compatibility information. 

This must be set to zero at this time. Future versions of this struct will increment this field, so we know what a given implementation supports. We\textquotesingle{}ll presumably keep supporting older versions as we offer new features, though. \mbox{\label{structPHYSFS__Io_a19d2faf6a0c7e5f0f40d2d15be9ebb23}} 
\index{P\+H\+Y\+S\+F\+S\+\_\+\+Io@{P\+H\+Y\+S\+F\+S\+\_\+\+Io}!write@{write}}
\index{write@{write}!P\+H\+Y\+S\+F\+S\+\_\+\+Io@{P\+H\+Y\+S\+F\+S\+\_\+\+Io}}
\subsubsection{write}
{\footnotesize\ttfamily \textbf{ P\+H\+Y\+S\+F\+S\+\_\+sint64}($\ast$ P\+H\+Y\+S\+F\+S\+\_\+\+Io\+::write) (struct \textbf{ P\+H\+Y\+S\+F\+S\+\_\+\+Io} $\ast$io, const void $\ast$buffer, \textbf{ P\+H\+Y\+S\+F\+S\+\_\+uint64} len)}



Write more data. 

Write (len) bytes from (buffer) to the interface at the current i/o position. The current i/o position should move ahead by the number of bytes successfully written.

You don\textquotesingle{}t have to implement this; set it to N\+U\+LL if not implemented. This will only be used if the file is opened for writing. If set to N\+U\+LL, a default implementation that immediately reports failure will be used.

You are allowed to buffer; a write can succeed here and then later fail when flushing. Note that \doxyref{P\+H\+Y\+S\+F\+S\+\_\+set\+Buffer()}{p.}{physfs_8h_aede5de47197e1a613d2091802befc886} may be operating a level above your i/o, so you should usually not implement your own buffering routines.


\begin{DoxyParams}{Parameters}
{\em io} & The i/o instance to write to. \\
\hline
{\em buffer} & The buffer to read data from. It must be at least (len) bytes long and can\textquotesingle{}t be N\+U\+LL. \\
\hline
{\em len} & The number of bytes to read from (buffer). \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{Returns}
number of bytes written to file, -\/1 if complete failure. 
\end{DoxyReturn}


The documentation for this struct was generated from the following file\+:\begin{DoxyCompactItemize}
\item 
\textbf{ physfs.\+h}\end{DoxyCompactItemize}
