fseries.c File Reference

(2023-09-13, commit: 3ece5ed)

Implementation file related to the handling of a series of filenames within a directory. More...

#include "fseries.h"
#include <dirent.h>
#include <fcntl.h>
#include <pthread.h>
#include <stdlib.h>
#include <string.h>
#include <sys/stat.h>
#include <sys/types.h>
#include "confparse.h"
#include "logio.h"

Include dependency graph for fseries.c:

Macros
#define	TESTABLE_STATIC   static

Functions
TESTABLE_STATIC int	crinitScanDirFilter (const struct dirent *dent)
TESTABLE_STATIC bool	crinitSuffixFilter (const char *name, const char *suffix)
TESTABLE_STATIC int	crinitStatFilter (const char *name, int baseDirFd, bool followLinks)
TESTABLE_STATIC void	crinitFreeScandirList (struct dirent **scanList, int size)
TESTABLE 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)
int	crinitFileSeriesFromDir (crinitFileSeries_t *fse, const char *path, const char *fileSuffix, bool followLinks)
int	crinitFileSeriesFromStrArr (crinitFileSeries_t *fse, const char *baseDir, char **strArr)

Variables
struct {
const char *   fileSuffix
	The extension of the files we want to scan for. More...
bool   followLinks
int   baseDirFd
	File descriptor of the opened base directory for the search. More...
pthread_mutex_t   dirScanLock
}	crinitScState = {.baseDirFd = -1, .dirScanLock = PTHREAD_MUTEX_INITIALIZER}

Detailed Description

Implementation file related to the handling of a series of filenames within a directory.

Macro Definition Documentation

TESTABLE_STATIC

#define TESTABLE_STATIC   static

Function Documentation

crinitDestroyFileSeries()

TESTABLE 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.

crinitFreeScandirList()

void crinitFreeScandirList	(	struct dirent **	scanList,
		int	size
	)

Free return pointer(s) from scandir().

Will free everything, scandir() has allocated according to the scandir(3) man page.

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.

crinitScanDirFilter()

int crinitScanDirFilter

(

const struct dirent *

dent

)

Result filter to be given to scandir() via function pointer.

Uses crinitScState to setup and run crinitSuffixFilter() and crinitStatFilter().

See also scandir(3) man page.

Parameters

dent	Pointer to a directory entry.

Returns

1 if dent should be included in the final result list, 0 if not.

crinitStatFilter()

int crinitStatFilter	(	const char *	name,
		int	baseDirFd,
		bool	followLinks
	)

Filters out everything that is not a regular file (or a symlink to it, depending on settings).

Parameters

name	Filename of the file to be fed to the filter.
baseDirFd	Opened file descriptor of the directory, the file in question resides.
followLinks	If symbolic links should be followed to its destination before filtering (true) or generally filtered out (false).

Returns

true if name refers to a regular file, false if not.

crinitSuffixFilter()

bool crinitSuffixFilter	(	const char *	name,
		const char *	suffix
	)

Filters strings by suffix.

Parameters

name	String to be fed to the filter.
suffix	Suffix to check for.

Returns

true if name ends with suffix, false if not.

Variable Documentation

baseDirFd

int baseDirFd

File descriptor of the opened base directory for the search.

struct { ... } crinitScState

Global state/option variable to store options and state of a directory scan for the dirscan() filters.

Used to configure the filters for scandir() in crinitFileSeriesFromDir(). Needs to be used as a compilation-unit- global variable as scandir() does not allow arbitrary arguments to the filters.

dirScanLock

pthread_mutex_t dirScanLock

Mutex to synchronize concurrent accesses to this data, must be held during scandir().

fileSuffix

const char* fileSuffix

The extension of the files we want to scan for.

followLinks

bool followLinks

If we should follow symlinks that have the correct fileSuffix. If false, symlinks will be filtered out of the list.