A class containing utility functions used for IO operations. More...

Functions
void	removeDirectory (const std::string &directory, const std::string &prefix)
	Remove a directory using directory name and parent pathname. More...

void	removeDirectory (const std::string &pathname)
	Remove a directory using a complete pathname. More...

void	copyDirectoryContents (const std::string &sourcepath, const std::string &targetpath, const bool removesource=false)
	Copy the contents of a directory, optionally deleting the source directory contents when done. More...

void	setAsideName (const std::string &name)
	Set aside a file or directory name. More...

uint64_t	getFileSize (const std::string &pathname)
	Get the size of a file. More...

uint64_t	sumDirectoryUsage (const std::string &pathname)
	Get the sum of the sizes of all files and directories in a given path. More...

bool	fileExists (const std::string &pathname)
	Indicate whether a file exists. More...

bool	pathIsDirectory (const std::string &pathname)

int	makePath (const std::string &path, const mode_t mode)
	Create an entire directory tree. More...

Memory::uint8Array	readFile (const std::string &path, std::ios_base::openmode mode=std::ios_base::binary)
	Read the contents of a file into an 8-bit AutoArray. More...

void	writeFile (const uint8_t *data, const size_t size, const std::string &path, std::ios_base::openmode mode=std::ios_base::binary)
	Write the contents of a buffer to a file. More...

void	writeFile (const Memory::uint8Array data, const std::string &path, std::ios_base::openmode mode=std::ios_base::binary)
	Write the contents of an 8-bit AutoArray to a file. More...

void	readPipe (void *data, size_t size, int pipeFD)
	Read from an open pipe into a buffer. More...

void	readPipe (Memory::uint8Array &data, int pipeFD)
	Read from an open pipe into an 8-bit AutoArray. More...

void	writePipe (const void *data, size_t size, int pipeFD)
	Write the contents of a buffer to a pipe. More...

void	writePipe (const Memory::uint8Array &data, int pipeFD)
	Write the contents of an 8-bit AutoArray to a pipe. More...

bool	isReadable (const std::string &pathname)
	Determine if the real user has read access permissions to this file. More...

bool	isWritable (const std::string &pathname)
	Determine if the real user has write access permissions to this file. More...

std::string	createTemporaryFile (const std::string &prefix="", const std::string &parentDir="/tmp")
	Create a temporary file. More...

FILE *	createTemporaryFile (std::string &path, const std::string &prefix="", const std::string &parentDir="/tmp")
	Create a temporary file. More...

uint64_t	countLines (const std::string &path)
	Count the number of newline characters in a text file. More...

uint64_t	countLines (const Memory::uint8Array &textBuffer)
	Count the number of newline characters in a buffer of a text file. More...

Detailed Description

A class containing utility functions used for IO operations.

These functions are class methods.

Function Documentation

◆ removeDirectory() [1/2]

void BiometricEvaluation::IO::Utility::removeDirectory	(	const std::string &	directory,
		const std::string &	prefix
	)

Remove a directory using directory name and parent pathname.

Parameters

[in]	directory	The name of the directory to be removed, without a preceding path.
[in]	prefix	The path leading to the directory.

Exceptions

Error::ObjectDoesNotExist	The named directory does not exist.
Error::StrategyError	An error occurred when using the underlying storage system, or the directoy name or prefix is malformed.

◆ removeDirectory() [2/2]

void BiometricEvaluation::IO::Utility::removeDirectory ( const std::string & pathname )

Remove a directory using a complete pathname.

Parameters

[in] pathname The complelte path name of the directory to be removed,

Exceptions

Error::ObjectDoesNotExist	The named directory does not exist.
Error::StrategyError	An error occurred when using the underlying storage system, or the path name is malformed.

◆ copyDirectoryContents()

void BiometricEvaluation::IO::Utility::copyDirectoryContents	(	const std::string &	sourcepath,
		const std::string &	targetpath,
		const bool	removesource = `false`
	)

Copy the contents of a directory, optionally deleting the source directory contents when done.

Parameters

[in]	sourcepath	The name of the directory whose contents are to be moved.
[in]	targetpath	The name of the directory where the contents of the sourcepath are to be moved.
[in]	removesource	Flag indicating whether to remove the source directory after the copy is complete.

Exceptions

Error::ObjectDoesNotExist	The source named directory does not exist.
Error::StrategyError	An error occurred when using the underlying storage system, or the directoy name or prefix is malformed.

◆ setAsideName()

void BiometricEvaluation::IO::Utility::setAsideName ( const std::string & name )

Set aside a file or directory name.

A file or directory is renamed in a sequential manner. For example, if directory foo is set aside, it will be renamed foo.1. If foo is recreated by the application, and again set aside, it will be renamed foo.2. There is a limit of uint16_t max attempts at creating a set aside name.

Parameters

[in] name The path name of the file or directory to be set aside.

Exceptions

Error::ObjectDoesNotExist	The named object does not exist.
Error::StrategyError	An error occurred when using the underlying storage system, the name or prefix is malformed, or the maximum number of attempts was reached.

◆ getFileSize()

uint64_t BiometricEvaluation::IO::Utility::getFileSize ( const std::string & pathname )

Get the size of a file.

Parameters

[in] pathname The name of the file to be sized; can be a complete path.

Returns: The file size.

Exceptions

Error::ObjectDoesNotExist	The named directory does not exist.
Error::StrategyError	An error occurred when using the underlying storage system, or pathname is malformed.

◆ sumDirectoryUsage()

uint64_t BiometricEvaluation::IO::Utility::sumDirectoryUsage ( const std::string & pathname )

Get the sum of the sizes of all files and directories in a given path.

Parameters

[in] pathname The name of the directory to be sized.

Returns: The sum of file and directory sizes.

Exceptions

Error::ObjectDoesNotExist	The named directory does not exist.
Error::StrategyError	An error occurred when using the underlying storage system, or pathname is malformed.

◆ fileExists()

bool BiometricEvaluation::IO::Utility::fileExists ( const std::string & pathname )

Indicate whether a file exists.

Parameters

[in] pathname The name of the file to be checked; can be a complete path.

Returns: true if the file exists, false otherwise.

Exceptions

Error::StrategyError An error occurred when using the underlying storage system, or pathname is malformed.

◆ pathIsDirectory()

bool BiometricEvaluation::IO::Utility::pathIsDirectory ( const std::string & pathname )

◆ makePath()

int BiometricEvaluation::IO::Utility::makePath	(	const std::string &	path,
		const mode_t	mode
	)

Create an entire directory tree.

All intermediate nodes are created if they don't exist.

Parameters

[in]	path	The path to create.
[in]	mode	The permission mode of each element in the path. See chmod(2).

Returns: 0 on success, non-zero otherwise, and errno can be checked.

◆ readFile()

Memory::uint8Array BiometricEvaluation::IO::Utility::readFile	(	const std::string &	path,
		std::ios_base::openmode	mode = `std::ios_base::binary`
	)

Read the contents of a file into an 8-bit AutoArray.

Parameters

path	Path to a file to be read.
mode	Bitwise OR'd arguments to send to the file stream constructor.

Returns: Contents of path in an AutoArray.

Exceptions

Error::ObjectDoesNotExist	path does not exist.
Error::StrategyError	An error occurred when using the underlying storage system.

◆ writeFile() [1/2]

void BiometricEvaluation::IO::Utility::writeFile	(	const uint8_t *	data,
		const size_t	size,
		const std::string &	path,
		std::ios_base::openmode	mode = `std::ios_base::binary`
	)

Write the contents of a buffer to a file.

A thin wrapper around std::ofstream. The mode parameter has the same semantics as that for std::ofstream and applications must set mode for append or truncate when writing to an existing file.

Parameters

data	Data buffer to write.
size	Size of data.
path	Path to file to create with contents of data.
mode	Bitwise OR'd arguments to send to the file stream constructor.

Exceptions

ObjectExists	path exists and is a directory.
StrategyError	An error occurred when using the underlying storage system.

◆ writeFile() [2/2]

void BiometricEvaluation::IO::Utility::writeFile	(	const Memory::uint8Array	data,
		const std::string &	path,
		std::ios_base::openmode	mode = `std::ios_base::binary`
	)

Write the contents of an 8-bit AutoArray to a file.

A thin wrapper around std::ofstream. The mode parameter has the same semantics as that for std::ofstream and applications must set mode for append or truncate when writing to an existing file.

Parameters

data	Data array to write.
path	Path to file to create with contents of data.
mode	Bitwise OR'd arguments to send to the file stream constructor.

Exceptions

ObjectExists	path exists and is a directory.
StrategyError	An error occurred when using the underlying storage system.

◆ readPipe() [1/2]

void BiometricEvaluation::IO::Utility::readPipe	(	void *	data,
		size_t	size,
		int	pipeFD
	)

Read from an open pipe into a buffer.

Wraps the read(2) system call by reading the requested amount of data from a pipe file descriptor, handling all errors and signals.

Parameters

data	Data buffer to store the data being read.
size	Size of data to read.
pipeFD	The file descriptor of the pipe.

Exceptions

ObjectDoesNotExist	The writing end of the pipe has been closed.
FileError	The data could not be written in the entirety; Error::errorStr() may contain more information.

◆ readPipe() [2/2]

void BiometricEvaluation::IO::Utility::readPipe	(	Memory::uint8Array &	data,
		int	pipeFD
	)

Read from an open pipe into an 8-bit AutoArray.

Wraps the read(2) system call by reading the requested amount of data from a pipe file descriptor, * handling all errors and signals.

Parameters

data	Data array to read into.
pipeFD	The file descriptor of the pipe.

Exceptions

ObjectDoesNotExist	The reading end of the pipe has been closed.
FileError	The data could not be written in the entirety; Error::errorStr() may contain more information.

◆ writePipe() [1/2]

void BiometricEvaluation::IO::Utility::writePipe	(	const void *	data,
		size_t	size,
		int	pipeFD
	)

Write the contents of a buffer to a pipe.

Wraps the write(2) system call by writing all data to a pipe file descriptor, handling all errors and signals.

Parameters

data	Data buffer to write.
size	Size of data.
pipeFD	The file descriptor of the pipe.

Exceptions

ObjectDoesNotExist	The reading end of the pipe has been closed.
FileError	The data could not be written in the entirety; Error::errorStr() may contain more information.

◆ writePipe() [2/2]

void BiometricEvaluation::IO::Utility::writePipe	(	const Memory::uint8Array &	data,
		int	pipeFD
	)

Write the contents of an 8-bit AutoArray to a pipe.

Wraps the write(2) system call by writing all data to a pipe file descriptor, handling all errors and signals.

Parameters

data	Data array to write.
pipeFD	The file descriptor of the pipe.

Exceptions

ObjectDoesNotExist	The reading end of the pipe has been closed.
FileError	The data could not be written in the entirety; Error::errorStr() may contain more information.

◆ isReadable()

bool BiometricEvaluation::IO::Utility::isReadable ( const std::string & pathname )

Determine if the real user has read access permissions to this file.

Parameters

[in] pathname Path to the file to check.

Returns: true if the real user has read acccess permissions, false otherwise.

Warning: This function should only be called after failing to open a file, to determine a possible failure reason.

See also: BiometricEvaluation::IO::Utility::fileExists()

◆ isWritable()

bool BiometricEvaluation::IO::Utility::isWritable ( const std::string & pathname )

Determine if the real user has write access permissions to this file.

Parameters

[in] pathname Path to the file to check.

Returns: true if the real user has write acccess permissions, false otherwise.

Warning: This function should only be called after failing to write to a file, to determine a possible failure reason.

See also: BiometricEvaluation::IO::Utility::fileExists()

◆ createTemporaryFile() [1/2]

std::string BiometricEvaluation::IO::Utility::createTemporaryFile	(	const std::string &	prefix = `""`,
		const std::string &	parentDir = `"/tmp"`
	)

Create a temporary file.

Parameters

[in]	prefix	String to be prefixed to the random temporary name.
[in]	parentDir	Where to place the temporary file.

Exceptions

Error::FileError	Could not create or close temporary file.
Error::MemoryError	Error allocating memory for file name.

Returns: Path to temporary file.

Note: Exclusivity is not guaranteed for the path returned, since the exclusive descriptor is closed before returning.; The default argument for parentDir is "/tmp". On Windows, this will be replaced with the appropriate Windows temporary directory, but Windows does not guarantee write access.

◆ createTemporaryFile() [2/2]

FILE * BiometricEvaluation::IO::Utility::createTemporaryFile	(	std::string &	path,
		const std::string &	prefix = `""`,
		const std::string &	parentDir = `"/tmp"`
	)

Create a temporary file.

Exclusivity to the file stream is guaranteed.

Parameters

[out]	path	Reference to a string that will hold the path to the opened temporary file.
[in]	prefix	String to be prefixed to the random temporary name.
[in]	parentDir	Where to place the temporary file.

Exceptions

Error::FileError	Could not create or close temporary file.
Error::MemoryError	Error allocating memory for file name.

Returns: Open file stream to path.

Note: Caller must fclose(3) the returned stream.; The default argument for parentDir is "/tmp". On Windows, this will be replaced with the appropriate Windows temporary directory, but Windows does not guarantee write access.

◆ countLines() [1/2]

uint64_t BiometricEvaluation::IO::Utility::countLines ( const std::string & path )

Count the number of newline characters in a text file.

Parameters

path	Path to text file.

Returns: Number of newline characters in file at path.

Exceptions

Error::FileError Could not open path.

◆ countLines() [2/2]

uint64_t BiometricEvaluation::IO::Utility::countLines ( const Memory::uint8Array & textBuffer )

Count the number of newline characters in a buffer of a text file.

Parameters

path	Buffer of text file that has been read in.

Returns: Number of newline characters in buffer.

Functions

Detailed Description

Function Documentation

◆ removeDirectory() [1/2]

◆ removeDirectory() [2/2]

◆ copyDirectoryContents()

◆ setAsideName()

◆ getFileSize()

◆ sumDirectoryUsage()

◆ fileExists()

◆ pathIsDirectory()

◆ makePath()

◆ readFile()

◆ writeFile() [1/2]

◆ writeFile() [2/2]

◆ readPipe() [1/2]

◆ readPipe() [2/2]

◆ writePipe() [1/2]

◆ writePipe() [2/2]

◆ isReadable()

◆ isWritable()

◆ createTemporaryFile() [1/2]

◆ createTemporaryFile() [2/2]

◆ countLines() [1/2]

◆ countLines() [2/2]