Detailed Description

blocking function and classes to work with filesystem

Use these with caution as they block current thread. It is probably OK to use them during startup (on component load), but don't use them after server start in the main TaskProcessor. Use asynchronous alternatives from fs namespace instead.

Classes
class	CFile
	A std::FILE* wrapper. More...
class	FileDescriptor
	A file descriptor wrapper. More...
class	TempDirectory
	A unique directory for temporary files. The directory is deleted when the TempDirectory is destroyed. More...
class	TempFile
	A unique temporary file. The file is deleted when the TempFile object is destroyed. More...

Typedefs
using	OpenMode = utils::Flags<OpenFlag>
	A set of OpenFlags.

Enumerations
enum class	OpenFlag { kNone = 0 , kRead = 1 << 0 , kWrite = 1 << 1 , kCreateIfNotExists = 1 << 2 , kExclusiveCreate = 1 << 3 , kTruncate = 1 << 4 , kAppend = 1 << 5 }

Functions
std::string	ReadFileContents (utils::zstring_view path)
	Reads file contents synchronously.
bool	FileExists (utils::zstring_view path)
	Checks whether the file exists synchronously.
boost::filesystem::file_type	GetFileType (utils::zstring_view path)
	Get file type returned by stat(2) synchronously.
FileInfoWithDataMap	ReadRecursiveFilesInfoWithData (utils::zstring_view path, SettingReadFileFlags flags)
	Returns files from recursively traversed directory.
void	CreateDirectories (std::string_view path, boost::filesystem::perms perms)
	Create directory and all necessary parent elements. Condition when path already exists and is a directory treated as "success" and no exception is thrown.
void	CreateDirectories (std::string_view path)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
void	RewriteFileContents (utils::zstring_view path, std::string_view contents)
	Rewrite file contents synchronously.
void	RewriteFileContentsFSync (utils::zstring_view path, std::string_view contents)
	Rewrite file contents synchronously and call fsync.
void	SyncDirectoryContents (utils::zstring_view path)
	flushes directory contents on disk using sync(2)
void	Rename (utils::zstring_view source, utils::zstring_view destination)
	Renames existing file synchronously.
void	RewriteFileContentsAtomically (utils::zstring_view path, std::string_view contents, boost::filesystem::perms perms)
	Rewrite file contents atomically.
void	Chmod (utils::zstring_view path, boost::filesystem::perms perms)
	Change file mode synchronously.
bool	RemoveSingleFile (utils::zstring_view path)
	Remove existing file synchronously.

Typedef Documentation

◆ OpenMode

using fs::blocking::OpenMode = utils::Flags<OpenFlag>

A set of OpenFlags.

Definition at line 43 of file open_mode.hpp.

Enumeration Type Documentation

◆ OpenFlag

enum class fs::blocking::OpenFlag

strong

Enumerator
kRead	Open the file for reading. Reading starts at the beginning of the file. At least one of kRead, kWrite must be set.
kWrite	Open the file for writing. Writing starts at the beginning of the file. By default, the file won't be created if it doesn't already exist. At least one of kRead, kWrite must be set.
kCreateIfNotExists	Used together with kWrite to create an empty file and open it for writing if it doesn't already exist.
kExclusiveCreate	Differs from kCreateIfNotExists in that it ensures that the 'open' operation creates the file.
kTruncate	Used together with kWrite to clear the contents of the file in case it already exists.
kAppend	Used together with kWrite to open file for writing to the end of the file.

Definition at line 13 of file open_mode.hpp.

Function Documentation

◆ Chmod()

void fs::blocking::Chmod	(	utils::zstring_view	path,
		boost::filesystem::perms	perms )

Change file mode synchronously.

Parameters

path	file path to chmod
perms	new file permissions

Exceptions

std::runtime_error

◆ CreateDirectories()

void fs::blocking::CreateDirectories	(	std::string_view	path,
		boost::filesystem::perms	perms )

Create directory and all necessary parent elements. Condition when path already exists and is a directory treated as "success" and no exception is thrown.

Parameters

path	directory to create
perms	new directory permissions, default=0755

Exceptions

std::runtime_error if an error occurred while creating directories

◆ FileExists()

bool fs::blocking::FileExists ( utils::zstring_view path )

Checks whether the file exists synchronously.

Parameters

path	file path to check

Returns: true if file exists, false if file doesn't exist

Exceptions

std::runtime_error if something goes wrong (e.g. out of file descriptors)

◆ GetFileType()

boost::filesystem::file_type fs::blocking::GetFileType ( utils::zstring_view path )

Get file type returned by stat(2) synchronously.

Parameters

path file path

Exceptions

std::runtime_error if something goes wrong

◆ ReadFileContents()

std::string fs::blocking::ReadFileContents ( utils::zstring_view path )

Reads file contents synchronously.

Parameters

path	file to open

Returns: file contents

Exceptions

std::runtime_error if read fails for any reason (e.g. no such file, read error, etc.),

◆ ReadRecursiveFilesInfoWithData()

FileInfoWithDataMap fs::blocking::ReadRecursiveFilesInfoWithData	(	utils::zstring_view	path,
		SettingReadFileFlags	flags )

Returns files from recursively traversed directory.

Parameters

path	to directory to traverse recursively
flags	settings read files

Returns: map with relative to path filepaths and file info

Exceptions

std::runtime_error if read fails for any reason (e.g. no such file, read error, etc.),

◆ RemoveSingleFile()

bool fs::blocking::RemoveSingleFile ( utils::zstring_view path )

Remove existing file synchronously.

Parameters

path	file path to chmod

Returns: true if successfully removed, false if file doesn't exist

Exceptions

std::runtime_error

◆ Rename()

void fs::blocking::Rename	(	utils::zstring_view	source,
		utils::zstring_view	destination )

Renames existing file synchronously.

Parameters

source	path to move from
destination	path to move to

Exceptions

std::runtime_error

◆ RewriteFileContents()

void fs::blocking::RewriteFileContents	(	utils::zstring_view	path,
		std::string_view	contents )

Rewrite file contents synchronously.

Parameters

path	file to rewrite
contents	new file contents

Exceptions

std::runtime_error if failed to overwrite

See also: fs::RewriteFileContents

◆ RewriteFileContentsAtomically()

void fs::blocking::RewriteFileContentsAtomically	(	utils::zstring_view	path,
		std::string_view	contents,
		boost::filesystem::perms	perms )

Rewrite file contents atomically.

Writes contents to a temporary file in the same directory, then atomically replaces the destination file with the temporary file. Effectively does write()+sync()+rename()+sync(directory). It does both sync(2) for file and on the directory, so after successful return the file will persist on the filesystem.

Parameters

path	file path to rewrite
contents	new file contents
perms	new file permissions

Exceptions

std::runtime_error

◆ RewriteFileContentsFSync()

void fs::blocking::RewriteFileContentsFSync	(	utils::zstring_view	path,
		std::string_view	contents )

Rewrite file contents synchronously and call fsync.

Blocks until the file is actually written to disk. This does not typically speed up the write operation, but is required for the atomic file write technique.

This function alone does not implement atomic file writes. If you need them, consider using:

See also: fs::RewriteFileContentsAtomically; fs::blocking::RewriteFileContentsAtomically

Parameters

path	file to rewrite
contents	new file contents

Exceptions

std::runtime_error if failed to overwrite

◆ SyncDirectoryContents()

void fs::blocking::SyncDirectoryContents ( utils::zstring_view path )

flushes directory contents on disk using sync(2)

Parameters

path	directory to flush

Detailed Description

Classes

Typedefs

Enumerations

Functions

Typedef Documentation

◆ OpenMode

Enumeration Type Documentation

◆ OpenFlag

Function Documentation

◆ Chmod()

◆ CreateDirectories()

◆ FileExists()

◆ GetFileType()

◆ ReadFileContents()

◆ ReadRecursiveFilesInfoWithData()

◆ RemoveSingleFile()

◆ Rename()

◆ RewriteFileContents()

◆ RewriteFileContentsAtomically()

◆ RewriteFileContentsFSync()

◆ SyncDirectoryContents()