FILES: files utilies

Data Structures
struct	N_FILE_INFO
	common file information More...

Functions
int	n_file_copy_verified (const char *from, const char *to, size_t *copied)
	Copy a file, check the copy against the original, and only then give it its name.
int	n_file_read_bounded (const char *path, size_t max_size, unsigned char **out, size_t *out_len)
	read a whole file into a freshly allocated, NUL-terminated buffer, refusing a file larger than max_size bytes.
int	n_file_same_content (const char *a, const char *b)
	Do two files hold the same bytes.
int	n_file_write_atomic (const char *path, const unsigned char *data, size_t len, int mode)
	durably and atomically write len bytes to path: write a "<path>.tmp" sibling created with mode from the outset (POSIX; 0 or Windows = leave default), flush it to stable storage, then atomically rename it over path (MoveFileEx REPLACE_EXISTING|WRITE_THROUGH on Windows, which replaces an existing target where the CRT rename() would fail).
void	n_free_file_info (void *ptr)
	free a N_FILE_INFO structure
int	n_scan_dir (const char *dir, LIST *result, const int recurse)
	scan a directory and store file information in the result list

Detailed Description

---

Data Structure Documentation

N_FILE_INFO

struct N_FILE_INFO

common file information

Examples

ex_file.c.

Definition at line 46 of file n_files.h.

Collaboration diagram for N_FILE_INFO:

Data Fields
time_t	filetime	file creation time
time_t	filetime_nsec
char *	name	file name

Function Documentation

n_file_copy_verified()

int n_file_copy_verified	(	const char *	from,
		const char *	to,
		size_t *	copied )

Copy a file, check the copy against the original, and only then give it its name.

For a backup that has to be trusted. The copy is written to "<to>.part", flushed to stable storage, closed, then read back from disk and compared with the original byte for byte; only a copy that compares equal is renamed to to. A copy that failed or differs is removed, so to is either absent or a verified copy, never a partial one. to is never replaced: an existing file makes the call fail, and the caller decides whether that file is the same one (see n_file_same_content()) or needs another name. Streams in blocks; memory does not grow with the file.

Parameters

from	the original, opened read only
to	where the copy goes; its folder must exist
copied	receives the number of bytes copied on success; may be NULL

Returns

TRUE when a verified copy is at to, FALSE otherwise (the reason is logged)

Definition at line 381 of file n_files.c.

References __n_assert, Free, LOG_ERR, Malloc, N_FILE_COPY_BLOCK, n_file_same_content(), and n_log.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

n_file_read_bounded()

int n_file_read_bounded	(	const char *	path,
		size_t	max_size,
		unsigned char **	out,
		size_t *	out_len )

read a whole file into a freshly allocated, NUL-terminated buffer, refusing a file larger than max_size bytes.

On success *out receives the malloc'd buffer (free with Free()/free()) and *out_len its byte length (0 for an empty file). Returns TRUE on success, FALSE on a NULL argument, an unreadable file, or one exceeding max_size.

Definition at line 270 of file n_files.c.

References __n_assert, Free, LOG_ERR, Malloc, and n_log.

Referenced by list_file(), and test_atomic_file().

Here is the caller graph for this function:

n_file_same_content()

int n_file_same_content	(	const char *	a,
		const char *	b )

Do two files hold the same bytes.

Parameters

a	first file
b	second file

Returns

TRUE when both can be read and are equal, FALSE otherwise

Definition at line 366 of file n_files.c.

References __n_assert, and n_file_streams_equal().

Referenced by main(), and n_file_copy_verified().

Here is the call graph for this function:

Here is the caller graph for this function:

n_file_write_atomic()

int n_file_write_atomic	(	const char *	path,
		const unsigned char *	data,
		size_t	len,
		int	mode )

durably and atomically write len bytes to path: write a "<path>.tmp" sibling created with mode from the outset (POSIX; 0 or Windows = leave default), flush it to stable storage, then atomically rename it over path (MoveFileEx REPLACE_EXISTING|WRITE_THROUGH on Windows, which replaces an existing target where the CRT rename() would fail).

A crash leaves either the old file or the new one, never a truncated file. Returns TRUE on success, FALSE otherwise (the temp file is removed on failure).

Definition at line 466 of file n_files.c.

References __n_assert, Free, LOG_ERR, Malloc, mode, and n_log.

Referenced by test_atomic_file().

Here is the caller graph for this function:

n_free_file_info()

void n_free_file_info

(

void *

ptr

)

free a N_FILE_INFO structure

free a N_FILE_INFO structure

This implementation uses ONLY POSIX-style APIs:

• opendir / readdir / closedir
• stat

MinGW provides these APIs on Windows, so no WinAPI (FindFirstFile...) is required.

Sorting:

• Files are inserted sorted by modification time (mtime), oldest first.
• Comparator uses seconds then nanoseconds (if available).

Notes:

• This version stores FULL PATH in N_FILE_INFO->name so recursion is unambiguous. If you prefer basename only, replace strdup(fullpath) with strdup(entry->d_name).

helper to free N_FILE_INFO structs

Parameters

ptr	a pointer to a N_FILE_INFO structure

Definition at line 76 of file n_files.c.

References __n_assert, and N_FILE_INFO::name.

Referenced by n_scan_dir().

Here is the caller graph for this function:

n_scan_dir()

int n_scan_dir	(	const char *	dir,
		LIST *	result,
		const int	recurse )

scan a directory and store file information in the result list

scan a directory and store file information in the result list

This function:

• Opens dir with opendir()
• Iterates entries via readdir()
• Builds full path for each entry (no chdir())
• Uses stat() to detect file type and modification time
• If recursion enabled and entry is a directory, scans it recursively
• If entry is a regular file, pushes an allocated N_FILE_INFO into result, keeping result sorted by n_comp_file_info (oldest -> newest).

Error handling:

• If opendir() fails: returns FALSE.
• If stat() fails for an entry: logs and continues.
• If readdir() fails: logs and returns FALSE.

Parameters

dir	Directory to scan (non-NULL)
result	LIST to fill (non-NULL)
recurse	TRUE/FALSE recursion flag

Returns

TRUE on success, FALSE on fatal error.

Definition at line 196 of file n_files.c.

References __n_assert, list_push_sorted(), LOG_ERR, Malloc, n_comp_file_info(), n_free_file_info(), n_log, n_path_join(), n_scan_dir(), n_set_time_from_stat(), and N_FILE_INFO::name.

Referenced by main(), and n_scan_dir().

Here is the call graph for this function:

Here is the caller graph for this function: