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.
A7.76 For not loading a file, but only finding its path, give a buffer pointer and a size pointer that points at 0. If the file was found in the path, path_name is set to the path name and *size is set to the length of the file.
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.
...

STRING* find_pathname(STRING* filename)
{
  int size = 0;
  file_load(chr_(filename),&size,&size);
  if (size > 0) 
    return path_name;
  else
    return NULL; // file not found in path
}

See also:

file_save, add_buffer ► latest version online