File system and file path features (in addition to std::filesystem). More...

Collaboration diagram for File system:

Classes
class	ts::FileNameGenerator
class	ts::FileTreeManager
class	ts::PolledFile
class	ts::PollFiles
class	ts::PollFilesListener

Functions
UString	ts::AbsoluteFilePath (const UString &path, const UString &base=UString())
UString	ts::BaseName (const UString &path, const UString &suffix=UString())
UString	ts::CleanupFilePath (const UString &path)
UString	ts::DirectoryName (const UString &path)
template<class CONTAINER>
bool	ts::ExpandWildcard (CONTAINER &container, const UString &pattern)
template<class CONTAINER>
bool	ts::ExpandWildcardAndAppend (CONTAINER &container, const UString &pattern)
Time	ts::GetFileModificationTimeLocal (const UString &path)
Time	ts::GetFileModificationTimeUTC (const UString &path)
bool	ts::IsAbsoluteFilePath (const UString &path)
UString	ts::RelativeFilePath (const UString &path, const UString &base=UString(), CaseSensitivity case_sensitivity=FILE_SYSTEM_CASE_SENSITVITY, bool portable_slashes=false)
UString	ts::SafeRelativeFilePath (const UString &path, UChar separator=fs::path::preferred_separator)
UString	ts::SearchConfigurationFile (const UString &file_name)
UString	ts::SearchExecutableFile (const UString &file_name, const UString &path_name=PATH_ENVIRONMENT_VARIABLE)
template<class CONTAINER>
bool	ts::SearchWildcard (CONTAINER &container, const UString &root, const UString &pattern, size_t max_levels=64, bool skip_symlinks=true)
template<class CONTAINER>
bool	ts::SearchWildcardAndAppend (CONTAINER &container, const UString &root, const UString &pattern, size_t max_levels=64, bool skip_symlinks=true)
bool	ts::SetFileModificationTimeLocal (const UString &path, const Time &time)
bool	ts::SetFileModificationTimeUTC (const UString &path, const Time &time)
fs::path	ts::TempFile (const UString &suffix=u".tmp")
UString	ts::UserConfigurationFileName (const UString &file_name, const UString &win_file_name=UString())
fs::path	ts::UserHomeDirectory ()
UString	ts::VernacularFilePath (const UString &path)

Variables
constexpr const UChar *	ts::DEFAULT_CSV_SEPARATOR = u","
constexpr const UChar *	ts::EXECUTABLE_FILE_SUFFIX = platform - specific(".exe", "")
constexpr CaseSensitivity	ts::FILE_SYSTEM_CASE_SENSITVITY = platform-specific
constexpr const UChar *	ts::SHARED_LIBRARY_SUFFIX = platform - specific(".dll", ".so", ".dylib")

Detailed Description

File system and file path features (in addition to std::filesystem).

Function Documentation

◆ VernacularFilePath()

UString ts::VernacularFilePath ( const UString & path )

Return a "vernacular" version of a file path.

Parameters

[in] path A file path.

Returns: A copy of path where all '/' and '\' have been translated into the local directory separator. On Windows, a file path starting with '/' which cannot be translated as a valid Windows absolute path becomes a relative path.

◆ IsAbsoluteFilePath()

bool ts::IsAbsoluteFilePath ( const UString & path )

Check if a file path is absolute (starting at a root of a file system).

Parameters

[in] path A file path.

Returns: True if path is an absolute file path.

◆ AbsoluteFilePath()

UString ts::AbsoluteFilePath	(	const UString &	path,
		const UString &	base = UString() )

Build the absolute form of a file path.

Parameters

[in]	path	A file path.
[in]	base	The base directory to use if path is a relative file path. By default, when base is empty, the current working directory is used.

Returns: The absolute form of path after cleanup.

◆ RelativeFilePath()

UString ts::RelativeFilePath	(	const UString &	path,
		const UString &	base = UString(),
		CaseSensitivity	case_sensitivity = FILE_SYSTEM_CASE_SENSITVITY,
		bool	portable_slashes = false )

Build a relative form of a file path, relative to a base directory.

Parameters

[in]	path	A file path.
[in]	base	The base directory to use. By default, when base is empty, the current working directory is used.
[in]	case_sensitivity	Case sensitivity of file names comparison. By default, use the local file system case sensitivity.
[in]	portable_slashes	If true, the relative path contains forward slashes ('/'), even on Windows. The resulting path can be used in relative URL's for instance.

Returns: The absolute form of path after cleanup.

◆ SafeRelativeFilePath()

UString ts::SafeRelativeFilePath	(	const UString &	path,
		UChar	separator = fs::path::preferred_separator )

Build a safe form of a file path to mitigate file traversal attacks. All attempts to move up ('..') are removed. If the path is absolute, the root is removed and it becomes a relative path. This means that the final path may not be equivalent to the original one but it is safe to use when the path comes from some untrusted source. Example: "/a/b/c/../d/e" is returned as "a/b/c/d/e".

Parameters

[in]	path	A file path.
[in]	separator	The path separator to use on output. By default, this is the preferred separator of the system but there are cases where '/' may be preferred (relative URLs for instance)

Returns: The safe form of path, as arelative path.

◆ CleanupFilePath()

UString ts::CleanupFilePath ( const UString & path )

Cleanup a file path.

Parameters

[in] path A file path.

Returns: The clean form of path. Double slashes are removed. Forms such as "." or ".." are reduced.

◆ DirectoryName()

UString ts::DirectoryName ( const UString & path )

Return the directory name of a file path ("dir/foo.bar" => "dir").

Parameters

[in] path A file path.

Returns: The directory name of path ("dir/foo.bar" => "dir").

◆ BaseName()

UString ts::BaseName	(	const UString &	path,
		const UString &	suffix = UString() )

Return the base file name of a file path ("dir/foo.bar" => "foo.bar").

Parameters

[in]	path	A file path.
[in]	suffix	An optional file suffix. If path ends in suffix, the suffix is removed.

Returns: The base file name of path ("dir/foo.bar" => "foo.bar").

◆ UserHomeDirectory()

fs::path ts::UserHomeDirectory ( )

Get the current user's home directory.

Returns: The full path of the current user's home directory.

Exceptions

ts::Exception In case of operating system error.

◆ TempFile()

fs::path ts::TempFile ( const UString & suffix = u".tmp" )

Return the name of a unique temporary file.

Parameters

[in] suffix An optional suffix to add to the file name.

Returns: A unique temporary file name.

◆ GetFileModificationTimeLocal()

Time ts::GetFileModificationTimeLocal ( const UString & path )

Get the local time of the last modification of a file.

Parameters

[in] path A file path.

Returns: Last modification time or Time::Epoch in case of error.

◆ GetFileModificationTimeUTC()

Time ts::GetFileModificationTimeUTC ( const UString & path )

Get the UTC time of the last modification of a file.

Parameters

[in] path A file path.

Returns: Last modification time or Time::Epoch in case of error.

◆ SetFileModificationTimeLocal()

bool ts::SetFileModificationTimeLocal	(	const UString &	path,
		const Time &	time )

Set the local time of the last modification of a file.

Parameters

[in]	path	A file path.
[in]	time	The modification local time to set.

Returns: True on success, false on error.

◆ SetFileModificationTimeUTC()

bool ts::SetFileModificationTimeUTC	(	const UString &	path,
		const Time &	time )

Set the UTC time of the last modification of a file.

Parameters

[in]	path	A file path.
[in]	time	The modification UTC time to set.

Returns: True on success, false on error.

◆ ExpandWildcardAndAppend()

template<class CONTAINER>

bool ts::ExpandWildcardAndAppend	(	CONTAINER &	container,
		const UString &	pattern )

Get all files matching a specified wildcard pattern and append them into a container.

Template Parameters

CONTAINER A container class of UString as defined by the C++ Standard Template Library (STL).

Parameters

[in,out]	container	A container of `UString` receiving the the names of all files matching the wildcard. The names are appended at the end of the existing content of the container.
[in]	pattern	A file path pattern with wildcards. The syntax of the wildcards is system-dependent.

Returns: True on success, false on error. Note that finding no file matching the pattern is not an error, it simply return no file name.

◆ ExpandWildcard()

template<class CONTAINER>

bool ts::ExpandWildcard	(	CONTAINER &	container,
		const UString &	pattern )

inline

Get all files matching a specified wildcard pattern.

Template Parameters

CONTAINER A container class of UString as defined by the C++ Standard Template Library (STL).

Parameters

[out]	container	A container of `UString` receiving the the names of all files matching the wildcard.
[in]	pattern	A file path pattern with wildcards. The syntax of the wildcards is system-dependent.

Returns: True on success, false on error. Note that finding no file matching the pattern is not an error, it simply return no file name.

◆ SearchWildcardAndAppend()

template<class CONTAINER>

bool ts::SearchWildcardAndAppend	(	CONTAINER &	container,
		const UString &	root,
		const UString &	pattern,
		size_t	max_levels = 64,
		bool	skip_symlinks = true )

Search all files matching a specified wildcard pattern in a directory tree and append them into a container.

Template Parameters

CONTAINER A container class of UString as defined by the C++ Standard Template Library (STL).

Parameters

[in,out]	container	A container of `UString` receiving the the names of all files matching the wildcard. The names are appended at the end of the existing content of the container.
[in]	root	Root directory into which the files are searched.
[in]	pattern	A file path pattern with wildcards. The syntax of the wildcards is system-dependent.
[in]	max_levels	Maximum number of directory recursions. Since some operating systems allow loops in the file system, it is a good idea to set some limit to avoid infinite recursion.
[in]	skip_symlinks	If true, do not recurse through symbolic links to directories.

Returns: True on success, false on error. Note that finding no file matching the pattern is not an error, it simply return no file name.

◆ SearchWildcard()

template<class CONTAINER>

bool ts::SearchWildcard	(	CONTAINER &	container,
		const UString &	root,
		const UString &	pattern,
		size_t	max_levels = 64,
		bool	skip_symlinks = true )

inline

Search all files matching a specified wildcard pattern in a directory tree.

Template Parameters

CONTAINER A container class of UString as defined by the C++ Standard Template Library (STL).

Parameters

[out]	container	A container of `UString` receiving the the names of all files matching the wildcard.
[in]	root	Root directory into which the files are searched.
[in]	pattern	A file path pattern with wildcards. The syntax of the wildcards is system-dependent.
[in]	max_levels	Maximum number of directory recursions. Since some operating systems allow loops in the file system, it is a good idea to set some limit to avoid infinite recursion.
[in]	skip_symlinks	If true, do not recurse through symbolic links to directories.

Returns: True on success, false on error. Note that finding no file matching the pattern is not an error, it simply return no file name.

◆ SearchExecutableFile()

UString ts::SearchExecutableFile	(	const UString &	file_name,
		const UString &	path_name = PATH_ENVIRONMENT_VARIABLE )

Search an executable file.

Parameters

[in]	file_name	Name of the file to search.
[in]	path_name	Name of the seach path environment variable.

Returns: The path to an existing file or an empty path if not found.

◆ SearchConfigurationFile()

UString ts::SearchConfigurationFile ( const UString & file_name )

Search a configuration file.

Parameters

[in]

file_name

Name of the file to search. If fileName is not found and does not contain any directory part, search this file in the following places:

All directories in TSPLUGINS_PATH environment variable.
Directory of the current executable.
Directory ../etc/tsduck from current executable (UNIX only).
Directory ../../etc/tsduck from current executable (UNIX only).
Directory ../lib64/tsduck from current executable (64-bit UNIX only).
Directory ../lib/tsduck from current executable (UNIX only).
Directory ../share/tsduck from current executable (UNIX only).
All directories in LD_LIBRARY_PATH environment variable (UNIX only).
All directories in PATH (UNIX) or Path (Windows) environment variable.

Returns: The path to an existing file or an empty string if not found.

◆ UserConfigurationFileName()

UString ts::UserConfigurationFileName	(	const UString &	file_name,
		const UString &	win_file_name = UString() )

Build the name of a user-specific configuration file.

Parameters

[in]	file_name	Base name of the configuration file.
[in]	win_file_name	Alternative base name on Windows. If empty, file_name is used.

Returns

The path to the user-specific configuration file. The file may exist or not. The default file location depends on the operating system:

Windows: %APPDATA%\tsduck
Unix: $HOME

Variable Documentation

◆ EXECUTABLE_FILE_SUFFIX

const UChar* ts::EXECUTABLE_FILE_SUFFIX = platform - specific(".exe", "")

constexpr

Executable file suffix.

◆ SHARED_LIBRARY_SUFFIX

const UChar* ts::SHARED_LIBRARY_SUFFIX = platform - specific(".dll", ".so", ".dylib")

constexpr

File name extension of shared library file names (".so" on Linux, '.dylib" on macOS, ".dll" on Windows).

◆ FILE_SYSTEM_CASE_SENSITVITY

CaseSensitivity ts::FILE_SYSTEM_CASE_SENSITVITY = platform-specific

constexpr

Case-sensitivity of the names in the file system.

◆ DEFAULT_CSV_SEPARATOR

const UChar* ts::DEFAULT_CSV_SEPARATOR = u","

constexpr

Default separator in CSV (comma-separated values) format. CSV files are suitable for analysis using tools such as Microsoft Excel.

Classes

Functions

Variables

Detailed Description

Function Documentation

◆ VernacularFilePath()

◆ IsAbsoluteFilePath()

◆ AbsoluteFilePath()

◆ RelativeFilePath()

◆ SafeRelativeFilePath()

◆ CleanupFilePath()

◆ DirectoryName()

◆ BaseName()

◆ UserHomeDirectory()

◆ TempFile()

◆ GetFileModificationTimeLocal()

◆ GetFileModificationTimeUTC()

◆ SetFileModificationTimeLocal()

◆ SetFileModificationTimeUTC()

◆ ExpandWildcardAndAppend()

◆ ExpandWildcard()

◆ SearchWildcardAndAppend()

◆ SearchWildcard()

◆ SearchExecutableFile()

◆ SearchConfigurationFile()

◆ UserConfigurationFileName()

Variable Documentation

◆ EXECUTABLE_FILE_SUFFIX

◆ SHARED_LIBRARY_SUFFIX

◆ FILE_SYSTEM_CASE_SENSITVITY

◆ DEFAULT_CSV_SEPARATOR