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.
}
fpl_platform_api void fplFileClose(fplFileHandle *fileHandle)
Closes the given file and releases the underlying resources and clears the handle to zero.
fpl_platform_api bool fplFileOpenBinary(const char *filePath, fplFileHandle *outHandle)
Opens a binary file for reading from a string path and returns the handle of it.
The filehandle structure.
- 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;
size_t read;
char fourCC[4];
jpeg_header jpegHeader;
size_t read;
read =
fplFileReadBlock(&fileHandle,
sizeof(jpegHeader), &jpegHeader,
sizeof(jpegHeader));
}
#define fplAssert(exp)
Breaks with an runtime assertion, when the specified expression evaluates to false.
fpl_platform_api size_t fplFileReadBlock(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.
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 overridden automatically.
}
fpl_platform_api bool fplFileCreateBinary(const char *filePath, fplFileHandle *outHandle)
Create a binary file for writing to the given string path and returns the handle of it.
- 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.
char *saveGameFilePath = ...
char savegameFourCC[4] = {'S', 'A', 'V', 'E'};
uint8_t *savegameDataPtr = ...;
size_t savegameDataSize = ...;
}
fpl_common_api size_t fplFileWriteBlock(const fplFileHandle *fileHandle, void *sourceBuffer, const size_t sourceSize)
Writes a block to the given file and returns the number of written bytes.
File Position
Getting the current file position
Call fplFileGetPosition() to get the current file position from a opened fplFileHandle .
fpl_common_api size_t fplFileGetPosition(const fplFileHandle *fileHandle)
Gets the current file position in bytes.
Setting the current file position (Seeking)
Call fplFileSetPosition() to set the current file position on a opened fplFileHandle .
fpl_common_api size_t fplFileSetPosition(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...
@ fplFilePositionMode_Beginning
Starts from the beginning.
@ fplFilePositionMode_Current
Starts from the current position.
@ fplFilePositionMode_End
Starts from the 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):