file_load

file_load(char* name,void* buffer,long* size)

Opens the file with the given name, reads it into the buffer, and closes the file.

Parameters:

name - file name, or NULL for deallocating the given buffer.
buffer - pointer to a preallocated buffer, or NULL. If NULL is given, a buffer is allocated by the engine.
size - pointer to a long variable, set to the file length, or NULL.

Returns:

Pointer to the buffer, or NULL if the instruction failed.

Modifies:

buffer, size

Remarks:

This instruction is intended for lite-C and for external languages and thus uses char* and long* instead of STRING* and var*.
The file is looked for first in the named buffers (see add_buffer), then in the path and then - if it's extension is ".pak" - in the WRS resource path.
If the file was found in the named buffers, size is set to 0.
If a buffer pointer is passed to the function , its size must be given by the size pointer. If the size of the file exceeds the size of the buffer, nothing is read and NULL is returned.
If a buffer was allocated by the engine, it must be deallocated by file_load(NULL,buffer,NULL); before terminating the application.

Speed:

slow

Example:

void* pTerrain = file_load("terrain.hmp",NULL,&size);
add_buffer("terrain1.hmp",pTerrain,size);
...
file_load(NULL,pTerrain,NULL); // free the buffer before exiting the application.

See also:

file_save, add_buffer ► latest version online