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.

 fileHandle;
if (("myimage.jpg", &fileHandle)) {

    // ... read data

    (&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
 fileHandle;
if (("myimage.jpg", &fileHandle)) {
    size_t read;

    // Read the first 4 characters
    char fourCC[4];
    read = (&fileHandle, 4, fourCC, sizeof(fourCC));
    (read == 4);

    // or

    // Read a JPEG-Header
    jpeg_header jpegHeader;
    size_t read;
    read = (&fileHandle, sizeof(jpegHeader), &jpegHeader, sizeof(jpegHeader));
    (read == sizeof(jpegHeader));
    (&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.

 fileHandle;
if (("myimage.jpg", &fileHandle)) {

    // ... write data

    (&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.

 fileHandle;
char *saveGameFilePath = ...
if ((saveGameFilePath, &fileHandle)) {
    char savegameFourCC[4] = {'S', 'A', 'V', 'E'};
    uint8_t *savegameDataPtr = ...;
    size_t savegameDataSize = ...;

    // Write a savegame
    (&fileHandle, savegameFourCC, 4);
    (&fileHandle, savegameDataPtr, savegameDataSize);

    (&fileHandle);
}

File Position

Getting the current file position

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

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

Setting the current file position (Seeking)

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

 fileHandle = ...
// Seek 4-bytes forwards from the current position
fplFileSetPosition(&fileHandle, 4, );

// Seek 4-bytes backwards from the current position
(&fileHandle, -4, );

// Seek to the 128-byte from the beginning (Absolute seeking)
(&fileHandle, 128, );

// Seek to the start of the file
(&fileHandle, 0, );

// Seek to the end of the file (Get file length)
size_t fileLength = (&fileHandle, 0, );

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()