libinotifytools
|
inotifytools library public interface. More...
Go to the source code of this file.
Classes | |
struct | nstring |
This structure holds string that can contain any character including NULL. More... | |
Functions | |
void | inotifytools_cleanup () |
const char * | inotifytools_dirname_from_event (struct inotify_event *event, size_t *dirnamelen) |
char * | inotifytools_dirpath_from_event (struct inotify_event *event) |
int | inotifytools_error () |
char * | inotifytools_event_to_str (int events) |
char * | inotifytools_event_to_str_sep (int events, char sep) |
const char * | inotifytools_filename_from_event (struct inotify_event *event, char const **eventname, size_t *dirnamelen) |
const char * | inotifytools_filename_from_watch (struct watch *w) |
const char * | inotifytools_filename_from_wd (int wd) |
int | inotifytools_fprintf (FILE *file, struct inotify_event *event, const char *fmt) |
int | inotifytools_get_max_queued_events () |
int | inotifytools_get_max_user_instances () |
int | inotifytools_get_max_user_watches () |
int | inotifytools_get_num_watches () |
int | inotifytools_ignore_events_by_inverted_regex (char const *pattern, int flags) |
int | inotifytools_ignore_events_by_regex (char const *pattern, int flags) |
int | inotifytools_init (int fanotify, int watch_filesystem, int verbose) |
struct inotify_event * | inotifytools_next_event (long int timeout) |
struct inotify_event * | inotifytools_next_events (long int timeout, int num_events) |
int | inotifytools_printf (struct inotify_event *event, const char *fmt) |
int | inotifytools_remove_watch_by_filename (char const *filename) |
int | inotifytools_remove_watch_by_wd (int wd) |
void | inotifytools_replace_filename (char const *oldname, char const *newname) |
void | inotifytools_set_filename_by_filename (char const *oldname, char const *newname) |
void | inotifytools_set_filename_by_wd (int wd, char const *filename) |
void | inotifytools_set_printf_timefmt (const char *fmt) |
int | inotifytools_snprintf (struct nstring *out, int size, struct inotify_event *event, const char *fmt) |
int | inotifytools_sprintf (struct nstring *out, struct inotify_event *event, const char *fmt) |
int | inotifytools_str_to_event (char const *event) |
int | inotifytools_str_to_event_sep (char const *event, char sep) |
int | inotifytools_watch_file (char const *filename, int events) |
int | inotifytools_watch_files (char const *filenames[], int events) |
int | inotifytools_watch_recursively (char const *path, int events) |
int | inotifytools_watch_recursively_with_exclude (char const *path, int events, char const **exclude_list) |
int | inotifytools_wd_from_filename (char const *filename) |
inotifytools library public interface.
This library provides a thin layer on top of the basic inotify interface. The primary use is to easily set up watches on files, potentially many files at once, and read events without having to deal with low-level I/O. There are also several utility functions for inotify-related string formatting.
To use this library, you must #include
the following headers accordingly:
<inotifytools/inotifytools.h>
- to use any functions declared in this file. <inotifytools/inotify.h>
- to have the inotify_event
type defined and the numeric IN_* event constants defined. If <sys/inotify.h>
was present on your system at compile time, this header simply includes that. Otherwise it includes <inotifytools/inotify-nosys.h>
.This very simple program recursively watches the entire directory tree under its working directory for events, then prints them out with a timestamp.
The following numeric events can be specified to functions in inotifytools, and may be present in events returned through inotifytools:
IN_ACCESS
- File was accessed (read) * IN_ATTRIB
- Metadata changed (permissions, timestamps, extended attributes, etc.) * IN_CLOSE_WRITE
- File opened for writing was closed * IN_CLOSE_NOWRITE
- File not opened for writing was closed * IN_CREATE
- File/directory created in watched directory * IN_DELETE
- File/directory deleted from watched directory * IN_DELETE_SELF
- Watched file/directory was itself deleted IN_MODIFY
- File was modified * IN_MOVE_SELF
- Watched file/directory was itself moved IN_MOVED_FROM
- File moved out of watched directory * IN_MOVED_TO
- File moved into watched directory * IN_OPEN
- File was opened * When monitoring a directory, the events marked with an asterisk * above can occur for files in the directory, in which case the name field in the returned inotify_event structure identifies the name of the file within the directory.
The IN_ALL_EVENTS macro is defined as a bit mask of all of the above events.
Two additional convenience macros are IN_MOVE, which equates to IN_MOVED_FROM|IN_MOVED_TO, and IN_CLOSE which equates to IN_CLOSE_WRITE|IN_CLOSE_NOWRITE.
The following bitmasks can also be provided when creating a new watch:
IN_DONT_FOLLOW
- Don't dereference pathname if it is a symbolic link IN_MASK_ADD
- Add (OR) events to watch mask for this pathname if it already exists (instead of replacing mask) IN_ONESHOT
- Monitor pathname for one event, then remove from watch list IN_ONLYDIR
- Only watch pathname if it is a directoryThe following bitmasks may occur in events generated by a watch:
IN_IGNORED
- Watch was removed explicitly (inotifytools_remove_watch_*) or automatically (file was deleted, or file system was unmounted) IN_ISDIR
- Subject of this event is a directory IN_Q_OVERFLOW
- Event queue overflowed (wd is -1 for this event) IN_UNMOUNT
- File system containing watched object was unmountedDefinition in file inotifytools.h.
void inotifytools_cleanup | ( | ) |
Close inotify and free the memory used by inotifytools.
If you call this function, you must call inotifytools_initialize() again before any other functions can be used.
Definition at line 415 of file inotifytools.cpp.
const char * inotifytools_dirname_from_event | ( | struct inotify_event * | event, |
size_t * | dirnamelen | ||
) |
Get the directory path used to establish a watch.
Returns the filename recorded for event->wd and the dirname prefix length.
The caller should NOT free() the returned string.
Definition at line 955 of file inotifytools.cpp.
References inotifytools_filename_from_wd().
Referenced by inotifytools_filename_from_event().
char * inotifytools_dirpath_from_event | ( | struct inotify_event * | event | ) |
Get the directory path from an event.
Returns the filename recorded for event->wd or NULL. For an event on non-directory also returns NULL.
The caller is responsible to free() the returned string.
Definition at line 1010 of file inotifytools.cpp.
References inotifytools_filename_from_wd().
int inotifytools_error | ( | ) |
Get the last error which occurred.
When a function fails, call this to find out why. The returned value is a typical errno value, the meaning of which depends on context. For example, if inotifytools_watch_file() fails because you attempt to watch a file which doesn't exist, this function will return ENOENT.
Definition at line 1911 of file inotifytools.cpp.
char * inotifytools_event_to_str | ( | int | events | ) |
Convert event from integer form to string form (as in inotify.h).
The returned string is from static storage; subsequent calls to this function or inotifytools_event_to_str_sep() will overwrite it. Don't free() it and make a copy if you want to keep it.
events | OR'd event(s) in integer form as defined in inotify.h. See section Events. |
Definition at line 688 of file inotifytools.cpp.
References inotifytools_event_to_str_sep().
char * inotifytools_event_to_str_sep | ( | int | events, |
char | sep | ||
) |
Convert event from integer form to string form (as in inotify.h).
The returned string is from static storage; subsequent calls to this function or inotifytools_event_to_str() will overwrite it. Don't free() it and make a copy if you want to keep it.
events | OR'd event(s) in integer form as defined in inotify.h |
sep | character used to separate events |
Definition at line 716 of file inotifytools.cpp.
Referenced by inotifytools_event_to_str().
const char * inotifytools_filename_from_event | ( | struct inotify_event * | event, |
char const ** | eventname, | ||
size_t * | dirnamelen | ||
) |
Get the watched path and filename from an event.
Returns the filename either recorded for event->wd or from event->name and the watched filename for event->wd.
The caller should NOT free() the returned strings.
Definition at line 984 of file inotifytools.cpp.
References inotifytools_dirname_from_event().
const char * inotifytools_filename_from_watch | ( | watch * | w | ) |
Get the filename from a watch.
If not stored in watch, resolve filename from fid + name and return static filename string.
Definition at line 907 of file inotifytools.cpp.
Referenced by inotifytools_filename_from_wd().
const char * inotifytools_filename_from_wd | ( | int | wd | ) |
Get the filename used to establish a watch.
inotifytools_initialize() must be called before this function can be used.
wd | watch descriptor. |
Definition at line 936 of file inotifytools.cpp.
References inotifytools_filename_from_watch().
Referenced by inotifytools_dirname_from_event(), and inotifytools_dirpath_from_event().
int inotifytools_fprintf | ( | FILE * | file, |
struct inotify_event * | event, | ||
const char * | fmt | ||
) |
Print a string to a file using an inotify_event and a printf-like syntax. The string written will only ever be up to 4096 characters in length.
file | file to print to |
event | the event to use to construct a string. |
fmt | the format string used to construct a string. |
The following tokens will be replaced with the specified string:
%w
- This will be replaced with the name of the Watched file on which an event occurred. %c
- This will be replaced with the cookie of the Watched file on which an event occurred. %f
- When an event occurs within a directory, this will be replaced with the name of the File which caused the event to occur. Otherwise, this will be replaced with an empty string. %e
- Replaced with the Event(s) which occurred, comma-separated. %Xe
- Replaced with the Event(s) which occurred, separated by whichever character is in the place of ‘X’. %T
- Replaced by the current Time in the format specified by the string previously passed to inotifytools_set_printf_timefmt(), or replaced with an empty string if that function has never been called. %0
- Replaced with the 'NUL' character %n
- Replaced with the 'Line Feed' characterDefinition at line 2037 of file inotifytools.cpp.
References nstring::buf, inotifytools_sprintf(), and nstring::len.
Referenced by inotifytools_printf().
int inotifytools_get_max_queued_events | ( | ) |
Get the event queue size.
This setting can also be read or modified by accessing the file /proc/sys/fs/inotify/max_queued_events.
Definition at line 2315 of file inotifytools.cpp.
int inotifytools_get_max_user_instances | ( | ) |
Get the maximum number of user instances of inotify.
This setting can also be read or modified by accessing the file /proc/sys/fs/inotify/max_user_instances.
Definition at line 2331 of file inotifytools.cpp.
int inotifytools_get_max_user_watches | ( | ) |
Get the maximum number of user watches.
This setting can also be read or modified by accessing the file /proc/sys/fs/inotify/max_user_watches.
Definition at line 2347 of file inotifytools.cpp.
int inotifytools_get_num_watches | ( | ) |
Get the number of watches set up through libinotifytools.
Definition at line 1938 of file inotifytools.cpp.
int inotifytools_ignore_events_by_inverted_regex | ( | char const * | pattern, |
int | flags | ||
) |
Ignore inotify events NOT matching a particular regular expression.
pattern is a regular expression and flags is a bitwise combination of POSIX regular expression flags.
On future calls to inotifytools_next_events() or inotifytools_next_event(), the regular expression is executed on the filename of files on which events occur. If the regular expression matches, the matched event will be ignored.
Definition at line 2423 of file inotifytools.cpp.
int inotifytools_ignore_events_by_regex | ( | char const * | pattern, |
int | flags | ||
) |
Ignore inotify events matching a particular regular expression.
pattern is a regular expression and flags is a bitwise combination of POSIX regular expression flags.
On future calls to inotifytools_next_events() or inotifytools_next_event(), the regular expression is executed on the filename of files on which events occur. If the regular expression matches, the matched event will be ignored.
Definition at line 2408 of file inotifytools.cpp.
int inotifytools_init | ( | int | fanotify, |
int | watch_filesystem, | ||
int | verbose | ||
) |
Initialise inotify. With @fanotify non-zero, initialize fanotify filesystem watch.
You must call this function before using any function which adds or removes watches or attempts to access any information about watches.
Definition at line 344 of file inotifytools.cpp.
struct inotify_event * inotifytools_next_event | ( | long int | timeout | ) |
Get the next inotify event to occur.
inotifytools_initialize() must be called before this function can be used.
timeout | maximum amount of time, in seconds, to wait for an event. If timeout is non-negative, the function is non-blocking. If timeout is negative, the function will block until an event occurs. |
Definition at line 1440 of file inotifytools.cpp.
References inotifytools_next_events().
struct inotify_event * inotifytools_next_events | ( | long int | timeout, |
int | num_events | ||
) |
Get the next inotify events to occur.
inotifytools_initialize() must be called before this function can be used.
timeout | maximum amount of time, in seconds, to wait for an event. If timeout is non-negative, the function is non-blocking. If timeout is negative, the function will block until an event occurs. |
num_events | approximate number of inotify events to wait for until this function returns. Use this for buffering reads to inotify if you expect to receive large amounts of events. You are NOT guaranteed that this number of events will actually be read; instead, you are guaranteed that the number of bytes read from inotify is num_events * sizeof(struct inotify_event). Obviously the larger this number is, the greater the latency between when an event occurs and when you'll know about it. May not be larger than 4096. |
Definition at line 1496 of file inotifytools.cpp.
Referenced by inotifytools_next_event().
int inotifytools_printf | ( | struct inotify_event * | event, |
const char * | fmt | ||
) |
Print a string to standard out using an inotify_event and a printf-like syntax. The string written will only ever be up to 4096 characters in length.
event | the event to use to construct a string. |
fmt | the format string used to construct a string. |
The following tokens will be replaced with the specified string:
%w
- This will be replaced with the name of the Watched file on which an event occurred. %c
- This will be replaced with the cookie of the Watched file on which an event occurred. %f
- When an event occurs within a directory, this will be replaced with the name of the File which caused the event to occur. Otherwise, this will be replaced with an empty string. %e
- Replaced with the Event(s) which occurred, comma-separated. %Xe
- Replaced with the Event(s) which occurred, separated by whichever character is in the place of ‘X’. %T
- Replaced by the current Time in the format specified by the string previously passed to inotifytools_set_printf_timefmt(), or replaced with an empty string if that function has never been called. %0
- Replaced with the 'NUL' character %n
- Replaced with the 'Line Feed' characterDefinition at line 1988 of file inotifytools.cpp.
References inotifytools_fprintf().
int inotifytools_remove_watch_by_filename | ( | char const * | filename | ) |
Remove a watch on a file specified by filename.
filename | Name of file on which watch should be removed. |
Definition at line 1217 of file inotifytools.cpp.
int inotifytools_remove_watch_by_wd | ( | int | wd | ) |
Remove a watch on a file specified by watch descriptor.
inotifytools_initialize() must be called before this function can be used.
wd | Watch descriptor of watch to be removed. |
Definition at line 1190 of file inotifytools.cpp.
void inotifytools_replace_filename | ( | char const * | oldname, |
char const * | newname | ||
) |
Replace a certain filename prefix on all watches.
This function should be used to update filenames for an entire directory tree when a directory is known to have been moved or renamed. At the moment, libinotifytools does not automatically handle this situation.
inotifytools_initialize() must be called before this function can be used.
oldname | Current filename prefix. |
newname | New filename prefix. |
Definition at line 1121 of file inotifytools.cpp.
void inotifytools_set_filename_by_filename | ( | char const * | oldname, |
char const * | newname | ||
) |
Set the filename for one or more watches with a particular existing filename.
This function should be used to update a filename when a file is known to have been moved or renamed. At the moment, libinotifytools does not automatically handle this situation.
inotifytools_initialize() must be called before this function can be used.
oldname | Current filename. |
newname | New filename. |
Definition at line 1089 of file inotifytools.cpp.
void inotifytools_set_filename_by_wd | ( | int | wd, |
char const * | filename | ||
) |
Set the filename for a particular watch descriptor.
This function should be used to update a filename when a file is known to have been moved or renamed. At the moment, libinotifytools does not automatically handle this situation.
inotifytools_initialize() must be called before this function can be used.
wd | Watch descriptor. |
filename | New filename. |
Definition at line 1065 of file inotifytools.cpp.
void inotifytools_set_printf_timefmt | ( | const char * | fmt | ) |
Set time format for printf functions.
fmt | A format string valid for use with strftime, or NULL. If NULL, time substitutions will no longer be made in printf functions. Note that this format string is not validated at all; using an incorrect format string will cause the printf functions to give incorrect results. |
Definition at line 2299 of file inotifytools.cpp.
int inotifytools_snprintf | ( | struct nstring * | out, |
int | size, | ||
struct inotify_event * | event, | ||
const char * | fmt | ||
) |
Construct a string using an inotify_event and a printf-like syntax. The string can only ever be up to 4096 characters in length.
out | location in which to store nstring. |
size | maximum amount of characters to write. |
event | the event to use to construct a nstring. |
fmt | the format string used to construct a nstring. |
The following tokens will be replaced with the specified string:
%w
- This will be replaced with the name of the Watched file on which an event occurred. %c
- This will be replaced with cookie of the Watched file on which an event occurred. %f
- When an event occurs within a directory, this will be replaced with the name of the File which caused the event to occur. Otherwise, this will be replaced with an empty string. %e
- Replaced with the Event(s) which occurred, comma-separated. %Xe
- Replaced with the Event(s) which occurred, separated by whichever character is in the place of ‘X’. %T
- Replaced by the current Time in the format specified by the string previously passed to inotifytools_set_printf_timefmt(), or replaced with an empty string if that function has never been called. %0
- Replaced with the 'NUL' character %n
- Replaced with the 'Line Feed' characterDefinition at line 2156 of file inotifytools.cpp.
Referenced by inotifytools_sprintf().
int inotifytools_sprintf | ( | struct nstring * | out, |
struct inotify_event * | event, | ||
const char * | fmt | ||
) |
Construct a string using an inotify_event and a printf-like syntax. The string can only ever be up to 4096 characters in length.
This function will keep writing until it reaches 4096 characters. If your allocated array is not large enough to hold the entire string, your program may crash. inotifytools_snprintf() is safer and you should use it where possible.
out | location in which to store nstring. |
event | the event to use to construct a nstring. |
fmt | the format string used to construct a nstring. |
The following tokens will be replaced with the specified string:
%w
- This will be replaced with the name of the Watched file on which an event occurred. %c
- This will be replaced with the cookie of the Watched file on which an event occurred. %f
- When an event occurs within a directory, this will be replaced with the name of the File which caused the event to occur. Otherwise, this will be replaced with an empty string. %e
- Replaced with the Event(s) which occurred, comma-separated. %Xe
- Replaced with the Event(s) which occurred, separated by whichever character is in the place of ‘X’. %T
- Replaced by the current Time in the format specified by the string previously passed to inotifytools_set_printf_timefmt(), or replaced with an empty string if that function has never been called. %0
- Replaced with the 'NUL' character %n
- Replaced with the 'Line Feed' characterDefinition at line 2100 of file inotifytools.cpp.
References inotifytools_snprintf().
Referenced by inotifytools_fprintf().
int inotifytools_str_to_event | ( | char const * | event | ) |
Convert comma-separated events from string form to integer form (as in inotify.h).
event | a sequence of events in string form as defined in inotify.h without leading IN_ prefix (e.g., MODIFY, ATTRIB), comma-separated. Case insensitive. Can be a single event. Can be empty or NULL. See section Events. |
Definition at line 602 of file inotifytools.cpp.
References inotifytools_str_to_event_sep().
int inotifytools_str_to_event_sep | ( | char const * | event, |
char | sep | ||
) |
Convert character separated events from string form to integer form (as in inotify.h).
event | a sequence of events in string form as defined in inotify.h without leading IN_ prefix (e.g., MODIFY, ATTRIB), separated by the sep character. Case insensitive. Can be a single event. Can be empty or NULL. See section Events. |
sep | Character used to separate events. sep must not be a character in a-z, A-Z, or _. |
Definition at line 524 of file inotifytools.cpp.
Referenced by inotifytools_str_to_event().
int inotifytools_watch_file | ( | char const * | filename, |
int | events | ||
) |
Set up a watch on a file.
filename | Absolute or relative path of file to watch. |
events | bitwise ORed inotify events to watch for. See section Events. |
Definition at line 1244 of file inotifytools.cpp.
References inotifytools_watch_files().
Referenced by inotifytools_watch_recursively_with_exclude().
int inotifytools_watch_files | ( | char const * | filenames[], |
int | events | ||
) |
Set up a watch on a list of files.
inotifytools_initialize() must be called before this function can be used.
filenames | null-terminated array of absolute or relative paths of files to watch. |
events | bitwise OR'ed inotify events to watch for. See section Events. |
Definition at line 1266 of file inotifytools.cpp.
Referenced by inotifytools_watch_file().
int inotifytools_watch_recursively | ( | char const * | path, |
int | events | ||
) |
Set up recursive watches on an entire directory tree.
inotifytools_initialize() must be called before this function can be used.
path | path of directory or file to watch. If the path is a directory, every subdirectory will also be watched for the same events up to the maximum readable depth. If the path is a file, the file is watched exactly as if inotifytools_watch_file() were used. |
events | Inotify events to watch for. See section Events. |
Definition at line 1756 of file inotifytools.cpp.
References inotifytools_watch_recursively_with_exclude().
int inotifytools_watch_recursively_with_exclude | ( | char const * | path, |
int | events, | ||
char const ** | exclude_list | ||
) |
Set up recursive watches on an entire directory tree, optionally excluding some directories.
inotifytools_initialize() must be called before this function can be used.
path | path of directory or file to watch. If the path is a directory, every subdirectory will also be watched for the same events up to the maximum readable depth. If the path is a file, the file is watched exactly as if inotifytools_watch_file() were used. |
exclude_list | NULL terminated path list of directories not to watch. Can be NULL if no paths are to be excluded. Directories may or may not include a trailing '/'. |
events | Inotify events to watch for. See section Events. |
Definition at line 1792 of file inotifytools.cpp.
References inotifytools_watch_file(), and inotifytools_watch_recursively_with_exclude().
Referenced by inotifytools_watch_recursively(), and inotifytools_watch_recursively_with_exclude().
int inotifytools_wd_from_filename | ( | char const * | filename | ) |
Get the watch descriptor for a particular filename.
inotifytools_initialize() must be called before this function can be used.
filename | file name to find watch descriptor for. |
Definition at line 1041 of file inotifytools.cpp.