Using Binary Files

Table of Contents

• Reading Files
  • Opening a Binary File
  • Reading from the file
• Writing Files
  • Creating a Binary File
  • Writing to the file
• File Position
  • Getting the current file position
  • Setting the current file position (Seeking)
• Default vs 32-bit vs 64-bit
  • Default
  • 32-bit
  • 64-bit

Reading Files

Opening a Binary File

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

fplFileHandle fileHandle;
if (fplFileOpenBinary("myimage.jpg", &fileHandle)) {
 
    // ... read data
 
    fplFileClose(&fileHandle);
}

Note

Call fplFileClose() 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 fplFileReadBlock() with your filehandle and a buffer to read into.

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

Writing Files

Creating a Binary File

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

fplFileHandle fileHandle;
if (fplFileCreateBinary("myimage.jpg", &fileHandle)) {
 
    // ... write data
 
    fplFileClose(&fileHandle);
}

Note

Call fplFileClose() 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 fplFileWriteBlock() with your filehandle and the buffer you want to write.

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

File Position

Getting the current file position

Call fplFileGetPosition() to get the current file position from an opened fplFileHandle .

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

Setting the current file position (Seeking)

Call fplFileSetPosition() to set the current file position on an opened fplFileHandle .

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

Default vs 32-bit vs 64-bit

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

• 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:

• fplFileSetPosition() maps to fplFileSetPosition32() or fplFileSetPosition64()
• fplFileGetPosition() maps to fplFileGetPosition32() or fplFileGetPosition64()
• fplFileReadBlock() maps to fplFileReadBlock32() or fplFileReadBlock64()
• fplFileWriteBlock() maps to fplFileWriteBlock32() or fplFileWriteBlock64()
• fplFileGetSizeFromPath() maps to fplFileGetSizeFromPath32() or fplFileGetSizeFromPath64()
• fplFileGetSizeFromHandle() maps to fplFileGetSizeFromHandle32() or fplFileGetSizeFromHandle64()

32-bit

Limited to 32-bit:

• fplFileSetPosition32()
• fplFileGetPosition32()
• fplFileReadBlock32()
• fplFileWriteBlock32()
• fplFileGetSizeFromPath32()
• fplFileGetSizeFromHandle32()

64-bit

Up to 2-TB (64-bit):

• fplFileSetPosition64()
• fplFileGetPosition64()
• fplFileReadBlock64()
• fplFileWriteBlock64()
• fplFileGetSizeFromPath64()
• fplFileGetSizeFromHandle64()