userver: fs::blocking Namespace Reference
Loading...
Searching...
No Matches
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

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
pathfile path to chmod
permsnew 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
pathdirectory to create
permsnew directory permissions, default=0755
Exceptions
std::runtime_errorif an error occurred while creating directories

◆ FileExists()

bool fs::blocking::FileExists ( const std::string & path)

Checks whether the file exists synchronously.

Parameters
pathfile path to check
Returns
true if file exists, false if file doesn't exist
Exceptions
std::runtime_errorif 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
pathfile path
Exceptions
std::runtime_errorif something goes wrong

◆ ReadFileContents()

std::string fs::blocking::ReadFileContents ( const std::string & path)

Reads file contents synchronously.

Parameters
pathfile to open
Returns
file contents
Exceptions
std::runtime_errorif 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
pathfile 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
sourcepath to move from
destinationpath 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
pathfile to rewrite
contentsnew file contents
Exceptions
std::runtime_errorif 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
pathfile path to rewrite
contentsnew file contents
permsnew 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
pathfile to rewrite
contentsnew file contents
Exceptions
std::runtime_errorif failed to overwrite

◆ SyncDirectoryContents()

void fs::blocking::SyncDirectoryContents ( const std::string & path)

flushes directory contents on disk using sync(2)

Parameters
pathdirectory to flush