Cross-platform file handling API with synchronous and asynchronous I/O support. More...

#include "platform.h"
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <stdio.h>
#include <fcntl.h>
#include <sys/mman.h>
#include <sys/stat.h>
#include <unistd.h>

Include dependency graph for file.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	FileAttributes

struct	file_t

Typedefs
typedef enum FileAttrFlags	FileAttrFlags

typedef struct FileAttributes	FileAttributes

Enumerations
enum	FileAttrFlags { FATTR_NONE = 0 , FATTR_FILE = 1 << 0 , FATTR_DIR = 1 << 1 , FATTR_SYMLINK = 1 << 2 , FATTR_CHARDEV = 1 << 3 , FATTR_BLOCKDEV = 1 << 4 , FATTR_FIFO = 1 << 5 , FATTR_SOCKET = 1 << 6 , FATTR_HIDDEN = 1 << 7 , FATTR_EXECUTABLE = 1 << 8 }

enum	file_result_t { FILE_SUCCESS = 0 , FILE_ERROR_INVALID_ARGS , FILE_ERROR_OPEN_FAILED , FILE_ERROR_IO_FAILED , FILE_ERROR_LOCK_FAILED , FILE_ERROR_MEMORY_FAILED , FILE_ERROR_SYSTEM_ERROR }

Functions
int	populate_file_attrs (const char path, FileAttributes attr)

file_result_t	file_open (file_t file, const char filename, const char *mode)

void	file_close (file_t *file)

file_result_t	file_truncate (file_t *file, int64_t length)

file_result_t	filesize_tostring (uint64_t size, char *buf, size_t len)

size_t	file_read (const file_t file, void buffer, size_t size, size_t count)

size_t	file_write (file_t file, const void buffer, size_t size, size_t count)

size_t	file_write_string (file_t file, const char str)

ssize_t	file_pread (const file_t file, void buffer, size_t size, int64_t offset)

ssize_t	file_pwrite (file_t file, const void buffer, size_t size, int64_t offset)

void *	file_readall (file_t file, size_t size_out)

file_result_t	file_lock (const file_t *file)

file_result_t	file_unlock (const file_t *file)

file_result_t	file_copy (const file_t src, file_t dst)

void *	file_mmap (const file_t *file, size_t length, bool read_access, bool write_access)

file_result_t	file_munmap (void *addr, size_t length)

file_result_t	file_flush (file_t *file)

int64_t	file_tell (const file_t *file)

file_result_t	file_seek (file_t *file, int64_t offset, int whence)

Detailed Description

Cross-platform file handling API with synchronous and asynchronous I/O support.

Definition in file file.h.

Typedef Documentation

◆ FileAttrFlags

typedef enum FileAttrFlags FileAttrFlags

File attribute flags bitmask

◆ FileAttributes

typedef struct FileAttributes FileAttributes

Represents file attributes for directory traversal

Enumeration Type Documentation

◆ file_result_t

enum file_result_t

File operation result codes.

Enumerator
FILE_SUCCESS	Operation completed successfully.
FILE_ERROR_INVALID_ARGS	Invalid arguments provided.
FILE_ERROR_OPEN_FAILED	File open operation failed.
FILE_ERROR_IO_FAILED	I/O operation failed.
FILE_ERROR_LOCK_FAILED	File locking operation failed.
FILE_ERROR_MEMORY_FAILED	Memory allocation failed.
FILE_ERROR_SYSTEM_ERROR	System-specific error occurred.

Definition at line 140 of file file.h.

◆ FileAttrFlags

enum FileAttrFlags

File attribute flags bitmask

Enumerator
FATTR_NONE	No attributes set
FATTR_FILE	Regular file
FATTR_DIR	Directory
FATTR_SYMLINK	Symbolic link
FATTR_CHARDEV	Character device
FATTR_BLOCKDEV	Block device
FATTR_FIFO	Named pipe (FIFO)
FATTR_SOCKET	Socket
FATTR_HIDDEN	Hidden file (starts with '.')
FATTR_EXECUTABLE	This is an executable file

Definition at line 56 of file file.h.

Function Documentation

◆ file_close()

void file_close ( file_t * file )

Closes the file and releases all associated resources. Safe to call multiple times or on uninitialized structures.

Parameters

file	Pointer to the file_t structure.

Definition at line 234 of file file.c.

References file_t::native_handle, and file_t::stream.

◆ file_copy()

file_result_t file_copy	(	const file_t *	src,
		file_t *	dst
	)

Copies content from source file to destination file. Reads from current position of source until EOF. Flushes destination after copying.

Parameters

src	Source file (must be open for reading).
dst	Destination file (must be open for writing).

Returns: FILE_SUCCESS on success, appropriate error code otherwise.

Definition at line 471 of file file.c.

References FILE_ERROR_IO_FAILED, file_read(), FILE_SUCCESS, file_write(), and file_t::stream.

Here is the call graph for this function:

◆ file_flush()

file_result_t file_flush ( file_t * file )

Flushes any buffered data to the underlying file.

Parameters

file	Pointer to the opened file_t structure.

Returns: FILE_SUCCESS on success, FILE_ERROR_IO_FAILED otherwise.

Definition at line 544 of file file.c.

References FILE_ERROR_IO_FAILED, FILE_SUCCESS, and file_t::stream.

◆ file_lock()

file_result_t file_lock ( const file_t * file )

Attempts to acquire an exclusive advisory lock on the entire file. The lock is non-blocking and will fail immediately if unavailable.

Parameters

file	Pointer to the opened file_t structure.

Returns: FILE_SUCCESS if locked, FILE_ERROR_LOCK_FAILED if already locked, other error codes for system failures.

Definition at line 424 of file file.c.

References FILE_ERROR_LOCK_FAILED, FILE_ERROR_SYSTEM_ERROR, FILE_SUCCESS, and file_t::native_handle.

◆ file_mmap()

void * file_mmap	(	const file_t *	file,
		size_t	length,
		bool	read_access,
		bool	write_access
	)

Memory maps a portion of the file starting from the beginning.

Parameters

file	Pointer to the opened file_t structure.
length	Number of bytes to map.
read_access	Request read access to the mapping.
write_access	Request write access to the mapping.

Returns: Pointer to mapped memory on success, NULL on failure (errno is set).

Note: Use file_munmap() to release the mapping.

Definition at line 498 of file file.c.

References file_t::native_handle.

◆ file_munmap()

file_result_t file_munmap	(	void *	addr,
		size_t	length
	)

Unmaps a previously memory-mapped region.

Parameters

addr	Pointer to the mapped region (from file_mmap).
length	Length of the mapping (must match file_mmap parameter).

Returns: FILE_SUCCESS on success, FILE_ERROR_INVALID_ARGS on failure.

Definition at line 531 of file file.c.

References FILE_ERROR_INVALID_ARGS, FILE_ERROR_SYSTEM_ERROR, and FILE_SUCCESS.

◆ file_open()

file_result_t file_open	(	file_t *	file,
		const char *	filename,
		const char *	mode
	)

Opens a file and populates the file_t structure.

Parameters

file	Pointer to file_t structure to initialize.
filename	Path to the file to open.
mode	Mode string (e.g., "r", "wb+", "a"). See fopen documentation.

Returns: FILE_SUCCESS on success, appropriate error code otherwise.

Note: Sets errno on failure. The file structure is zeroed on failure.

Definition at line 198 of file file.c.

References FILE_ERROR_INVALID_ARGS, FILE_ERROR_OPEN_FAILED, FILE_SUCCESS, file_t::native_handle, populate_file_attrs(), and file_t::stream.

Here is the call graph for this function:

◆ file_pread()

ssize_t file_pread	(	const file_t *	file,
		void *	buffer,
		size_t	size,
		int64_t	offset
	)

Performs positioned read without affecting the file pointer. This is atomic on POSIX systems and simulated on Windows.

Parameters

file	Pointer to the opened file_t structure.
buffer	Buffer to store read data.
size	Number of bytes to read.
offset	File offset to read from.

Returns: Number of bytes read on success, -1 on error (errno is set).

Definition at line 323 of file file.c.

References file_t::native_handle.

◆ file_pwrite()

ssize_t file_pwrite	(	file_t *	file,
		const void *	buffer,
		size_t	size,
		int64_t	offset
	)

Performs positioned write without affecting the file pointer. This is atomic on POSIX systems and simulated on Windows.

Parameters

file	Pointer to the opened file_t structure.
buffer	Data to write.
size	Number of bytes to write.
offset	File offset to write to.

Returns: Number of bytes written on success, -1 on error (errno is set).

Definition at line 347 of file file.c.

References file_t::native_handle.

◆ file_read()

size_t file_read	(	const file_t *	file,
		void *	buffer,
		size_t	size,
		size_t	count
	)

Reads data from the file using buffered I/O.

Parameters

file	Pointer to the opened file_t structure.
buffer	Buffer to store read data.
size	Size of each element.
count	Number of elements to read.

Returns: Number of elements successfully read. Use feof/ferror for status.

Definition at line 301 of file file.c.

References file_t::stream.

Referenced by file_copy(), and file_readall().

Here is the caller graph for this function:

◆ file_readall()

void * file_readall	(	file_t *	file,
		size_t *	size_out
	)

Reads the entire file content into a newly allocated buffer. The file position is reset to the beginning before reading.

Parameters

file	Pointer to the opened file_t structure.
size_out	Optional pointer to store the file size read.

Returns: Allocated buffer containing file content, or NULL on error.

Note: Caller must free() the returned buffer. Sets errno on failure.

Definition at line 367 of file file.c.

References file_read(), file_tell(), FileAttributes::size, and file_t::stream.

Here is the call graph for this function:

◆ file_seek()

file_result_t file_seek	(	file_t *	file,
		int64_t	offset,
		int	whence
	)

Sets the file position.

Parameters

file	Pointer to the opened file_t structure.
offset	Offset relative to whence.
whence	Position reference (SEEK_SET, SEEK_CUR, SEEK_END).

Returns: FILE_SUCCESS on success, FILE_ERROR_IO_FAILED otherwise.

Definition at line 561 of file file.c.

References FILE_ERROR_INVALID_ARGS, FILE_ERROR_IO_FAILED, FILE_SUCCESS, file_t::native_handle, and file_t::stream.

◆ file_tell()

int64_t file_tell ( const file_t * file )

Gets the current file position.

Parameters

file	Pointer to the opened file_t structure.

Returns: Current file position, or -1 on error (errno is set).

Definition at line 546 of file file.c.

References file_t::native_handle.

Referenced by file_readall().

Here is the caller graph for this function:

◆ file_truncate()

file_result_t file_truncate	(	file_t *	file,
		int64_t	length
	)

Truncates or extends the file to the specified length. File must be opened with write permissions.

Parameters

file	Pointer to the opened file_t structure.
length	Desired file length in bytes.

Returns: FILE_SUCCESS on success, appropriate error code otherwise.

Definition at line 242 of file file.c.

References FILE_ERROR_INVALID_ARGS, FILE_ERROR_IO_FAILED, FILE_SUCCESS, file_t::native_handle, and file_t::stream.

◆ file_unlock()

file_result_t file_unlock ( const file_t * file )

Releases an advisory lock on the file. Safe to call on files that are not locked.

Parameters

file	Pointer to the opened file_t structure.

Returns: FILE_SUCCESS on success, appropriate error code otherwise.

Definition at line 453 of file file.c.

References FILE_ERROR_SYSTEM_ERROR, FILE_SUCCESS, and file_t::native_handle.

◆ file_write()

size_t file_write	(	file_t *	file,
		const void *	buffer,
		size_t	size,
		size_t	count
	)

Writes data to the file using buffered I/O. Does not automatically flush the stream.

Parameters

file	Pointer to the opened file_t structure.
buffer	Data to write.
size	Size of each element.
count	Number of elements to write.

Returns: Number of elements successfully written. Use ferror for status.

Definition at line 308 of file file.c.

References file_t::stream.

Referenced by file_copy().

Here is the caller graph for this function:

◆ file_write_string()

size_t file_write_string	(	file_t *	file,
		const char *	str
	)

Writes a null-terminated string to the file (excluding null terminator).

Parameters

file	Pointer to the opened file_t structure.
str	Null-terminated string to write.

Returns: Number of bytes written on success, 0 if str is NULL or empty.

Definition at line 315 of file file.c.

References file_t::stream.

◆ filesize_tostring()

file_result_t filesize_tostring	(	uint64_t	size,
		char *	buf,
		size_t	len
	)

Converts a file size to a human-readable string representation.

Parameters

size	File size in bytes.
buf	Buffer to store the formatted string.
len	Size of the buffer.

Returns: FILE_SUCCESS on success, FILE_ERROR_INVALID_ARGS if buffer too small.

Definition at line 268 of file file.c.

References FILE_ERROR_INVALID_ARGS, and FILE_SUCCESS.

◆ populate_file_attrs()

int populate_file_attrs	(	const char *	path,
		FileAttributes *	attr
	)

Populates FileAttributes structure from a file path (POSIX implementation).

Parameters

path	Full path to the file.
name	Basename of the file.
attr	Output FileAttributes structure to populate.

Returns: 0 on success, -1 on error (errno is set).

Cross-platform file information retrieval. On Unix: uses lstat to detect symlinks without following them. On Windows: uses GetFileAttributesEx for basic info.

Definition at line 124 of file file.c.

References FileAttributes::attrs, FATTR_BLOCKDEV, FATTR_CHARDEV, FATTR_DIR, FATTR_EXECUTABLE, FATTR_FIFO, FATTR_FILE, FATTR_HIDDEN, FATTR_NONE, FATTR_SOCKET, FATTR_SYMLINK, populate_file_attrs(), and FileAttributes::size.

Referenced by dir_walk(), dir_walk_depth_first(), file_open(), and populate_file_attrs().

Here is the call graph for this function:

Here is the caller graph for this function:

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ FileAttrFlags

◆ FileAttributes

Enumeration Type Documentation

◆ file_result_t

◆ FileAttrFlags

Function Documentation

◆ file_close()

◆ file_copy()

◆ file_flush()

◆ file_lock()

◆ file_mmap()

◆ file_munmap()

◆ file_open()

◆ file_pread()

◆ file_pwrite()

◆ file_read()

◆ file_readall()

◆ file_seek()

◆ file_tell()

◆ file_truncate()

◆ file_unlock()

◆ file_write()

◆ file_write_string()

◆ filesize_tostring()

◆ populate_file_attrs()