Event type manipulation. More...

#include <time.h>
#include <limits.h>
#include <stdbool.h>
#include "libfswatch_types.h"

Classes
struct	fsw_cevent
struct	fsw_cevent_v2

Typedefs
typedef struct fsw_cevent	fsw_cevent
typedef struct fsw_cevent_v2	fsw_cevent_v2
typedef void(*	FSW_CEVENT_CALLBACK) (fsw_cevent const const events, const unsigned int event_num, void data)
typedef void(*	FSW_CEVENT_CALLBACK_V2) (fsw_cevent_v2 const const events, const unsigned int event_num, void data)

Enumerations
enum	fsw_event_flag { NoOp = 0 , PlatformSpecific = (1 << 0) , Created = (1 << 1) , Updated = (1 << 2) , Removed = (1 << 3) , Renamed = (1 << 4) , OwnerModified = (1 << 5) , AttributeModified = (1 << 6) , MovedFrom = (1 << 7) , MovedTo = (1 << 8) , IsFile = (1 << 9) , IsDir = (1 << 10) , IsSymLink = (1 << 11) , Link = (1 << 12) , Overflow = (1 << 13) , CloseWrite = (1 << 14) }
	Backend-agnostic change flags. More...
enum	fsw_process_id_kind { FSW_PROCESS_ID_NONE = 0 , FSW_PROCESS_ID_PID , FSW_PROCESS_ID_TID }
	Type of process identifier associated with an event. More...

Functions
FSW_STATUS	fsw_get_event_flag_by_name (const char name, enum fsw_event_flag flag)
	Get event flag by name.
char *	fsw_get_event_flag_name (const enum fsw_event_flag flag)
	Get the name of an event flag.

Variables
enum fsw_event_flag	FSW_ALL_EVENT_FLAGS [16]

Detailed Description

Event type manipulation.

This header file defines the event types of the libfswatch API.

Copyright: Copyright (c) 2014-2026 Enrico M. Crisostomo

License:\n GNU General Public License v. 3.0

Author: Enrico M. Crisostomo

Version: 13:1:0 TODO: Update version number reflecting changes of the API.

Typedef Documentation

◆ fsw_cevent

typedef struct fsw_cevent fsw_cevent

A file change event is represented as an instance of this struct where:

path is the path where the event was triggered.
evt_time the time when the event was triggered.
flags is an array of fsw_event_flag of size flags_num.
flags_num is the size of the flags array.

◆ FSW_CEVENT_CALLBACK

typedef void(* FSW_CEVENT_CALLBACK) (fsw_cevent const *const events, const unsigned int event_num, void *data)

A function pointer of type FSW_CEVENT_CALLBACK is used by the API as a callback to provide information about received events. The callback is passed the following arguments:

events, a const pointer to an array of events of type const fsw_cevent.
event_num, the size of the *events array.
data, optional persisted data for a callback.

The memory used by the fsw_cevent objects will be freed at the end of the callback invocation. A callback should copy such data instead of storing a pointer to it.

◆ FSW_CEVENT_CALLBACK_V2

typedef void(* FSW_CEVENT_CALLBACK_V2) (fsw_cevent_v2 const *const events, const unsigned int event_num, void *data)

A callback receiving events with extended metadata.

◆ fsw_cevent_v2

typedef struct fsw_cevent_v2 fsw_cevent_v2

A file change event with extended metadata.

This type is additive and preserves the ABI of fsw_cevent. The process file descriptor is owned by libfswatch and is valid only while the callback is executing.

Enumeration Type Documentation

◆ fsw_event_flag

enum fsw_event_flag

Backend-agnostic change flags.

Each element of this enum represents a backend-agnostic change flag. No direct mapping to backend-specific change types is guaranteed to exist: a change type may be mapped to multiple fsw_event_flag instances included the PlatformSpecific flag.

The values of event flags are all powers of 2, that is numbers $f=2^n$ where $n$ is an integer. This representation makes it easy to combine flags into a bit mask and encode multiple events flags into a single integer.

A monitor implementation is required to map implementation-specific flags into API flags. Sometimes, though, a perfect match is not possible and the following situation may arise:

One platform-specific flag must be mapped into multiple API flags.
Multiple platform-specific flags must be mapped into a single API flag.
A mapping is not possible for some flags, in which case they should be mapped to fsw_event_flag::PlatformSpecific. The API currently offers no way to retain a platform-specific event flag value in this case.

Enumerator
NoOp	No event has occurred.
PlatformSpecific	Platform-specific placeholder for event type that cannot currently be mapped.
Created	An object was created.
Updated	An object was updated.
Removed	An object was removed.
Renamed	An object was renamed.
OwnerModified	The owner of an object was modified.
AttributeModified	The attributes of an object were modified.
MovedFrom	An object was moved from this location.
MovedTo	An object was moved to this location.
IsFile	The object is a file.
IsDir	The object is a directory.
IsSymLink	The object is a symbolic link.
Link	The link count of an object has changed.
Overflow	The event queue has overflowed.
CloseWrite	A file was closed after being opened in write mode.

◆ fsw_process_id_kind

enum fsw_process_id_kind

Type of process identifier associated with an event.

Enumerator
FSW_PROCESS_ID_NONE	No process attribution is available.
FSW_PROCESS_ID_PID	The identifier is a process ID.
FSW_PROCESS_ID_TID	The identifier is a thread ID.

Function Documentation

◆ fsw_get_event_flag_by_name()

FSW_STATUS fsw_get_event_flag_by_name	(	const char *	name,
		enum fsw_event_flag *	flag )

Get event flag by name.

This function looks for an event flag called name and, if it exists, it writes its value onto flag and FSW_OK, otherwise flag is not modified and FSW_ERR_UNKNOWN_VALUE is returned.

Parameters

[in]	name	The name of the event flag to look for.
[out]	flag	The output variable where the event flag is returned.

Returns: FSW_OK if the functions succeeds, FSW_ERR_UNKNOWN_VALUE otherwise.

◆ fsw_get_event_flag_name()

char * fsw_get_event_flag_name ( const enum fsw_event_flag flag )

Get the name of an event flag.

This function looks for the name of the specified event flag. If it exists, it returns its name, otherwise nullptr is returned.

Parameters

[in] flag The event flag to look for.

Returns: The name of flag, or nullptr if it does not exist.

Classes

Typedefs

Enumerations

Functions

Variables