====== LoadFile ======

Loads a cel file from disk

==== Synopsis ====

''%%void * LoadFile (char *fileName, long *fileSizePtr, uint32 memTypeBits)%%''

==== Description ====

Loads an entire file into a buffer in memory. This function allocates a buffer, loads the file into it, and returns a pointer to the allocated buffer. The size of the file is returned into a longword via the fileSizePtr parameter.

Note that the buffer is allocated to an even multiple of the device's blocksize (2 KB for CD-ROM and the Mac link), and thus may be slightly larger than the actual size of the file. The file size returned via fileSizePtr, however, reflects the actual size of the file without the extra padding required to achieve an integral device block size.

This function is approximately 3-4 times as fast as the old method of loading a file using ''%%GetFileSize()%%'', allocating a buffer, calling ''%%ReadFile()%%''. When you are finished with the file, use ''%%UnloadFile()%%'' to free the file buffer.

If an error returns, the function return value is NULL and the longword at the *fileSizePtr contains the error status. A return value of NULL with an error status of zero indicates that the file exists but contains no data; in this cas, no buffer was allocated.

==== Arguments ====

  * **fileName** Pointer to the file name string.

  * **fileSizePtr** Pointer to a longword which receives the length of file (in bytes). If you don't need the length, a NULL pointer can be passed for this parameter.

  * **memTypeBits** Type of memory to use when loading the file; usually MEMTYPE_ANY or MEMTYPE_VRAM.

==== Return Value ====

Pointer to loaded file in memory, or NULL if an error occurred.

==== Associated Files ====

lib3do.lib, blockfile.h

==== See Also ====

[[:documentation:development:opera:pf25:ppgfldr:smmfldr:ldofldr:01ldo203#xref19907|''%%UnloadFile%%'']], [[:documentation:development:opera:pf25:ppgfldr:smmfldr:ldofldr:01ldo116#xref11782|LoadFileHere]], [[:documentation:development:opera:pf25:ppgfldr:smmfldr:ldofldr:01ldo002#xref32442|AsyncLoadFile]]