local_filesys Class Reference

This class can be used to enumerate the contents of local directories and to query the metadata of files. More...

#include <local_filesys.hpp>

Public Types
enum	type { unknown = -1 , file , dir , link }
	Types of files. While 'everything is a file', a filename can refer to a file proper, a directory or a symbolic link. More...

Public Member Functions
	local_filesys (local_filesys const &)=delete
local_filesys &	operator= (local_filesys const &)=delete
	local_filesys (local_filesys &&) noexcept
local_filesys &	operator= (local_filesys &&) noexcept
result	begin_find_files (native_string path, bool dirs_only=false, bool query_symlink_targets=true)
	Begins enumerating a directory.
result	begin_find_files (file::file_t fd, bool dirs_only=false, bool query_symlink_targets=true)
	Begin enumerating a directory represented by a descriptor.
bool	get_next_file (native_string &name)
	Gets the next file in the directory. Call until it returns false.
bool	get_next_file (native_string &name, bool &is_link, type &t, int64_t *size, datetime *modification_time, int *mode)
	Gets the next file in the directory. Call until it returns false.
void	end_find_files ()
	Ends enumerating files. Automatically called in the destructor.
file::file_t	fd ()
	Returns the raw descriptor/handle, but retains ownership.

Static Public Member Functions
static bool	is_separator (wchar_t c)
	Checks whether given character is a path separator.
static type	get_file_type (native_string const &path, bool follow_links=false)
	get_file_type return the type of the passed path.
static type	get_file_info (native_string const &path, bool &is_link, int64_t *size, datetime *modification_time, int *mode, bool follow_links=true)
	Gets the info for the passed arguments.
static result	get_file_info (native_string const &path, bool &is_link, typetype &typetype, int64_t *size, datetime *modification_time, int *mode, bool follow_links=true)
	Gets the info for the passed arguments.
static int64_t	get_size (native_string const &path, bool *is_link=nullptr)
	Gets size of file, returns -1 on error.
static datetime	get_modification_time (native_string const &path)
static result	set_modification_time (native_string const &path, const datetime &t)
static result	get_modification_time (file::file_t fd, datetime &t)
	Gets the modification time of an open file or directory.
static result	set_modification_time (file::file_t fd, datetime const &t)
	Sets the modification time of an open file or directory.
static native_string	get_link_target (native_string const &path)
	Get the immediate target path of a symbolic link. Only consideres the immediate link. Output may be be relative.
static native_string	get_final_link_target (native_string const &path)
	Get the final target path of a symbolic link (chain).

Static Public Attributes
static char const	path_separator
	The system's preferred path separator.

Detailed Description

This class can be used to enumerate the contents of local directories and to query the metadata of files.

This class is aware of symbolic links. Under Windows it can handle reparse points as well.

Examples

list.cpp.

Member Enumeration Documentation

type

enum type

Types of files. While 'everything is a file', a filename can refer to a file proper, a directory or a symbolic link.

Examples

list.cpp.

Member Function Documentation

begin_find_files() [1/2]

result begin_find_files	(	file::file_t	fd,
		bool	dirs_only = false,
		bool	query_symlink_targets = true )

Begin enumerating a directory represented by a descriptor.

Takes ownership of descriptor/handle.

begin_find_files() [2/2]

result begin_find_files	(	native_string	path,
		bool	dirs_only = false,
		bool	query_symlink_targets = true )

Begins enumerating a directory.

Parameters

dirs_only

If true, only directories are enumerated.

Examples

list.cpp.

get_file_info() [1/2]

type get_file_info ( native_string const & path, bool & is_link, int64_t * size, datetime * modification_time, int * mode, bool follow_links = true )

static

Gets the info for the passed arguments.

Follows symbolic links and stats the target by default, sets is_link to true if path was a link.

The returned type can only be type::link if follow_links is false.

get_file_info() [2/2]

result get_file_info ( native_string const & path, bool & is_link, type & type, int64_t * size, datetime * modification_time, int * mode, bool follow_links = true )

static

Gets the info for the passed arguments.

Follows symbolic links and stats the target by default, sets is_link to true if path was a link.

This overload additionally takes a type reference out parameter, which could be set to type::link only if follow_links is false.

get_file_type()

type get_file_type ( native_string const & path, bool follow_links = false )

static

get_file_type return the type of the passed path.

Can optionally follow symbolic links.

get_final_link_target()

native_string get_final_link_target ( native_string const & path )

static

Get the final target path of a symbolic link (chain).

Result is absolute.

get_link_target()

native_string get_link_target ( native_string const & path )

static

Get the immediate target path of a symbolic link. Only consideres the immediate link. Output may be be relative.

Examples

list.cpp.

get_modification_time()

result get_modification_time ( file::file_t fd, datetime & t )

static

Gets the modification time of an open file or directory.

The descriptor or handle is borrowed and is not closed by this function. On Windows, the handle must have FILE_READ_ATTRIBUTES access.

On failure, t is unchanged and the result retains the native error code.

get_next_file() [1/2]

bool get_next_file

(

native_string &

name

)

Gets the next file in the directory. Call until it returns false.

Examples

list.cpp.

get_next_file() [2/2]

bool get_next_file	(	native_string &	name,
		bool &	is_link,
		type &	t,
		int64_t *	size,
		datetime *	modification_time,
		int *	mode )

Gets the next file in the directory. Call until it returns false.

Stores the metadata in any non-null arguments. Follows symbolic links iff begin_find_files was called with query_symlink_targets set to true.

Parameters

is_link	will be set to true iff file is a symbolic link.
t	will receive the type of file. If query_symlink_targets was set it cannot return type::link.

is_separator()

bool is_separator ( wchar_t c )

inlinestatic

Checks whether given character is a path separator.

On most systems, the forward slash is the only separator. The exception is Windows where both forward and backward slashes are separators, with the latter being preferred.

set_modification_time()

result set_modification_time ( file::file_t fd, datetime const & t )

static

Sets the modification time of an open file or directory.

The descriptor or handle is borrowed and is not closed by this function. On Windows, the access time is also updated. If access is denied, the same object is temporarily reopened with FILE_WRITE_ATTRIBUTES access. Reopening uses the calling thread's current security context, not the identity that originally opened the handle. Callers using impersonation must invoke this function under the intended identity. Reopening can fail because of access or sharing restrictions; its native error is returned. The original handle and its file position are unchanged. On other systems, the access time is unchanged and no reopening occurs.

An empty timestamp, or a Windows FILETIME with a zero high word, returns result::invalid with a raw error of zero. Operating system errors retain their native error code.

---

The documentation for this class was generated from the following file:

• local_filesys.hpp