Final Platform Layer  0.9.6-beta
Using Binary Files

Reading Files

Opening a Binary File

To open a binary file, simply declare a fplFileHandle somewhere and call fplOpenBinaryFile() with a valid UTF-8 path to open it.

fplFileHandle fileHandle;
if (fplOpenBinaryFile("myimage.jpg", &fileHandle)) {
// ... read data
fplCloseFile(&fileHandle);
}
Note
Call fplCloseFile() to close a file when you are done.

Reading from the file

To read a block of n-bytes from the file starting from the current file position, simply call fplReadFileBlock() with your filehandle and a buffer to read into.

struct jpeg_header; // defined somewhere
fplFileHandle fileHandle;
if (fplOpenBinaryFile("myimage.jpg", &fileHandle)) {
size_t read;
// Read the first 4 characters
char fourCC[4];
read = fplReadFileBlock(&fileHandle, 4, fourCC, sizeof(fourCC));
fplAssert(read == 4);
// or
// Read a JPEG-Header
jpeg_header jpegHeader;
size_t read;
read = fplReadFileBlock(&fileHandle, sizeof(jpegHeader), &jpegHeader, sizeof(jpegHeader));
fplAssert(read == sizeof(jpegHeader));
fplCloseFile(&fileHandle);
}

Writing Files

Creating a Binary File

To create a binary file, simply declare a fplFileHandle somewhere and call fplCreateBinaryFile() with a valid UTF-8 path to open it.
If the file already exists, it will be overridden automatically.

fplFileHandle fileHandle;
if (fplCreateBinaryFile("myimage.jpg", &fileHandle)) {
// ... write data
fplCloseFile(&fileHandle);
}
Note
Call fplCloseFile() to close a file when you are done.

Writing to the file

To write n-bytes of memory into an opened file beginning at the current file position, simply call fplWriteFileBlock() with your filehandle and the buffer you want to write.

fplFileHandle fileHandle;
char *saveGameFilePath = ...
if (fplCreateBinaryFile(saveGameFilePath, &fileHandle)) {
char savegameFourCC[4] = {'S', 'A', 'V', 'E'};
uint8_t *savegameDataPtr = ...;
size_t savegameDataSize = ...;
// Write a savegame
fplWriteFileBlock(&fileHandle, savegameFourCC, 4);
fplWriteFileBlock(&fileHandle, savegameDataPtr, savegameDataSize);
fplCloseFile(&fileHandle);
}

File Position

Getting the current file position

Call fplGetFilePosition() to get the current file position from a opened fplFileHandle .

fplFileHandle fileHandle = ...
size_t curPos = fplGetFilePosition(&fileHandle);

Setting the current file position (Seeking)

Call fplSetFilePosition() to set the current file position on a opened fplFileHandle .

fplFileHandle fileHandle = ...
// Seek 4-bytes forwards from the current position
fplSetFilePosition(&fileHandle, 4, fplFilePositionMode_Current);
// Seek 8-bytes backwards from the current position
// Seek to the 128-byte from the beginning (Absolute seeking)
// Seek to the start of the file
// Seek to the end of the file (Get file length)
size_t fileLength = fplSetFilePosition(&fileHandle, 0, fplFilePositionMode_End);

Default vs 32-bit vs 64-bit

There are three versions for file reading/writing and seekings:

  • A version which uses uint32_t or int32_t (32-bit only, Limited to 2 GB of file = 2^31).
  • A version which uses uint64_t or int64_t (64-bit only, Limited to 2 TB of file = 2^63).
  • A default version which uses size_t or intptr_t always and use either the 32-bit or the 64-bit, depending on the compiled CPU-Architecture.

    See the next sections for more details.

Default

Uses either 32-bit or the 64-bit, depending on the compiled CPU architecture:

32-bit

Limited to 32-bit:

64-bit

Up to 2-TB (64-bit):

fplCloseFile
fpl_platform_api void fplCloseFile(fplFileHandle *fileHandle)
Closes the given file and releases the underlying resources and clears the handle to zero.
fplFilePositionMode_End
Starts from the end.
Definition: final_platform_layer.h:5069
fplFilePositionMode_Current
Starts from the current position.
Definition: final_platform_layer.h:5067
fplReadFileBlock
fpl_platform_api size_t fplReadFileBlock(const fplFileHandle *fileHandle, const size_t sizeToRead, void *targetBuffer, const size_t maxTargetBufferSize)
Reads a block from the given file and returns the number of bytes read.
fplAssert
#define fplAssert(exp)
Breaks with an runtime assertion, when the specified expression evaluates to false.
Definition: final_platform_layer.h:2081
fplGetFilePosition
fpl_common_api size_t fplGetFilePosition(const fplFileHandle *fileHandle)
Gets the current file position in bytes.
fplCreateBinaryFile
fpl_platform_api bool fplCreateBinaryFile(const char *filePath, fplFileHandle *outHandle)
Create a binary file for writing to the given string path and returns the handle of it.
fplFilePositionMode_Beginning
Starts from the beginning.
Definition: final_platform_layer.h:5065
fplWriteFileBlock
fpl_common_api size_t fplWriteFileBlock(const fplFileHandle *fileHandle, void *sourceBuffer, const size_t sourceSize)
Writes a block to the given file and returns the number of written bytes.
fplSetFilePosition
fpl_common_api size_t fplSetFilePosition(const fplFileHandle *fileHandle, const intptr_t position, const fplFilePositionMode mode)
Sets the current file position by the given position, depending on the mode it's absolute or relative...
fplFileHandle
The filehandle structure.
Definition: final_platform_layer.h:5055
fplOpenBinaryFile
fpl_platform_api bool fplOpenBinaryFile(const char *filePath, fplFileHandle *outHandle)
Opens a binary file for reading from a string path and returns the handle of it.