- Generated by
1.9.8
|
CX Framework
Cross-platform C utility framework
|
Data Structures | |
| struct | File |
Macros | |
| #define | fileClose(pfile) (unused_noeval(&((*(pfile))->_is_File)), _fileClose((File**)(pfile))) |
| #define | fileWriteString(self, str, byteswritten) File_writeString(File(self), str, byteswritten) |
| #define | fileRead(self, buf, sz, bytesread) ((self) ? ((self)->_->read(File(self), buf, sz, bytesread)) : false) |
| #define | fileWrite(self, buf, sz, byteswritten) ((self) ? ((self)->_->write(File(self), buf, sz, byteswritten)) : false) |
| #define | fileTell(self) ((self) ? ((self)->_->tell(File(self))) : -1) |
| #define | fileSeek(self, off, seektype) ((self) ? ((self)->_->seek(File(self), off, seektype)) : -1) |
| #define | fileFlush(self) ((self) ? ((self)->_->flush(File(self))) : false) |
Typedefs | |
| typedef File | FSFile |
| A file opened on the OS filesystem with fsOpen() | |
| typedef enum FSSeekTypeEnum | FSSeekType |
| typedef struct File | File |
Enumerations | |
| enum | FSOpenFlags { FS_Read = 1 , FS_Write = 2 , FS_Create = 4 , FS_Truncate = 8 , FS_Lock = 16 , FS_Overwrite = (FS_Write | FS_Create | FS_Truncate) } |
| enum | FSSeekTypeEnum { FS_Set = 0x00010000 , FS_Cur = 0x00020000 , FS_End = 0x00030000 } |
Functions | |
| FSFile * | fsOpen (strref path, flags_t flags) |
| bool | fsRead (FSFile *file, void *buf, size_t sz, size_t *bytesread) |
| bool | fsWrite (FSFile *file, const void *buf, size_t sz, size_t *byteswritten) |
| bool | fsWriteString (FSFile *file, strref str, size_t *byteswritten) |
| int64 | fsTell (FSFile *file) |
| int64 | fsSeek (FSFile *file, int64 off, FSSeekType seektype) |
| bool | fsFlush (FSFile *file) |
Provides direct access to the operating system's file I/O APIs for synchronous read/write operations. This is a thin wrapper around platform-native file handles with minimal buffering.
Key characteristics:
An open file is a File object no matter which layer opened it, so FSFile and VFSFile are both just other names for File. A function that reads and writes can take a File* and be handed either one; the type does not record where the handle came from.
The fs* calls below and the vfs* calls in vfs.h are the same operations as fileRead(), fileWrite() and the rest, under names that say which layer the file was opened through. Which spelling you use is a matter of readability.
For higher-level filesystem operations (directories, metadata), see fs.h. For virtual filesystem abstraction, see vfs.h.
| #define fileClose | ( | pfile | ) | (unused_noeval(&((*(pfile))->_is_File)), _fileClose((File**)(pfile))) |
bool fileClose(File **pfile);
Closes a file and releases your reference to it
Flushes pending writes, closes the file, and sets the pointer to NULL. Accepts any kind of File. If something else still holds a reference to the same File, that reference stays valid, but reads and writes through it fail.
| pfile | Pointer to the file handle (the handle may be NULL) |
Example:
| #define fileFlush | ( | self | ) | ((self) ? ((self)->_->flush(File(self))) : false) |
bool fileFlush(File* self);
Flushes buffered writes to storage
Forces buffered data out to the storage device. This is slow, so only do it when durability matters right now; closing the file flushes it anyway.
| #define fileRead | ( | self, | |
| buf, | |||
| sz, | |||
| bytesread | |||
| ) | ((self) ? ((self)->_->read(File(self), buf, sz, bytesread)) : false) |
bool fileRead(File* self, void* buf, size_t sz, size_t* bytesread);
Reads data from the file
Reads up to sz bytes from the current position into buf and advances the position by the number of bytes actually read. Reading less than requested is not an error; it means the end of the file was reached.
| buf | Buffer to receive the data (must be at least sz bytes) |
| sz | Maximum number of bytes to read |
| bytesread | Receives the number of bytes read (0 at end of file) |
| #define fileSeek | ( | self, | |
| off, | |||
| seektype | |||
| ) | ((self) ? ((self)->_->seek(File(self), off, seektype)) : -1) |
int64 fileSeek(File* self, int64 off, FSSeekType seektype);
Changes the current position in the file
| off | Offset in bytes, which may be negative for FS_Cur and FS_End |
| seektype | Where to measure from: FS_Set (start), FS_Cur (current), FS_End (end) |
| #define fileTell | ( | self | ) | ((self) ? ((self)->_->tell(File(self))) : -1) |
int64 fileTell(File* self);
Gets the current position in the file
| #define fileWrite | ( | self, | |
| buf, | |||
| sz, | |||
| byteswritten | |||
| ) | ((self) ? ((self)->_->write(File(self), buf, sz, byteswritten)) : false) |
bool fileWrite(File* self, const void* buf, size_t sz, size_t* byteswritten);
Writes data to the file
Writes sz bytes from buf at the current position and advances the position by the number of bytes written. Most of the time everything is written or the call fails, but a short write is possible on some filesystems, so check byteswritten when it matters.
| buf | Buffer containing the data to write |
| sz | Number of bytes to write |
| byteswritten | Receives the number of bytes written, or NULL |
| #define fileWriteString | ( | self, | |
| str, | |||
| byteswritten | |||
| ) | File_writeString(File(self), str, byteswritten) |
bool fileWriteString(File* self, strref str, size_t* byteswritten);
Writes the contents of a string to the file
The string is written as-is, with no line ending added.
| str | String to write |
| byteswritten | Receives the number of bytes written, or NULL |
An open file
Every open file is a File, whichever layer opened it: fsOpen() hands back one backed by an OS file handle, and vfsOpen() one backed by a VFS provider. Code that only reads and writes can take a File* and work with either.
A File is reference counted. fileClose() closes the file and releases your reference; objRelease() only releases the reference, and closes the file if it was the last one.
A file handle is single-owner: one thread at a time, like a C FILE*. Two threads may use two handles on the same file, but they must not share one handle.
| typedef enum FSSeekTypeEnum FSSeekType |
File seek origin
Specifies the reference point for fileSeek operations.
| enum FSOpenFlags |
File open flags
Flags controlling how a file is opened. Combine with bitwise OR. The FS_Overwrite flag is a convenience combination of common flags.
| enum FSSeekTypeEnum |
|
inline |
Flushes buffered writes to disk
Forces any buffered write data to be physically written to the storage device. This ensures data durability but may be slow. The OS may buffer writes for performance; this function ensures they reach the disk.
| file | Open file handle |
Definition at line 244 of file file.h.
References fileFlush.
| FSFile * fsOpen | ( | strref | path, |
| flags_t | flags | ||
| ) |
Opens a file for I/O operations
Creates a file handle for reading, writing, or both. Close it with fileClose() when done, or hold on to it and release it later with objRelease().
Common flag combinations:
FS_Read - Open existing file for readingFS_Write - Open existing file for writingFS_Read | FS_Write - Open existing file for read/writeFS_Write | FS_Create - Open or create file for writingFS_Overwrite - Create new or truncate existing fileFS_Read | FS_Write | FS_Create - Open or create for read/writeThe FS_Lock flag requests exclusive write access. On Windows, other processes can still read the file but cannot write. On Unix, this is advisory locking.
| path | Path to the file to open (can be relative or absolute) |
| flags | Combination of FSOpenFlags specifying open mode |
Example:
|
inline |
Reads data from a file
Reads up to 'sz' bytes from the current file position into the buffer. The file position is advanced by the number of bytes actually read. Reading less than requested is not an error - it indicates end-of-file or incomplete data available.
| file | Open file handle (must have FS_Read flag) |
| buf | Buffer to receive the data (must be at least 'sz' bytes) |
| sz | Maximum number of bytes to read |
| bytesread | Receives the actual number of bytes read (can be 0 at EOF) |
Example:
Definition at line 126 of file file.h.
References fileRead.
|
inline |
Changes the current file position
Moves the file position to a new location for subsequent read/write operations. The position can be set relative to the beginning, current position, or end of the file.
| file | Open file handle |
| off | Offset in bytes (can be negative for FS_Cur and FS_End) |
| seektype | Reference point: FS_Set (start), FS_Cur (current), FS_End (end) |
Examples:
Definition at line 225 of file file.h.
References fileSeek.
|
inline |
Gets the current file position
Returns the current byte offset within the file. This is the position where the next read or write operation will occur. The position starts at 0 (beginning of file) when the file is opened.
| file | Open file handle |
Definition at line 198 of file file.h.
References fileTell.
|
inline |
Writes data to a file
Writes 'sz' bytes from the buffer to the file at the current position. The file position is advanced by the number of bytes written.
On most systems, this function will write all requested bytes or fail. However, on some systems (particularly networked filesystems), a short write may occur. Check byteswritten to verify the full write completed.
| file | Open file handle (must have FS_Write flag) |
| buf | Buffer containing data to write |
| sz | Number of bytes to write |
| byteswritten | Optional pointer to receive actual bytes written (can be NULL) |
Example:
Definition at line 160 of file file.h.
References fileWrite.
|
inline |
Writes a string to a file
The string contents are written as-is, with no line ending added.
| file | Open file handle (must have FS_Write flag) |
| str | String to write |
| byteswritten | Optional pointer to receive actual bytes written (can be NULL) |
Definition at line 179 of file file.h.
References fileWriteString.
1.9.8