fseries.h File Reference

(2023-11-21, commit: e767693)

Header defining functions related to the handling of a series of filenames within a directory. More...

#include <stdbool.h>
#include <stddef.h>

Include dependency graph for fseries.h:

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

Go to the source code of this file.

Classes
struct	crinitFileSeries_t

Macros
#define	TESTABLE

Typedefs
typedef struct crinitFileSeries_t	crinitFileSeries_t

Functions
int	crinitFileSeriesFromDir (crinitFileSeries_t *fse, const char *path, const char *fileSuffix, bool followLinks)
int	crinitFileSeriesFromStrArr (crinitFileSeries_t *fse, const char *baseDir, char **strArr)
void	crinitDestroyFileSeries (crinitFileSeries_t *fse)
TESTABLE int	crinitInitFileSeries (crinitFileSeries_t *fse, size_t numElements, const char *baseDir)
int	crinitResizeFileSeries (crinitFileSeries_t *fse, size_t numElements)

Detailed Description

Header defining functions related to the handling of a series of filenames within a directory.

Macro Definition Documentation

TESTABLE

#define TESTABLE

Typedef Documentation

crinitFileSeries_t

typedef struct crinitFileSeries_t crinitFileSeries_t

Data type holding a series of files inside a specific directory.

Function Documentation

crinitDestroyFileSeries()

void crinitDestroyFileSeries

(

crinitFileSeries_t *

fse

)

Frees memory associated with an crinitFileSeries_t.

Parameters

fse	The crinitFileSeries_t whose memory shall be deallocated.

crinitFileSeriesFromDir()

int crinitFileSeriesFromDir	(	crinitFileSeries_t *	fse,
		const char *	path,
		const char *	fileSuffix,
		bool	followLinks
	)

Generates an crinitFileSeries_t instance by scanning a given directory for regular files.

Uses scandir() with filters.

Parameters

fse	Return pointer for the resulting file series, will contain allocated memory that can be freed via crinitDestroyFileSeries().
path	Path to the directory to scan.
fileSuffix	File extension to filter results by.
followLinks	If symbolic links to regular files matching fileSuffix should be included or not.

Returns

0 on success, -1 otherwise.

crinitFileSeriesFromStrArr()

int crinitFileSeriesFromStrArr	(	crinitFileSeries_t *	fse,
		const char *	baseDir,
		char **	strArr
	)

Creates an crinitFileSeries_t instance by emplacing a pre-created array of strings.

Under the assumption, strArr is allocated as an outer array of pointers into a single dynamically allocated backing string beginning at the first pointer (as crinitFileSeriesFromDir() does it), crinitDestroyFileSeries() can be used for deallocation. If that is not the case, crinitFileSeries_t::fnames needs to be manually freed as necessary and set to NULL before it is safe to call crinitDestroyFileSeries().

Parameters

fse	Return pointer for the resulting file series, memory for crinitFileSeries_t::baseDir will be allocated.
baseDir	Base directory of the files in the series.
strArr	Array of strings to be emplaced as crinitFileSeries_t::fnames.

Returns

0 on success, -1 otherwise.

crinitInitFileSeries()

TESTABLE int crinitInitFileSeries	(	crinitFileSeries_t *	fse,
		size_t	numElements,
		const char *	baseDir
	)

Initialize an crinitFileSeries_t with a given number of empty pointers.

Sets initial state and then uses crinitResizeFileSeries() internally to allocate space for the pointers.

Parameters

fse	The crinitFileSeries_t to initialize.
numElements	The number of pointers in crinitFileSeries_t::fnames to allocate. No memory for the backing string is allocated at this point.
baseDir	Base directory of the new file series to be set.

Returns

0 on success, -1 otherwise.

crinitResizeFileSeries()

int crinitResizeFileSeries	(	crinitFileSeries_t *	fse,
		size_t	numElements
	)

Grow or shrink the number of string pointers in a file series.

May be used on an uninitialized crinitFileSeries_t if fnames is set to NULL before the call. Memory of the backing string is unaffected.

Parameters

fse	The crinitFileSeries_t to modify.
numElements	The new number of pointers that fse shall have. Can be lower, higher or the same as the current state.

Returns

0 on success, -1 otherwise.