fsw Namespace Reference

Main namespace of libfswatch. More...

Namespaces
namespace	string_utils
	This namespace contains string manipulation functions.
namespace	win_paths
	Path conversion functions.
namespace	win_strings
	String conversion functions.

Classes
struct	compiled_monitor_filter
class	directory_change_event
	Header of the fsw::directory_change_event class, a helper class to wrap Microsoft Windows' ReadDirectoryChangesW function and a common workflow to detect file system changes. More...
class	event
	Type representing a file change event. More...
class	fanotify_monitor
	Linux fanotify monitor. More...
struct	fanotify_monitor_impl
class	fen_monitor
	Solaris/Illumos monitor. More...
class	fsevents_monitor
	macOS FSEvents monitor. More...
class	inotify_monitor
	Solaris/Illumos monitor. More...
struct	inotify_monitor_impl
class	kqueue_monitor
	Solaris/Illumos monitor. More...
class	libfsw_exception
	Base exception of the libfswatch library. More...
class	monitor
	Base class of all monitors. More...
class	monitor_factory
	Object factory class for fsw::monitor instances. More...
class	poll_monitor
	stat()-based monitor. More...
struct	process_metadata
struct	scoped_fd
class	win_error_message
	Helper class to get the system-defined error message for a Microsoft Windows' error code. More...
struct	win_flag_type
class	win_handle
	A RAII wrapper around Microsoft Windows HANDLE. More...
class	windows_monitor
	Windows monitor. More...

Typedefs
using	monitor_filter = monitor_filter { std::string text
	Path filters used to accept or reject file change events.
using	FSEventFlagType = FSEventFlagType { FSEventStreamEventFlags flag
template<typename K , typename V >
using	fsw_hash_map = std::map< K, V >
	Default associative container type used by libfswatch.
template<typename K >
using	fsw_hash_set = std::set< K >
	Default set type used by libfswatch.
typedef void	FSW_EVENT_CALLBACK(const std::vector< event > &, void *)
	Function definition of an event callback.
using	poll_monitor_data = poll_monitor::poll_monitor_data { std::unordered_map< string, poll_monitor::watched_file_info > tracked_files

Enumerations
enum class	process_id_kind { none = 0 , pid , tid }

Functions
ostream &	operator<< (ostream &out, const fsw_event_flag flag)
std::ostream &	operator<< (std::ostream &out, const fsw_event_flag flag)
	Overload of the << operator to print an event using iostreams.
static bool	parse_filter (std::string filter, monitor_filter &filter_object, void(*err_handler)(std::string))
static bool	is_unescaped_space (string &filter, long i)
static bool	parse_filter (string filter, monitor_filter &filter_object, void(*err_handler)(string))
static std::vector< monitor_filter >	read_from_file (const std::string &path, void(*err_handler)(std::string)=nullptr)
	Load filters from the specified file.
static vector< FSEventFlagType >	create_flag_type_vector ()
static vector< fsw_event_flag >	decode_flags (FSEventStreamEventFlags flag)
static int	latency_to_timeout_ms (double latency)
static void	add_epoll_interest (int epoll_fd, int fd)
static void	drain_eventfd (int fd)
static monitor *	create_default_monitor (std::vector< std::string > paths, FSW_EVENT_CALLBACK *callback, void *context)
std::vector< std::filesystem::directory_entry >	get_directory_entries (const std::filesystem::path &path)
	Gets a vector of direct directory entries.
std::vector< std::filesystem::directory_entry >	get_subdirectories (const std::filesystem::path &path)
	Gets a vector of direct subdirectories.
bool	stat_path (const std::string &path, struct stat &fd_stat, bool follow_symlink)
	Wraps a stat(path, fd_stat) call or a lstat(path, fd_stat) call, depending on the value of follow_symlink. The function invokes perror() if it fails.
bool	stat_path (const std::string &path, struct stat &fd_stat)
	Wraps a stat(path, fd_stat) call that invokes perror() if it fails.
bool	lstat_path (const std::string &path, struct stat &fd_stat)
	Wraps a lstat(path, fd_stat) call that invokes perror() if it fails.
static vector< win_flag_type >	create_flag_type_vector ()
static vector< fsw_event_flag >	decode_flags (DWORD flag)

Variables
fsw_filter_type	type
	Filter type.
bool	case_sensitive
	Flag indicating whether monitor_filter::text is a case sensitive regular expression.
bool	extended
	Flag indicating whether monitor_filter::text is an extended regular expression.
static const vector< FSEventFlagType >	event_flag_type = create_flag_type_vector()
static const unsigned int	BUFFER_SIZE = (10 * ((sizeof(struct inotify_event)) + NAME_MAX + 1))
static const int	EPOLL_EVENT_COUNT = 2
static const vector< win_flag_type >	event_flag_type = create_flag_type_vector()

Detailed Description

Main namespace of libfswatch.

Typedef Documentation

FSW_EVENT_CALLBACK

typedef void fsw::FSW_EVENT_CALLBACK(const std::vector< event > &, void *)

Function definition of an event callback.

The event callback is a user-supplied function that is invoked by the monitor when an event is detected. The following parameters are passed to the callback:

• A reference to the vector of events.
• A pointer to the context data set by the caller.

fsw_hash_map

template<typename K , typename V >

using fsw::fsw_hash_map = typedef std::map<K, V>

Default associative container type used by libfswatch.

This type definition will be a synonym of std::unordered_map if the C++ library contains it, otherwise it will default to std::map.

fsw_hash_set

template<typename K >

using fsw::fsw_hash_set = typedef std::set<K>

Default set type used by libfswatch.

This type definition will be a synonym of std::unordered_set if the C++ library contains it, otherwise it will default to std::set.

monitor_filter

using fsw::monitor_filter = typedef monitor_filter { std::string text

Path filters used to accept or reject file change events.

A path filter is a regular expression used to accept or reject file change events based on the value of their path. A filter has the following characteristics:

• It has a regular expression (monitor_filter::text), used to match the paths.
• It can be an inclusion or an exclusion filter (monitor_filter::type).
• It can be case sensitive or insensitive (monitor_filter::case_sensitive).
• It can be an extended regular expression (monitor_filter::extended).

Further information about how filtering works in libfswatch can be found in Path Filtering.

Function Documentation

get_directory_entries()

std::vector< std::filesystem::directory_entry > fsw::get_directory_entries

(

const std::filesystem::path &

path

)

Gets a vector of direct directory entries.

Parameters

path	The directory whose entries must be returned.

Returns

A vector containing the list of entries of path.

Since

1.18.0

get_subdirectories()

std::vector< std::filesystem::directory_entry > fsw::get_subdirectories

(

const std::filesystem::path &

path

)

Gets a vector of direct subdirectories.

Parameters

path	The directory whose subdirectories must be returned.

Returns

A vector containing the list of subdirectories of path.

lstat_path()

bool fsw::lstat_path	(	const std::string &	path,
		struct stat &	fd_stat
	)

Wraps a lstat(path, fd_stat) call that invokes perror() if it fails.

Parameters

path	The path to lstat().
fd_stat	The stat structure where lstat() writes its results.

Returns

true if the function succeeds, false otherwise.

operator<<()

std::ostream & fsw::operator<<	(	std::ostream &	out,
		const fsw_event_flag	flag
	)

Overload of the << operator to print an event using iostreams.

Parameters

out	A reference to the output stream.
flag	The flag to print.

Returns

A reference to the stream.

read_from_file()

static std::vector< monitor_filter > fsw::read_from_file ( const std::string &  path, void(*)(std::string)  err_handler = nullptr  )

static

Load filters from the specified file.

Filters can be loaded from a text file containing one filter per line. A filter has the following structure:

• It is validated by the following regular expression: ^([+-])([ei]*) (.+)$
• The first character is the filter type: + if it is an inclusion filter, - if it is an exclusion filter.
• An optional list of flags:
  • e if it is an extended regular expression.
  • i if it is a case insensitive regular expression.
• A space.
• The filter regular expression text.

Parsing errors are notified through an optional error handler. The valid filters are returned in a vector.

Parameters

path	The path of the file to read filters from.
err_handler	An optional error handler.

Returns

A vector containing the valid filters.

Exceptions

invalid_argument

If the specified path cannot be opened.

stat_path() [1/2]

bool fsw::stat_path	(	const std::string &	path,
		struct stat &	fd_stat
	)

Wraps a stat(path, fd_stat) call that invokes perror() if it fails.

Parameters

path	The path to stat().
fd_stat	The stat structure where stat() writes its results.

Returns

true if the function succeeds, false otherwise.

stat_path() [2/2]

bool fsw::stat_path	(	const std::string &	path,
		struct stat &	fd_stat,
		bool	follow_symlink
	)

Wraps a stat(path, fd_stat) call or a lstat(path, fd_stat) call, depending on the value of follow_symlink. The function invokes perror() if it fails.

Parameters

path	The path to stat() or lstat().
fd_stat	The stat structure where stat() or lstat() writes its results.
follow_symlink	true if the function should call lstat(), false if it should call stat().

Returns

true if the function succeeds, false otherwise.

Variable Documentation

extended

bool fsw::extended

Flag indicating whether monitor_filter::text is an extended regular expression.

Further information about extended regular expressions can be found here:

http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04