266 6. Resources and the File System
back and forth between absolute and relative paths, and so on. It can be ex-
tremely helpful to have a feature-rich API to help with these tasks.
Microsoft Windows provides an API for this purpose. It is implement-
ed by the dynamic link library shlwapi.dll, and exposed via the header
fi le shlwapi.h. Complete documentation for this API is provided on the
Microsoft Developer’s Network (MSDN) at the following URL: htt p://msdn2.
microsoft .com/en-us/library/bb773559(VS.85).aspx.
Of course, the shlwapi API is only available on Win32 platforms. Sony
provides a similar API for use on the PLAYSTATION 3. But when writing a
cross-platform game engine, we cannot use platform-specifi c APIs directly. A
game engine may not need all of the functions provided by an API like sh-
lwapi anyway. For these reasons, game engines oft en implement a stripped-
down path-handling API that meets the engine’s particular needs and works
on every operating system targeted by the engine. Such an API can be imple-
mented as a thin wrapper around the native API on each platform or it can be
writt en from scratch.6.1.2. Basic File I/O
The standard C library provides two APIs for opening, reading, and writing
the contents of fi les—one buff ered and the other unbuff ered. Every fi le I/O
API requires data blocks known as buff ers to serve as the source or destination
of the bytes passing between the program and the fi le on disk. We say a fi le
I/O API is buff ered when the API manages the necessary input and output data
buff ers for you. With an unbuff ered API, it is the responsibility of the pro-
grammer using the API to allocate and manage the data buff ers. The standard
C library’s buff ered fi le I/O routines are sometimes referred to as the stream
I/O API, because they provide an abstraction which makes disk fi les look like
streams of bytes.
The standard C library functions for buff ered and un-buff ered fi le I/O are
listed in Table 6.1.
The standard C library I/O functions are well-documented, so we will not
repeat detailed documentation for them here. For more information, please
refer to htt p://msdn2.microsoft .com/en-us/library/c565h7xx(VS.71).aspx for
Microsoft ’s implementation of the buff ered (stream I/O) API, and to htt p://
msdn2.microsoft .com/en-us/library/40bbyw78(VS.71).aspx for Microsoft ’s
implementation of the unbuff ered (low-level I/O) API.
On UNIX and its variants, the standard C library’s unbuff ered I/O routes
are native operating system calls. However, on Microsoft Windows these rou-
tines are merely wrappers around an even lower-level API. The Win32 func-
tion CreateFile() creates or opens a fi le for writing or reading, ReadFile()