libinotifytools
Functions
inotifytools.h File Reference

inotifytools library public interface. More...

Go to the source code of this file.

Functions

void inotifytools_cleanup ()
 
int inotifytools_error ()
 
char * inotifytools_event_to_str (int events)
 
char * inotifytools_event_to_str_sep (int events, char sep)
 
char * inotifytools_filename_from_wd (int wd)
 
int inotifytools_fprintf (FILE *file, struct inotify_event *event, 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_get_stat_by_filename (char const *filename, int event)
 
int inotifytools_get_stat_by_wd (int wd, int event)
 
int inotifytools_get_stat_total (int event)
 
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_initialize ()
 
void inotifytools_initialize_stats ()
 
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, 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 (char *fmt)
 
int inotifytools_snprintf (char *out, int size, struct inotify_event *event, char *fmt)
 
int inotifytools_sprintf (char *out, struct inotify_event *event, 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)
 

Detailed Description

inotifytools library public interface.

Author
Rohan McGovern, <rohan.nosp@m.@mcg.nosp@m.overn.nosp@m..id..nosp@m.au>

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:

Example

This very simple program recursively watches the entire directory tree under its working directory for events, then prints them out with a timestamp.

#include <stdio.h>
#include <string.h>
#include <inotifytools/inotify.h>
/*
* libinotifytools example program.
* Compile with gcc -linotifytools example.c
*/
int main() {
// initialize and watch the entire directory tree from the current working
// directory downwards for all events
|| !inotifytools_watch_recursively( ".", IN_ALL_EVENTS ) ) {
fprintf(stderr, "%s\n", strerror( inotifytools_error() ) );
return -1;
}
// set time format to 24 hour time, HH:MM:SS
// Output all events as "<timestamp> <path> <events>"
struct inotify_event * event = inotifytools_next_event( -1 );
while ( event ) {
inotifytools_printf( event, "%T %w%f %e\n" );
event = inotifytools_next_event( -1 );
}
}

Events

Note
This section comes almost verbatim from the inotify(7) man page.
Warning
The information here applies to inotify in Linux 2.6.17. Older versions of Linux may not support all the events described here.

The following numeric events can be specified to functions in inotifytools, and may be present in events returned through inotifytools:

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:

The following bitmasks may occur in events generated by a watch:

TODO list

Todo:
Improve wd/filename mapping. Currently there is no explicit code for handling different filenames mapping to the same inode (and hence, wd). gamin's approach sounds good: let the user watch an inode using several different filenames, and when an event occurs on the inode, generate an event for each filename.

Definition in file inotifytools.h.

Function Documentation

◆ inotifytools_cleanup()

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 329 of file inotifytools.c.

◆ inotifytools_error()

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.

Returns
an error code.

Definition at line 1608 of file inotifytools.c.

◆ inotifytools_event_to_str()

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.

Parameters
eventsOR'd event(s) in integer form as defined in inotify.h. See section Events.
Returns
comma-separated string representing the event(s), in no particular order

Example

int eventnum == IN_MODIFY | IN_CLOSE | IN_CREATE;
char * eventstr = inotifytools_event_to_str( eventnum );
printf( "%s\n", eventstr );
// outputs something like MODIFY,CLOSE,CREATE but order not guaranteed.

Definition at line 642 of file inotifytools.c.

References inotifytools_event_to_str_sep().

Referenced by inotifytools_snprintf().

◆ 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.

Parameters
eventsOR'd event(s) in integer form as defined in inotify.h
sepcharacter used to separate events
Returns
sep separated string representing the event(s), in no particular order. If the integer is not made of OR'ed inotify events, the string returned will be a hexadecimal representation of the integer.

Example

int eventnum == IN_MODIFY | IN_CLOSE | IN_CREATE;
char * eventstr = inotifytools_event_to_str_sep( eventnum, '-' );
printf( "%s\n", eventstr );
// outputs something like MODIFY-CLOSE-CREATE but order not guaranteed.

Definition at line 670 of file inotifytools.c.

Referenced by inotifytools_event_to_str(), and inotifytools_snprintf().

◆ inotifytools_filename_from_wd()

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.

Parameters
wdwatch descriptor.
Returns
filename associated with watch descriptor wd, or NULL if wd is not associated with any filename.
Note
This always returns the filename which was used to establish a watch. This means the filename may be a relative path. If this isn't desired, then always use absolute paths when watching files. Also, this is not necessarily the filename which might have been used to cause an event on the file, since inotify is inode based and there can be many filenames mapping to a single inode. Finally, if a file is moved or renamed while being watched, the filename returned will still be the original name.

Definition at line 777 of file inotifytools.c.

Referenced by inotifytools_snprintf().

◆ inotifytools_fprintf()

int inotifytools_fprintf ( FILE *  file,
struct inotify_event *  event,
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.

Parameters
filefile to print to
eventthe event to use to construct a string.
fmtthe format string used to construct a string.
Returns
number of characters written, or -1 if an error occurs.

Format string syntax

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.
  • %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.

Example

// suppose this is the only file watched.
inotifytools_watch_file( "mydir/", IN_CLOSE );
// wait until an event occurs
struct inotify_event * event = inotifytools_next_event( -1 );
inotifytools_fprintf(stderr, event, "in %w, file %f had event(s): %.e\n");
// suppose the file 'myfile' in mydir was read from and closed. Then,
// this prints to standard error something like:
// "in mydir/, file myfile had event(s): CLOSE_NOWRITE.CLOSE.ISDIR\n"

Definition at line 1725 of file inotifytools.c.

References inotifytools_sprintf().

Referenced by inotifytools_printf().

◆ inotifytools_get_max_queued_events()

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.

Returns
the maximum number of events which will be queued in the kernel.

Definition at line 1973 of file inotifytools.c.

◆ inotifytools_get_max_user_instances()

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.

Returns
the maximum number of inotify file descriptors a single user can obtain.

Definition at line 1988 of file inotifytools.c.

◆ inotifytools_get_max_user_watches()

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.

Returns
the maximum number of inotify watches a single user can obtain per inotify instance.

Definition at line 2003 of file inotifytools.c.

◆ inotifytools_get_num_watches()

int inotifytools_get_num_watches ( )

Get the number of watches set up through libinotifytools.

Returns
number of watches set up by inotifytools_watch_file(), inotifytools_watch_files() and inotifytools_watch_recursively().

Definition at line 1634 of file inotifytools.c.

◆ inotifytools_get_stat_by_filename()

int inotifytools_get_stat_by_filename ( char const *  filename,
int  event 
)

Get statistics by a particular filename.

inotifytools_initialize_stats() must be called before this function can be used.

Parameters
filenamename of file to get stats for.
eventa single inotify event to get statistics for, or 0 for event total. See section Events.
Returns
the number of times the event specified by event has occurred on the file specified by filename since stats collection was enabled, or -1 if the file is not being watched or event is invalid.
Note
The filename specified must always be the original name used to establish the watch.

Definition at line 1592 of file inotifytools.c.

References inotifytools_get_stat_by_wd(), and inotifytools_wd_from_filename().

◆ inotifytools_get_stat_by_wd()

int inotifytools_get_stat_by_wd ( int  wd,
int  event 
)

Get statistics by a particular watch descriptor.

inotifytools_initialize_stats() must be called before this function can be used.

Parameters
wdwatch descriptor to get stats for.
eventa single inotify event to get statistics for, or 0 for event total. See section Events.
Returns
the number of times the event specified by event has occurred on the watch descriptor specified by wd since stats collection was enabled, or -1 if event or wd are invalid.

Definition at line 1515 of file inotifytools.c.

Referenced by inotifytools_get_stat_by_filename().

◆ inotifytools_get_stat_total()

int inotifytools_get_stat_total ( int  event)

Get statistics aggregated across all watches.

inotifytools_initialize_stats() must be called before this function can be used.

Parameters
eventa single inotify event to get statistics for, or 0 for event total. See section Events.
Returns
the number of times the event specified by event has occurred over all watches since stats collection was enabled, or -1 if event is not a valid event.

Definition at line 1538 of file inotifytools.c.

◆ inotifytools_ignore_events_by_inverted_regex()

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 2072 of file inotifytools.c.

◆ inotifytools_ignore_events_by_regex()

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 2057 of file inotifytools.c.

◆ inotifytools_initialize()

int inotifytools_initialize ( )

Initialise inotify.

You must call this function before using any function which adds or removes watches or attempts to access any information about watches.

Returns
1 on success, 0 on failure. On failure, the error can be obtained from inotifytools_error().

Definition at line 284 of file inotifytools.c.

◆ inotifytools_initialize_stats()

void inotifytools_initialize_stats ( )

Initialize or reset statistics.

inotifytools_initialize() must be called before this function can be used.

When this function is called, all subsequent events will be tallied. Statistics can then be obtained via the inotifytools_get_stat_* functions.

After the first call, subsequent calls to this function will reset the event tallies to 0.

Definition at line 426 of file inotifytools.c.

◆ inotifytools_next_event()

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.

Parameters
timeoutmaximum 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.
Returns
pointer to an inotify event, or NULL if function timed out before an event occurred. The event is located in static storage and it may be overwritten in subsequent calls; do not call free() on it, and make a copy if you want to keep it.
Note
Your program should call this function or inotifytools_next_events() frequently; between calls to this function, inotify events will be queued in the kernel, and eventually the queue will overflow and you will miss some events.
If the function inotifytools_ignore_events_by_regex() has been called with a non-NULL parameter, this function will not return on events which match the regular expression passed to that function. However, the timeout period begins again each time a matching event occurs.

Definition at line 1055 of file inotifytools.c.

References inotifytools_next_events().

◆ 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.

Parameters
timeoutmaximum 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_eventsapproximate 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.
Returns
pointer to an inotify event, or NULL if function timed out before an event occurred or num_events < 1. The event is located in static storage and it may be overwritten in subsequent calls; do not call free() on it, and make a copy if you want to keep it. When num_events is greater than 1, this will return a pointer to the first event only, and you MUST call this function again to get pointers to subsequent events; don't try to add to the pointer to find the next events or you will run into trouble.
Note
You may actually get different events with different values of num_events. This is because inotify does some in-kernel filtering of duplicate events, meaning some duplicate events will not be reported if num_events > 1. For some purposes this is fine, but for others (such as gathering accurate statistics on numbers of event occurrences) you must call this function with num_events = 1, or simply use inotifytools_next_event().
Your program should call this function frequently; between calls to this function, inotify events will be queued in the kernel, and eventually the queue will overflow and you will miss some events.
If the function inotifytools_ignore_events_by_regex() has been called with a non-NULL parameter, this function will not return on events which match the regular expression passed to that function. However, the timeout period begins again each time a matching event occurs.

Definition at line 1108 of file inotifytools.c.

Referenced by inotifytools_next_event().

◆ inotifytools_printf()

int inotifytools_printf ( struct inotify_event *  event,
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.

Parameters
eventthe event to use to construct a string.
fmtthe format string used to construct a string.
Returns
number of characters written, or -1 if an error occurs.

Format string syntax

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.
  • %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.

Example

// suppose this is the only file watched.
inotifytools_watch_file( "mydir/", IN_CLOSE );
// wait until an event occurs
struct inotify_event * event = inotifytools_next_event( -1 );
inotifytools_printf(stderr, event, "in %w, file %f had event(s): %.e\n");
// suppose the file 'myfile' in mydir was read from and closed. Then,
// this prints to standard out something like:
// "in mydir/, file myfile had event(s): CLOSE_NOWRITE.CLOSE.ISDIR\n"

Definition at line 1680 of file inotifytools.c.

References inotifytools_fprintf().

◆ inotifytools_remove_watch_by_filename()

int inotifytools_remove_watch_by_filename ( char const *  filename)

Remove a watch on a file specified by filename.

Parameters
filenameName of file on which watch should be removed.
Returns
1 on success, 0 on failure. On failure, the error can be obtained from inotifytools_error().
Note
The filename specified must always be the original name used to establish the watch.

Definition at line 947 of file inotifytools.c.

◆ inotifytools_remove_watch_by_wd()

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.

Parameters
wdWatch descriptor of watch to be removed.
Returns
1 on success, 0 on failure. If the given watch doesn't exist, returns 1. On failure, the error can be obtained from inotifytools_error().

Definition at line 924 of file inotifytools.c.

◆ inotifytools_replace_filename()

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.

Parameters
oldnameCurrent filename prefix.
newnameNew filename prefix.

Example

// if /home/user1/original_dir is moved to /home/user2/new_dir, then to
// update all watches:
inotifytools_replace_filename( "/home/user1/original_dir",
"/home/user2/new_dir" );

Definition at line 873 of file inotifytools.c.

◆ inotifytools_set_filename_by_filename()

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.

Parameters
oldnameCurrent filename.
newnameNew filename.

Definition at line 843 of file inotifytools.c.

◆ inotifytools_set_filename_by_wd()

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.

Parameters
wdWatch descriptor.
filenameNew filename.

Definition at line 821 of file inotifytools.c.

◆ inotifytools_set_printf_timefmt()

void inotifytools_set_printf_timefmt ( char *  fmt)

Set time format for printf functions.

Parameters
fmtA 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 1961 of file inotifytools.c.

◆ inotifytools_snprintf()

int inotifytools_snprintf ( char *  out,
int  size,
struct inotify_event *  event,
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.

Parameters
outlocation in which to store string.
sizemaximum amount of characters to write.
eventthe event to use to construct a string.
fmtthe format string used to construct a string.
Returns
number of characters written, or -1 if an error occurs.

Format string syntax

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.
  • %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.

Example

// suppose this is the only file watched.
inotifytools_watch_file( "mydir/", IN_CLOSE );
// wait until an event occurs
struct inotify_event * event = inotifytools_next_event( -1 );
char mystring[1024];
inotifytools_snprintf( mystring, 1024, event,
"in %w, file %f had event(s): %.e\n" );
printf( mystring );
// suppose the file 'myfile' in mydir was written to and closed. Then,
// this prints something like:
// "in mydir/, file myfile had event(s): CLOSE_WRITE.CLOSE.ISDIR\n"

Definition at line 1834 of file inotifytools.c.

References inotifytools_event_to_str(), inotifytools_event_to_str_sep(), and inotifytools_filename_from_wd().

Referenced by inotifytools_sprintf().

◆ inotifytools_sprintf()

int inotifytools_sprintf ( char *  out,
struct inotify_event *  event,
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.

Parameters
outlocation in which to store string.
eventthe event to use to construct a string.
fmtthe format string used to construct a string.
Returns
number of characters written, or -1 if an error occurs.

Format string syntax

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.
  • %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.

Example

// suppose this is the only file watched.
inotifytools_watch_file( "mydir/", IN_CLOSE );
// wait until an event occurs
struct inotify_event * event = inotifytools_next_event( -1 );
char mystring[1024];
// hope this doesn't crash - if filename is really long, might not fit into
// mystring!
inotifytools_sprintf(mystring, event, "in %w, file %f had event(s): %.e\n");
printf( mystring );
// suppose the file 'myfile' in mydir was written to and closed. Then,
// this prints something like:
// "in mydir/, file myfile had event(s): CLOSE_WRITE.CLOSE.ISDIR\n"

Definition at line 1783 of file inotifytools.c.

References inotifytools_snprintf().

Referenced by inotifytools_fprintf().

◆ inotifytools_str_to_event()

int inotifytools_str_to_event ( char const *  event)

Convert comma-separated events from string form to integer form (as in inotify.h).

Parameters
eventa 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.
Returns
integer representing the mask specified by event, or 0 if any string in event is empty or NULL, or -1 if any string in event does not match any event.

Example

char * eventstr = "MODIFY,CLOSE,CREATE";
int eventnum = inotifytools_str_to_event( eventstr );
if ( eventnum == IN_MODIFY | IN_CLOSE | IN_CREATE ) {
printf( "This code always gets executed!\n" );
}

Definition at line 555 of file inotifytools.c.

References inotifytools_str_to_event_sep().

◆ 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).

Parameters
eventa 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.
sepCharacter used to separate events. sep must not be a character in a-z, A-Z, or _.
Returns
integer representing the mask specified by event, or 0 if any string in event is empty or NULL, or -1 if any string in event does not match any event or sep is invalid.

Example

char * eventstr = "MODIFY:CLOSE:CREATE";
int eventnum = inotifytools_str_to_event_sep( eventstr, ':' );
if ( eventnum == IN_MODIFY | IN_CLOSE | IN_CREATE ) {
printf( "This code always gets executed!\n" );
}

Definition at line 479 of file inotifytools.c.

Referenced by inotifytools_str_to_event().

◆ inotifytools_watch_file()

int inotifytools_watch_file ( char const *  filename,
int  events 
)

Set up a watch on a file.

Parameters
filenameAbsolute or relative path of file to watch.
eventsbitwise ORed inotify events to watch for. See section Events.
Returns
1 on success, 0 on failure. On failure, the error can be obtained from inotifytools_error().

Definition at line 970 of file inotifytools.c.

References inotifytools_watch_files().

Referenced by inotifytools_watch_recursively_with_exclude().

◆ inotifytools_watch_files()

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.

Parameters
filenamesnull-terminated array of absolute or relative paths of files to watch.
eventsbitwise OR'ed inotify events to watch for. See section Events.
Returns
1 on success, 0 on failure. On failure, the error can be obtained from inotifytools_error().

Definition at line 992 of file inotifytools.c.

Referenced by inotifytools_watch_file().

◆ inotifytools_watch_recursively()

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.

Parameters
pathpath 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.
eventsInotify events to watch for. See section Events.
Returns
1 on success, 0 on failure. On failure, the error can be obtained from inotifytools_error(). Note that some errors on subdirectories will be ignored; for example, if you watch a directory tree which contains some directories which you do not have access to, those directories will not be watched, but this function will still return 1 if no other errors occur.
Note
This function does not attempt to work atomically. If you use this function to watch a directory tree and files or directories are being created or removed within that directory tree, there are no guarantees as to whether or not those files will be watched.

Definition at line 1266 of file inotifytools.c.

References inotifytools_watch_recursively_with_exclude().

◆ 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.

Author
UH
Parameters
pathpath 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_listNULL 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 '/'.
eventsInotify events to watch for. See section Events.
Returns
1 on success, 0 on failure. On failure, the error can be obtained from inotifytools_error(). Note that some errors on subdirectories will be ignored; for example, if you watch a directory tree which contains some directories which you do not have access to, those directories will not be watched, but this function will still return 1 if no other errors occur.
Note
This function does not attempt to work atomically. If you use this function to watch a directory tree and files or directories are being created or removed within that directory tree, there are no guarantees as to whether or not those files will be watched.

Definition at line 1302 of file inotifytools.c.

References inotifytools_watch_file().

Referenced by inotifytools_watch_recursively().

◆ inotifytools_wd_from_filename()

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.

Parameters
filenamefile name to find watch descriptor for.
Returns
watch descriptor associated with filename, or -1 if filename is not associated with any watch descriptor.
Note
The filename specified must always be the original name used to establish the watch.

Definition at line 800 of file inotifytools.c.

Referenced by inotifytools_get_stat_by_filename().

inotifytools_initialize
int inotifytools_initialize()
Definition: inotifytools.c:284
inotifytools_set_printf_timefmt
void inotifytools_set_printf_timefmt(char *fmt)
Definition: inotifytools.c:1961
inotifytools_sprintf
int inotifytools_sprintf(char *out, struct inotify_event *event, char *fmt)
Definition: inotifytools.c:1783
inotifytools_event_to_str_sep
char * inotifytools_event_to_str_sep(int events, char sep)
Definition: inotifytools.c:670
inotifytools_printf
int inotifytools_printf(struct inotify_event *event, char *fmt)
Definition: inotifytools.c:1680
inotifytools_fprintf
int inotifytools_fprintf(FILE *file, struct inotify_event *event, char *fmt)
Definition: inotifytools.c:1725
inotifytools_event_to_str
char * inotifytools_event_to_str(int events)
Definition: inotifytools.c:642
inotifytools_watch_file
int inotifytools_watch_file(char const *filename, int events)
Definition: inotifytools.c:970
inotifytools_error
int inotifytools_error()
Definition: inotifytools.c:1608
inotifytools.h
inotifytools library public interface.
inotifytools_str_to_event
int inotifytools_str_to_event(char const *event)
Definition: inotifytools.c:555
inotifytools_replace_filename
void inotifytools_replace_filename(char const *oldname, char const *newname)
Definition: inotifytools.c:873
inotifytools_next_event
struct inotify_event * inotifytools_next_event(long int timeout)
Definition: inotifytools.c:1055
inotifytools_str_to_event_sep
int inotifytools_str_to_event_sep(char const *event, char sep)
Definition: inotifytools.c:479
inotifytools_snprintf
int inotifytools_snprintf(char *out, int size, struct inotify_event *event, char *fmt)
Definition: inotifytools.c:1834
inotifytools_watch_recursively
int inotifytools_watch_recursively(char const *path, int events)
Definition: inotifytools.c:1266