bcache::file Namespace Reference

File utility functions and classes. More...

Classes
class	exe_path_t
	Path to an executable file. More...
class	file_info_t
	Information about a file. More...
class	file_lock_t
	A scoped exclusive global lock class. More...
class	scoped_work_dir_t
	A helper class for temporarily changing the current working dir (CWD). More...
class	tmp_file_t
	A helper class for handling temporary files and directories. More...

Functions
std::string	canonicalize_path (const std::string &path)
	Get the canonical form of a path. More...
std::string	get_extension (const std::string &path)
	Get the file extension of a path. More...
std::string	change_extension (const std::string &path, const std::string &new_ext)
	Change the file extension of a path. More...
std::string	get_file_part (const std::string &path, const bool include_ext=true)
	Get the file name part of a path. More...
std::string	get_dir_part (const std::string &path)
	Get the directory part of a path. More...
std::string	get_temp_dir ()
	Get a temporary directory for this user and process. More...
std::string	get_user_home_dir ()
	Get the user home directory. More...
std::string	get_cwd ()
	Get the current working directory. More...
void	set_cwd (const std::string &path)
	Set the current working directory. More...
std::string	resolve_path (const std::string &path)
	Resolve a path. More...
exe_path_t	find_executable (const std::string &program, const std::string &exclude=std::string())
	Find the true path to an executable file. More...
void	create_dir (const std::string &path)
	Create a directory. More...
void	create_dir_with_parents (const std::string &path)
	Create a directory and its parent directories. More...
void	remove_file (const std::string &path, const bool ignore_errors=false)
	Remove an existing file. More...
void	remove_dir (const std::string &path, const bool ignore_errors=false)
	Remove a directory and all its contents (recursively). More...
bool	dir_exists (const std::string &path)
	Check if a directory exists. More...
bool	file_exists (const std::string &path)
	Check if a file exists. More...
void	move (const std::string &from_path, const std::string &to_path)
	Move a file from an old location to a new location. More...
void	copy (const std::string &from_path, const std::string &to_path)
	Make a full copy of a file. More...
void	link_or_copy (const std::string &from_path, const std::string &to_path)
	Make a hard link or a full copy of a file. More...
void	touch (const std::string &path)
	Touch the file to update the modification time. More...
std::string	read (const std::string &path)
	Read a file into a string. More...
void	write (const std::string &data, const std::string &path)
	Write a string to a file. More...
void	write_atomic (const std::string &data, const std::string &path)
	Write a string to a file in an atomic fashion. More...
void	append (const std::string &data, const std::string &path)
	Append a string to a file. More...
file_info_t	get_file_info (const std::string &path)
	Get file information about a single file or directory. More...
std::string	human_readable_size (const int64_t byte_size)
	Convert a size to a human readable string. More...
std::vector< file_info_t >	walk_directory (const std::string &path)
	Walk a directory and its subdirectories. More...
std::string	get_unique_id ()
	Create a unique ID string. More...

Detailed Description

File utility functions and classes.

Function Documentation

append()

void bcache::file::append	(	const std::string &	data,
		const std::string &	path
	)

Append a string to a file.

Parameters

data	The data string to write.
path	The path to the file.

Exceptions

runtime_error

if the operation could not be completed.

Note

Multiple processes may append to the same file concurrently.

append_path()

std::string bcache::file::append_path	(	const std::string &	path,
		const std::string &	append
	)

Append two paths.

Parameters

path	The base path.
append	The path to be appended (e.g. a file name).

Returns

the concatenated paths, using the system path separator.

Note

If path is empty or append is empty, the result will not contain any path separator.

canonicalize_path()

std::string bcache::file::canonicalize_path

(

const std::string &

path

)

Get the canonical form of a path.

The returned path is absolute, and free of relative operators ("." and "..").

Parameters

path	The path to canonicalize.

Returns

the canonical form of the given path.

change_extension()

std::string bcache::file::change_extension	(	const std::string &	path,
		const std::string &	new_ext
	)

Change the file extension of a path.

Parameters

path	The path to a file.
new_ext	The new file extension (including the leading period) for the file.

Returns

The path to the file that has the new file extension.

copy()

void bcache::file::copy	(	const std::string &	from_path,
		const std::string &	to_path
	)

Make a full copy of a file.

Parameters

from_path	The source file.
to_path	The destination file.

Exceptions

runtime_error

if the operation could not be completed.

create_dir()

void bcache::file::create_dir

(

const std::string &

path

)

Create a directory.

Parameters

path	The path to the directory.

Exceptions

runtime_error

if the directory could not be created.

create_dir_with_parents()

void bcache::file::create_dir_with_parents

(

const std::string &

path

)

Create a directory and its parent directories.

This function will create parent directories if required (similar to mkdir -p), and if the specified directory does not already exist, it is created (unlike create_dir, which will always try to create the directory).

Parameters

path	The path to the directory.

Exceptions

runtime_error

if the directory could not be created.

dir_exists()

bool bcache::file::dir_exists

(

const std::string &

path

)

Check if a directory exists.

Parameters

path	The path to the directory.

Returns

true if the directory exists.

file_exists()

bool bcache::file::file_exists

(

const std::string &

path

)

Check if a file exists.

Parameters

path	The path to the file.

Returns

true if the file exists.

find_executable()

exe_path_t bcache::file::find_executable	(	const std::string &	program,
		const std::string &	exclude = std::string()
	)

Find the true path to an executable file.

Parameters

program	The file to find.
exclude	A file name to exclude (excluding the file extension).

Returns

an exe_path_t object with extended path information for the executable file.

Exceptions

runtime_error

if the executable file could not be found.

get_cwd()

std::string bcache::file::get_cwd

(

)

Get the current working directory.

Returns

the full path to the current working directory.

Exceptions

runtime_error

if the current working directory could not be determined.

get_dir_part()

std::string bcache::file::get_dir_part

(

const std::string &

path

)

Get the directory part of a path.

Parameters

path	The path to a file.

Returns

The part of the path before the final path separator. If the path does not contain a separator, an empty string is returned.

get_extension()

std::string bcache::file::get_extension

(

const std::string &

path

)

Get the file extension of a path.

Parameters

path	The path to a file.

Returns

The file extension of the file (including the leading period), or an empty string if the file does not have an extension.

get_file_info()

file_info_t bcache::file::get_file_info

(

const std::string &

path

)

Get file information about a single file or directory.

Parameters

path	The path to the file (or directory).

Returns

a file information object.

get_file_part()

std::string bcache::file::get_file_part	(	const std::string &	path,
		const bool	include_ext = true
	)

Get the file name part of a path.

Parameters

path	The path to a file.
include_ext	Include the file extension in the file name.

Returns

The part of the path after the final path separator. If the path does not contain a separator, the entire path is returned.

get_temp_dir()

std::string bcache::file::get_temp_dir

(

)

Get a temporary directory for this user and process.

Returns

the full path to the temporary directory.

get_unique_id()

std::string bcache::file::get_unique_id

(

)

Create a unique ID string.

Returns

a string that contains a unique ID.

get_user_home_dir()

std::string bcache::file::get_user_home_dir

(

)

Get the user home directory.

Returns

the full path to the user home directory.

human_readable_size()

std::string bcache::file::human_readable_size

(

const int64_t

byte_size

)

Convert a size to a human readable string.

Parameters

byte_size

The size (number of bytes).

Returns

a string containing a human readable version of the size, e.g. "4.7 MiB".

link_or_copy()

void bcache::file::link_or_copy	(	const std::string &	from_path,
		const std::string &	to_path
	)

Make a hard link or a full copy of a file.

A hard link will be performed if possible. Otherwise a full copy will be made.

Parameters

from_path	The source file.
to_path	The destination file.

Exceptions

runtime_error

if the operation could not be completed.

move()

void bcache::file::move	(	const std::string &	from_path,
		const std::string &	to_path
	)

Move a file from an old location to a new location.

Parameters

from_path	The source file.
to_path	The destination file.

Exceptions

runtime_error

if the operation could not be completed.

read()

std::string bcache::file::read

(

const std::string &

path

)

Read a file into a string.

Parameters

path	The path to the file.

Returns

the contents of the file as a string.

Exceptions

runtime_error

if the operation could not be completed.

remove_dir()

void bcache::file::remove_dir	(	const std::string &	path,
		const bool	ignore_errors = false
	)

Remove a directory and all its contents (recursively).

Parameters

path	The path to the dir.
ignore_errors	Set this to true to ignore errors related to removing files.

Exceptions

runtime_error

if the dir could not be removed.

remove_file()

void bcache::file::remove_file	(	const std::string &	path,
		const bool	ignore_errors = false
	)

Remove an existing file.

Parameters

path	The path to the file.
ignore_errors	Set this to true to ignore errors related to removing files.

Exceptions

runtime_error

if the file could not be removed.

resolve_path()

std::string bcache::file::resolve_path

(

const std::string &

path

)

Resolve a path.

Relative paths are converted into absolute paths, and symbolic links are resolved.

Parameters

path	The path to resolve.

Returns

an absolute path to a regular file, or an empty string if the path could not be resolved.

set_cwd()

void bcache::file::set_cwd

(

const std::string &

path

)

Set the current working directory.

Parameters

path	the path to the new working directory.

Exceptions

runtime_error

if the current working directory could not be changed.

touch()

void bcache::file::touch

(

const std::string &

path

)

Touch the file to update the modification time.

Parameters

path	The path to the file.

Exceptions

runtime_error

if the operation could not be completed.

walk_directory()

std::vector< file_info_t > bcache::file::walk_directory

(

const std::string &

path

)

Walk a directory and its subdirectories.

Parameters

path	The path to the directory.

Returns

a vector of file information objects.

Note

Directories are listed after any files that are contained within the directories.

write()

void bcache::file::write	(	const std::string &	data,
		const std::string &	path
	)

Write a string to a file.

Parameters

data	The data string to write.
path	The path to the file.

Exceptions

runtime_error

if the operation could not be completed.

write_atomic()

void bcache::file::write_atomic	(	const std::string &	data,
		const std::string &	path
	)

Write a string to a file in an atomic fashion.

The target file will either be written in whole, or the function will fail.

Parameters

data	The data string to write.
path	The path to the file.

Exceptions

runtime_error

if the operation could not be completed.