fswatch 1.17.1
Namespaces | Classes | Typedefs | Functions | Variables
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  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...
 
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. More...
 
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. More...
 
template<typename K >
using fsw_hash_set = std::set< K >
 Default set type used by libfswatch. More...
 
typedef void FSW_EVENT_CALLBACK(const std::vector< event > &, void *)
 Function definition of an event callback. More...
 
using poll_monitor_data = poll_monitor::poll_monitor_data { fsw_hash_map< string, poll_monitor::watched_file_info > tracked_files
 

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. More...
 
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_filterread_from_file (const std::string &path, void(*err_handler)(std::string)=nullptr)
 Load filters from the specified file. More...
 
static vector< FSEventFlagType > create_flag_type_vector ()
 
static vector< fsw_event_flagdecode_flags (FSEventStreamEventFlags flag)
 
static monitorcreate_default_monitor (std::vector< std::string > paths, FSW_EVENT_CALLBACK *callback, void *context)
 
vector< string > get_directory_children (const string &path)
 
bool read_link_path (const string &path, string &link_path)
 
std::string fsw_realpath (const char *path, char *resolved_path)
 A thin wrapper about realpath. More...
 
bool stat_path (const string &path, struct stat &fd_stat)
 
bool lstat_path (const string &path, struct stat &fd_stat)
 
std::vector< std::string > get_directory_children (const std::string &path)
 Gets a vector of direct directory children. More...
 
bool read_link_path (const std::string &path, std::string &link_path)
 Resolves a path name. More...
 
bool lstat_path (const std::string &path, struct stat &fd_stat)
 Wraps a lstat(path, fd_stat) call that invokes perror() if it fails. More...
 
bool stat_path (const std::string &path, struct stat &fd_stat)
 Wraps a stat(path, fd_stat) call that invokes perror() if it fails. More...
 
static vector< win_flag_typecreate_flag_type_vector ()
 
static vector< fsw_event_flagdecode_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. More...
 
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 vector< win_flag_typeevent_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

◆ fsw_realpath()

std::string fsw::fsw_realpath ( const char *  path,
char *  resolved_path 
)

A thin wrapper about realpath.

Parameters
pathThe path to resolve.
resolved_pathA pointer to a buffer where the resolved path is stored.
Returns
If there is no error, realpath() returns a string, otherwise it throws a std::system_error.

◆ get_directory_children()

std::vector< std::string > fsw::get_directory_children ( const std::string &  path)

Gets a vector of direct directory children.

Parameters
pathThe directory whose children must be returned.
Returns
A vector containing the list of children 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
pathThe path to lstat().
fd_statThe 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
outA reference to the output stream.
flagThe 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
pathThe path of the file to read filters from.
err_handlerAn optional error handler.
Returns
A vector containing the valid filters.
Exceptions
invalid_argumentIf the specified path cannot be opened.

◆ read_link_path()

bool fsw::read_link_path ( const std::string &  path,
std::string &  link_path 
)

Resolves a path name.

This function resolves path using realpath() and stores the absolute pathname into link_path. The function returns true if it succeeds, false otherwise.

Parameters
pathThe path to resolve.
link_pathA reference to a std::string where the resolved absolute path should be copied to.
Returns
true if the function succeeds, false otherwise.

◆ stat_path()

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
pathThe path to stat().
fd_statThe stat structure where stat() writes its results.
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