BRender Technical Reference Manual:3 Functions (Structured Reference):Filing System Support
Next|Prev|Up
Standard Filing System Services
BrFileAttributes()
BrFileOpenWrite()
BrFileWrite()
BrFilePrintf()
BrFilePutLine()
BrFilePutChar()
BrFileOpenRead()
BrFileRead()
BrFileGetLine()
BrFileGetChar()
BrFileAdvance()
BrFileEOF()
BrFileClose()
Special Filing System Services
BrWriteModeSet()

Filing System Support


Standard Filing System Services

BRender provides a set of filing system services very similar to those provided in the standard C library. All filing should be performed using these functions, so that on platforms where there is no standard C library or where the filing system is based on an unusual media such as cartridge, calls to load various items will still succeed. In some cases it may be necessary to have some read operations accessing a CD-ROM and some read/write operations accessing a memory card (not that one expects to store much in a memory card).

Note that BRender will recognise an environment variable (in some systems) called BRENDER_PATH, which will be used, if defined, to extend the search for unqualified file names beyond the current directory.

For background information on the following functions, read any standard C library documentation that you may have.


BrFileAttributes()

Description:
Determine capabilities of the filing system.

Declaration:
br_uint_32 BrFileAttributes(void)

Preconditions:
Filing system handler dependent. BRender's default filing system requires BRender to have completed initialisation.

Effects:
Interrogates filing system.

Result:
br_uint_32

The attributes of the filing system; its capabilities as defined by a combination of the following flag values:




BrFileOpenWrite()

Description:
Open a file for writing, over-writing any existing file of the same name.

Declaration:
void* BrFileOpenWrite(const char* name, int mode)

Arguments:
const char * name

Name to open file as.

int mode

Mode in which to open file (BR_FS_MODE_TEXT or BR_FS_MODE_BINARY). In the default implementation of the filing system (using the standard C library), this is effectively turned into a "w" or "wb" write mode parameter to fopen().

Preconditions:
Filing system handler dependent. BRender's default filing system requires BRender to have completed initialisation.

Effects:
Overwrite or create file using specified name and mode.

Result:
void *

Return a file handle or Null if the file could not be opened.

Remarks:
In the default implementation, when a file is opened for writing in text mode, `end of file' (EOF, Ctrl-Z, 0x1A) characters may have special significance, and `line feed' (LF, Ctrl-J, 0x0A, `\n') characters may be translated to `carriage return, line feed' combinations. Consult your Standard C library documentation.


BrFileWrite()

Description:
Write a block of data to a file.

Declaration:
int BrFileWrite(const void* buf, int size, int n, void* f)

Arguments:
const void * buf

Buffer containing block to be written.

int size

Size of each element in block.

int n

Maximum number of elements to write.

void * f

Valid file handle - as returned by BrFileOpenWrite()57.

Preconditions:
Filing system handler dependent. BRender's default filing system requires BRender to have completed Initialisation.

Effects:
Write up to n elements from buf to the file f.

Result:
int

Return the number of complete elements written, which may be less than n if an error occurs (such as running out of file space).

Remarks:
The data written to the file may be affected by the current `write mode' of the file.


BrFilePrintf()

Description:
Write a formatted string to a file.

Declaration:
int BrFilePrintf(void* f, const char* fmt, ...)

Arguments:
void * f

Valid file handle - as returned by BrFileOpenWrite()57.

const char * fmt

Format string as supplied to printf().

...

Any further necessary parameters as would be required in printf().

Preconditions:
Filing system handler dependent. BRender's default filing system requires BRender to have completed initialisation.

Effects:
Write the string to the file (effectively using vsprintf()).

Result:
int

Returns the number of characters written, or a negative value if an error occurs.

Remarks:
The data written to the file may be affected by the current `write mode' of the file.

See Also:
Consult your Standard C library documentation.


BrFilePutLine()

Description:
Write a line of text to a file, followed by writing the new-line character (`\n').

Declaration:
void BrFilePutLine(const char* buf, void* f)

Arguments:
const char * buf

Pointer to zero terminated string containing line of text to be written.

void * f

Valid file handle - as returned by BrFileOpenWrite()57.

Preconditions:
Filing system handler dependent. BRender's default filing system requires BRender to have completed initialisation.

Effects:
Write the string to the file. Write the new-line character to the file (`\n').

Remarks:
The data written to the file may be affected by the current `write mode' of the file.

See Also:
Consult your Standard C library documentation.


BrFilePutChar()

Description:
Write a single character to a file.

Declaration:
void BrFilePutChar(int c, void* f)

Arguments:
int c

Character to write.

void * f

Valid file handle - as returned by BrFileOpenWrite()57.

Preconditions:
Filing system handler dependent. BRender's default filing system requires BRender to have completed initialisation.

Effects:
Write the character to the file.

Remarks:
The data written to the file may be affected by the current `write mode' of the file.

See Also:
Consult your Standard C library documentation.


BrFileOpenRead()

Description:
Open a file for read access.

Declaration:
void* BrFileOpenRead(const char* name, br_size_t n_magics, br_mode_test_cbfn* mode_test, int* mode_result)

Arguments:
const char * name

Name of file.

br_size_t n_magics

Number of characters required for mode_test to determine file type (less than or equal to BR_MAX_FILE_MAGICS).

br_mode_test_cbfn * mode_test

Call-back function that can be used to determine file type given the first n_magics characters of a file. Will not be used if Null.

int * mode_result

If this argument is non-Null, the file type (if it could be determined) will be stored at the address pointed to.

Preconditions:
Filing system handler dependent. BRender's default filing system requires BRender to have completed Initialisation.

Effects:
Searches for a file called name, if no path is specified with the file, looks in the current directory, if not found tries, in order, the directories listed in BRENDER_PATH (if defined). Having found the file, use mode_test (if supplied) to find out if the file is text, binary or unknown. Store the result through mode_result (if non-Null). Obtain a handle to the file.

Result:
void *

Return a file handle, or Null if the file could not be opened.

See Also:
Consult your Standard C library documentation.


BrFileRead()

Description:
Read a block of data from a file.

Declaration:
int BrFileRead(void* buf, int size, int n, void* f)

Arguments:
void * buf

Buffer to receive block.

int size

Size of each element in block.

int n

Maximum number of elements to read.

void * f

Valid file handle - as returned by BrFileOpenRead()60.

Preconditions:
Filing system handler dependent. BRender's default filing system requires BRender to have completed initialisation.

Effects:
Read up to n elements of size bytes from the file f and store them in buf.

Result:
br_size_t

Return the number of complete elements read, which may be less than n if the end of file is encountered before all the elements could be read.

Remarks:
The data read from the file may be affected by the `write mode' used to write the file.

See Also:
Consult your Standard C library documentation.


BrFileGetLine()

Description:
Read a line of text (excluding terminators) from a file.

Declaration:
int BrFileGetLine(char* buf, br_size_t buf_len, void* f)

Arguments:
char * buf

Buffer to hold text read.

br_size_t buf_len

Length of buffer (maximum number of characters to store - including `\0').

void * f

Valid file handle - as returned by BrFileOpenRead()60.

Preconditions:
Filing system handler dependent. BRender's default filing system requires BRender to have completed Initialisation.

Effects:
Read characters into supplied buffer until buf_len-1 characters have been read, end of line has been read, or end of file has been reached. If the last character read was `\n' it is removed from the buffer.

Result:
int

The number of characters stored in the buffer is returned. If at the end of file upon entry, zero will be returned.

Remarks:
The data read from the file may be affected by the `write mode' used to write the file.

See Also:
Consult your Standard C library documentation.


BrFileGetChar()

Description:
Read a character from a file.

Declaration:
int BrFileGetChar(void* f)

Arguments:
void * f

Valid file handle - as returned by BrFileOpenRead()60.

Preconditions:
Filing system handler dependent. BRender's default filing system requires BRender to have completed initialisation.

Effects:
If the file position is at the end of the file, the file enters the end-of-file state, otherwise a character is read and the file position is advanced.

Result:
int

The character read from the file is returned (as though the character had been cast as (int)(unsigned char)). If a character could not be read because the file position was at the end of the file, BR_EOF is returned.

Remarks:
The data read from the file may be affected by the `write mode' used to write the file.

See Also:
Consult your Standard C library documentation.


BrFileAdvance()

Description:
Advance the file pointer a number of bytes through a binary stream.

Declaration:
void BrFileAdvance(long int count, void* f)

Arguments:
long int count

Number of bytes to advance.

void * f

Valid file handle - as returned by BrFileOpenRead()60 and BrFileOpenWrite()57.

Preconditions:
Filing system handler dependent. BRender's default filing system requires BRender to have completed initialisation.

Effects:
Advance file position by count bytes.

Remarks:
This function may be affected by the `write mode' used to write the file. If the `write mode' is BR_FS_MODE_TEXT, the accuracy of the file pointer is not guaranteed (unless count is zero).

See Also:
Consult your Standard C library documentation.


BrFileEOF()

Description:
Test a file pointer for end of file.

Declaration:
int BrFileEof(const void* f)

Arguments:
const void * f

Valid file handle - as returned by BrFileOpenRead()60 and BrFileOpenWrite()57.

Preconditions:
Filing system handler dependent. BRender's default filing system requires BRender to have completed initialisation.

Effects:
None.

Result:
int

Returns a non-zero value after the first read operation that attempts to read past the end of the file. It returns 0 if the current position is not end of file.

Remarks:
This function may be affected by the `write mode' used to write the file. If the `write mode' is BR_FS_MODE_TEXT, the result may indicate end-of-file upon reaching an EOF character.

See Also:
Consult your Standard C library documentation.


BrFileClose()

Description:
Close a previously opened file.

Declaration:
void BrFileClose(void* f)

Arguments:
void * f

Valid file handle - as returned by BrFileOpenRead()60 and BrFileOpenWrite()57.

Preconditions:
Filing system handler dependent. BRender's default filing system requires BRender to have completed initialisation.

Effects:
Close file.

See Also:
Consult your Standard C library documentation.


Special Filing System Services

BRender allows the application to specify how the various export functions should write data to files. Text mode will write data in ASCII, using text labels and expanding numbers into strings. Text mode files are primarily used for debugging but can be useful to allow hand editing of input data. Binary mode will cause exported data to be written in binary, i.e. a more compact, unreadable form.


BrWriteModeSet()

Description:
Instruct BRender to output data files in text or binary for subsequent `Save' operations.

Declaration:
int BrWriteModeSet(int mode)

Arguments:
int mode

Write mode. Either BR_FS_MODE_TEXT or BR_FS_MODE_BINARY.

Effects:
Records the mode with which BRender should subsequently open files for writing and how data should be written to them. This will affect export functions such as BrModelSave()245.

Result:
int

Returns the old write mode.

Remarks:
The purpose of this function is primarily to indicate to BRender how it should output its data files, whether in compact binary form or in vaguely human readable, ASCII form.

If the application produces binary and text files then it will specify the write mode upon opening a file for writing.

When opening a file for read, it is opened in the same mode as it was written.



Generated with CERN WebMaker