fs::blocking Namespace Reference

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 (const std::string &path)
	Reads file contents synchronously.
bool	FileExists (const std::string &path)
	Checks whether the file exists synchronously.
boost::filesystem::file_type	GetFileType (const std::string &path)
	Get file type returned by stat(2) synchronously.
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 (const std::string &path, std::string_view contents)
	Rewrite file contents synchronously.
void	RewriteFileContentsFSync (const std::string &path, std::string_view contents)
	Rewrite file contents synchronously and call fsync
void	SyncDirectoryContents (const std::string &path)
	flushes directory contents on disk using sync(2)
void	Rename (const std::string &source, const std::string &destination)
	Renames existing file synchronously.
void	RewriteFileContentsAtomically (const std::string &path, std::string_view contents, boost::filesystem::perms perms)
	Rewrite file contents atomically.
void	Chmod (const std::string &path, boost::filesystem::perms perms)
	Change file mode synchronously.
bool	RemoveSingleFile (const std::string &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	(	const std::string &	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

(

const std::string &

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

(

const std::string &

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

(

const std::string &

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.),

RemoveSingleFile()

bool fs::blocking::RemoveSingleFile

(

const std::string &

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	(	const std::string &	source,
		const std::string &	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	(	const std::string &	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	(	const std::string &	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	(	const std::string &	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

(

const std::string &

path

)

flushes directory contents on disk using sync(2)

Parameters

path	directory to flush