inotify_watch.h File Reference

Public interface for inotify backend to log watch. More...

#include "lwatch.h"

Go to the source code of this file.

Classes
struct	path_watch_t
	When a watch is established on a filesystem directory this struct is used to track it. More...
Defines
#define	INOTIFY_WATCH_ERROR_BASE   -2500
	Base error code (minimum value) for inotify watch errors.
#define	INOTIFY_WATCH_ERROR_LIMIT   (INOTIFY_WATCH_ERROR_BASE + 50)
	Maximum error code for inotify errors.
#define	IS_INOTIFY_WATCH_ERROR(error)   (((error) >= INOTIFY_WATCH_ERROR_BASE) && ((error) < INOTIFY_WATCH_ERROR_LIMIT))
	Return true if error code is within the range for inotify watch errors.
#define	INOTIFY_WATCH_ERROR_NULL_WATCH   (INOTIFY_WATCH_ERROR_BASE + 1)
	watch invalid, was NULL
#define	INOTIFY_WATCH_ERROR_WATCH_ID_NOT_FOUND   (INOTIFY_WATCH_ERROR_BASE + 2)
	could not look up watch id
#define	INOTIFY_WATCH_ALREADY_WATCHING   (INOTIFY_WATCH_ERROR_BASE + 3)
	already being watched
#define	INOTIFY_WATCH_NOT_WATCHED   (INOTIFY_WATCH_ERROR_BASE + 4)
	not being watched
Functions
int	inotify_watch_init (void)
	Initialize the inotify monitoring back end.
int	inotify_watch_fini (void)
	Close the inotify monitoring back end, stop all monitoring, free all resources.
bool	is_watch_target (const char *path)
	Return true if path parameter is a watch target.
bool	is_path_watched (const char *path)
	Return true if the given path is being watched by inotify.
const char *	inotify_watch_error_string (int error)
	Translate error code to string description.
char *	inotify_mask_string (unsigned int mask, const char *separator)
	Given an inotify event bitmask return a string of all the enabled flags.
char *	path_watch_string (struct path_watch_t *pw)
	Render a path_watch_t struct as a string.
struct path_watch_t *	find_watch_by_path (const char *path)
	Given a path lookup the path watch object associated with it.
struct path_watch_t *	find_watch_by_watch_id (int watch_id)
	Given an inotify watch id lookup the path watch object associated with it.
int	inotify_start_monitoring (const char *path)
	Start monitoring the target path with inotify.
int	inotify_stop_monitoring (const char *path)
	Stop monitoring the target path with inotify.
int	read_events (void)
	Loop used to read inotify events and dispatch them.
int	get_inotify_fd (void)
	Return the file descriptor used by the inotify back end.
lwatch_event_callback_t	register_lwatch_event_callback (lwatch_event_callback_t callback)
	Register a callback to receive log watch events.
Variables
bool	keep_watching
	Flag used to indicate if the read_events() loop should terminate or continue.

---

Detailed Description

Public interface for inotify backend to log watch.

Definition in file inotify_watch.h.

---

Define Documentation

#define IS_INOTIFY_WATCH_ERROR

(

error

)

(((error) >= INOTIFY_WATCH_ERROR_BASE) && ((error) < INOTIFY_WATCH_ERROR_LIMIT))

Return true if error code is within the range for inotify watch errors.

Parameters:

[in]

error

The error code to test if it's a inotify watch error code.

Returns:

True if error code is a inotify watch error.

Definition at line 38 of file inotify_watch.h.

Referenced by error_string().

---

Function Documentation

struct path_watch_t* find_watch_by_path

(

const char *

path

)

[read]

Given a path lookup the path watch object associated with it.

Parameters:

[in]

path

The path whose matching watch object is desired.

Returns:

Pointer to the path watch object or NULL if not found.

Definition at line 1407 of file inotify_watch.c.

Referenced by inotify_start_monitoring().

{
    int error;
    hash_key_t key;
    hash_value_t value;
    struct path_watch_t *pw;

    key.type = HASH_KEY_STRING;
    key.str = path;

    if ((error = hash_lookup(watch_path_table, &key, &value)) != HASH_SUCCESS) {
        log_msg(LOG_VERBOSE_DEBUG, _("cannot find pathname \"%s\"\n"),  path);
        return NULL;
    }

    pw = (struct path_watch_t *) value.ptr;
    return pw;
}

struct path_watch_t* find_watch_by_watch_id

(

int

watch_id

)

[read]

Given an inotify watch id lookup the path watch object associated with it.

Parameters:

[in]

watch_id

The watch_id assigned by inotify to identify the watch

Returns:

Pointer to the path watch object or NULL if not found.

Definition at line 1431 of file inotify_watch.c.

Referenced by process_event().

{
    int error;
    hash_key_t key;
    hash_value_t value;
    struct path_watch_t *pw;

    key.type = HASH_KEY_ULONG;
    key.ul = watch_id;

    if ((error = hash_lookup(watch_id_table, &key, &value)) != HASH_SUCCESS) {
        log_msg(LOG_DEBUG, _("cannot find watch_id %d\n"),  watch_id);
        return NULL;
    }

    pw = (struct path_watch_t *) value.ptr;
    return pw;
}

int get_inotify_fd

(

void

)

Return the file descriptor used by the inotify back end.

Returns:

Integer file descriptor used to read inotify events

The inotify file descriptor is used to read inotify events.

Definition at line 1627 of file inotify_watch.c.

Referenced by main_loop().

{
    return inotify_fd;
}

char* inotify_mask_string	(	unsigned int	mask,
		const char *	separator
	)

Given an inotify event bitmask return a string of all the enabled flags.

Parameters:

[in]	mask	Bitmask of inotify event flags
[in]	separator	String used to separate individual flags

Returns:

static string with each enabled flag separated by the separator string

Definition at line 1305 of file inotify_watch.c.

Referenced by process_event().

{
    static __thread char buf[1024]; /* thread local static buffer */
    char *p, *buf_end;
    size_t separator_len;
    unsigned int unknown;

    p = buf;                     /* current position in buffer */
    buf_end = &buf[sizeof(buf)]; /* non-inclusive end of buffer */
    separator_len = strlen(separator);
    *p = 0;

    /* validate there is nothing in the event mask we don't know about */
    unknown = mask & ~(IN_ACCESS | IN_MODIFY | IN_ATTRIB | IN_CLOSE_WRITE |
                        IN_CLOSE_NOWRITE | IN_OPEN | IN_MOVED_FROM | IN_MOVED_TO |
                        IN_CREATE | IN_DELETE | IN_DELETE_SELF | IN_MOVE_SELF |
                        IN_UNMOUNT | IN_Q_OVERFLOW | IN_IGNORED | IN_ONLYDIR |
                        IN_DONT_FOLLOW | IN_MASK_ADD | IN_ISDIR | IN_ONESHOT);

    if (unknown) p += snprintf(p, buf_end - p, "unknown bits=0x%x%s", unknown, separator);
    if (p >= buf_end) goto fail;

    if (mask & IN_ACCESS)        p += snprintf(p, buf_end - p, "ACCESS%s",        separator);
    if (p >= buf_end) goto fail;
    if (mask & IN_MODIFY)        p += snprintf(p, buf_end - p, "MODIFY%s",        separator);
    if (p >= buf_end) goto fail;
    if (mask & IN_ATTRIB)        p += snprintf(p, buf_end - p, "ATTRIB%s",        separator);
    if (p >= buf_end) goto fail;
    if (mask & IN_CLOSE_WRITE)   p += snprintf(p, buf_end - p, "CLOSE_WRITE%s",   separator);
    if (p >= buf_end) goto fail;
    if (mask & IN_CLOSE_NOWRITE) p += snprintf(p, buf_end - p, "CLOSE_NOWRITE%s", separator);
    if (p >= buf_end) goto fail;
    if (mask & IN_OPEN)          p += snprintf(p, buf_end - p, "OPEN%s",          separator);
    if (p >= buf_end) goto fail;
    if (mask & IN_MOVED_FROM)    p += snprintf(p, buf_end - p, "MOVED_FROM%s",    separator);
    if (p >= buf_end) goto fail;
    if (mask & IN_MOVED_TO)      p += snprintf(p, buf_end - p, "MOVED_TO%s",      separator);
    if (p >= buf_end) goto fail;
    if (mask & IN_CREATE)        p += snprintf(p, buf_end - p, "CREATE%s",        separator);
    if (p >= buf_end) goto fail;
    if (mask & IN_DELETE)        p += snprintf(p, buf_end - p, "DELETE%s",        separator);
    if (p >= buf_end) goto fail;
    if (mask & IN_DELETE_SELF)   p += snprintf(p, buf_end - p, "DELETE_SELF%s",   separator);
    if (p >= buf_end) goto fail;
    if (mask & IN_MOVE_SELF)     p += snprintf(p, buf_end - p, "MOVE_SELF%s",     separator);
    if (p >= buf_end) goto fail;
    if (mask & IN_UNMOUNT)       p += snprintf(p, buf_end - p, "UNMOUNT%s",       separator);
    if (p >= buf_end) goto fail;
    if (mask & IN_Q_OVERFLOW)    p += snprintf(p, buf_end - p, "Q_OVERFLOW%s",    separator);
    if (p >= buf_end) goto fail;
    if (mask & IN_IGNORED)       p += snprintf(p, buf_end - p, "IGNORED%s",       separator);
    if (p >= buf_end) goto fail;
    if (mask & IN_ONLYDIR)       p += snprintf(p, buf_end - p, "ONLYDIR%s",       separator);
    if (p >= buf_end) goto fail;
    if (mask & IN_DONT_FOLLOW)   p += snprintf(p, buf_end - p, "DONT_FOLLOW%s",   separator);
    if (p >= buf_end) goto fail;
    if (mask & IN_MASK_ADD)      p += snprintf(p, buf_end - p, "MASK_ADD%s",      separator);
    if (p >= buf_end) goto fail;
    if (mask & IN_ISDIR)         p += snprintf(p, buf_end - p, "ISDIR%s",         separator);
    if (p >= buf_end) goto fail;
    if (mask & IN_ONESHOT)       p += snprintf(p, buf_end - p, "ONESHOT%s",       separator);
    if (p >= buf_end) goto fail;

    if (p > buf) p[-separator_len] = 0;

    return buf;
 fail:
    /* exhausted the buffer; NULL terminate then return truncated string */
    buf_end[-1] = 0;   /* should already be NULL terminated, but be safe */
    return buf;
}

int inotify_start_monitoring

(

const char *

path_arg

)

Start monitoring the target path with inotify.

Parameters:

[in]

path_arg

The pathname to monitor, it will be normalized and made absolute

Returns:

SUCCESS (0) or non-zero error code otherwise

Definition at line 1455 of file inotify_watch.c.

Referenced by process_file_rename(), relocate_watches(), start_monitoring(), and validate_backups_in_database().

{
    int error;
    char path[PATH_MAX];
    hash_key_t key;
    hash_value_t value;
    char existing_directory_ancestor[PATH_MAX];
    struct path_watch_t *pw;

    /* Normalize the path passed to us */
    if ((error = make_normalized_absolute_path(path, sizeof(path), path_arg)) != SUCCESS) {
        log_msg(LOG_ERROR, _("failed make_normalized_absolute_path from \"%s\" (%s)\n"),
                path_arg, error_string(error));
        return error;
    }

    /* Assure we're not already watching this path */
    if (is_watch_target(path)) {
        error = INOTIFY_WATCH_ALREADY_WATCHING;
        log_msg(LOG_ERROR, _("path is already being watched \"%s\"\n"),  path);
        return error;
    }

    log_msg(LOG_INFO, _("watching target \"%s\"\n"),  path);

    /*
     * We watch the directory which contains the path, not the path itself. To
     * establish a watch on a directory the directory must exist in the
     * filesystem so we search for the nearest directory ancestor containing the
     * path which exists in the file system.  This is where the watch will be
     * established.
     *
     * If the directory containing the path does not yet exist we watch the
     * closest directory to the final path component and will move the watch to
     * a closer directory when the missing directory component is later created
     * in the directory which was chosen to watch.
     *
     * FIXME
     * WARNING: Race Condition. If the missing directory is created before the
     * watch is established we won't see the directory creation event which
     * tells us we can move the watch directory closer to the target. The only
     * way to protect against this is to periodically walk all the watch targets
     * and and adjust their watch directories.
     */
    if ((error = find_existing_directory_ancestor(existing_directory_ancestor,
                                                  sizeof(existing_directory_ancestor),
                                                  path) != SUCCESS)) {
        log_msg(LOG_ERROR, _("failed find_existing_directory_ancestor \"%s\" (%s)\n"),
                path, error_string(error));
        return error;
    }

    /*
     * If we're already watching the selected directory get the watch object
     * previously created for watching that directory, otherwise create a new
     * watch object for the directory.
     */
    if ((pw = find_watch_by_path(existing_directory_ancestor)) == NULL) {
        if ((error = new_path_watch(existing_directory_ancestor, &pw)) != SUCCESS) {
            log_msg(LOG_ERROR, _("could not allocate new watch for \"%s\" (%s)\n"),
                    existing_directory_ancestor, error_string(error));
            return error;
        }
    }

    /* Do some basic bookkeeping */

    /* Add the path to our list of targets. */
    if ((error = add_path_to_target_list(path)) != SUCCESS) {
        log_msg(LOG_ERROR, _("could not insert path into target table \"%s\" (%s)\n"),
                pw->path, error_string(error));
        inotify_rm_watch(inotify_fd, pw->watch_id);
        free_path_watch(&pw);
        return error;
    }

    /* Add the watch object to our list of directories we're watching. */
    if ((error = track_path_watch(pw)) != SUCCESS) {
        log_msg(LOG_ERROR, _("could not insert watch into tables for \"%s\" (%s)\n"),
                pw->path, error_string(error));
        inotify_rm_watch(inotify_fd, pw->watch_id);
        free_path_watch(&pw);
        return error;
    }

    log_msg(LOG_DEBUG, _("adding path \"%s\" to descendant_path_table for directory \"%s\"\n"),
            path, pw->path);

    /* Add the path to the list of targets the watch object is responsible for watching (e.g. descendants). */
    key.type = HASH_KEY_STRING;
    key.str = path;
    value.type = HASH_VALUE_UNDEF;

    if ((error = hash_enter(pw->descendant_path_table, &key, &value)) != HASH_SUCCESS) {
        log_msg(LOG_ERROR, _("cannot add path \"%s\" to path_watch_t descendant_path_table \"%s\" (%s)\n"),
                path, pw->path, error_string(error));
        return error;
    }

    return SUCCESS;
}

int inotify_stop_monitoring

(

const char *

path_arg

)

Stop monitoring the target path with inotify.

Parameters:

[in]

path_arg

The pathname cease monitoring, it will be normalized and made absolute

Returns:

SUCCESS (0) or non-zero error code otherwise

Definition at line 1562 of file inotify_watch.c.

{
    int error;
    char path[PATH_MAX];
    unsigned long i, count;
    hash_key_t key;
    hash_entry_t *entries, *entry;
    struct path_watch_t *pw;
    int path_count;

    if ((error = make_normalized_absolute_path(path, sizeof(path), path_arg)) != SUCCESS) {
        log_msg(LOG_ERROR, _("failed make_normalized_absolute_path from \"%s\" (%s)\n"),
                path_arg, error_string(error));
        return error;
    }

    if (!is_watch_target(path)) {
        error = INOTIFY_WATCH_NOT_WATCHED;
        log_msg(LOG_ERROR, _("path was not being watched \"%s\"\n"),  path);
        return error;
    }

    log_msg(LOG_INFO, _("removing watch target \"%s\"\n"),  path);

    key.type = HASH_KEY_STRING;
    key.str = path;

    path_count = 0;
    hash_entries(watch_id_table, &count, &entries);
    for (i = 0, entry = entries; i < count; i++, entry++) {
        pw = entry->value.ptr;

        if (hash_has_key(pw->descendant_path_table, &key)) {
            path_count++;
            if ((error = hash_delete(pw->descendant_path_table, &key)) != HASH_SUCCESS) {
                log_msg(LOG_ERROR, _("cannot delete path \"%s\" from path_watch_t descendant_path_table \"%s\" (%s)\n"),
                        path, pw->path, error_string(error));
            }
            if ((error = destroy_path_watch_if_empty(&pw)) != SUCCESS) {
                log_msg(LOG_ERROR, _("destroy_path_watch_if_empty failed (%s)\n"), error_string(error));
            }
        }
    }
    free(entries);

    if (path_count != 1) {
        log_msg(LOG_ERROR, _("found %d instances of \"%s\" but expected exactly one\n"),
                path_count, path);
    }

    if ((error = remove_path_from_target_list(path)) != SUCCESS) {
        log_msg(LOG_ERROR, _("could not remove path from target table \"%s\" (%s)\n"),
                path, error_string(error));
    }

    return error;
}

const char* inotify_watch_error_string

(

int

error

)

Translate error code to string description.

Parameters:

[in]

error

Error code whose string description is sought.

Returns:

string describing the error

Note: IS_INOTIFY_WATCH_ERROR(error) should true otherwise the error code is outside the set of values this function knows about. If the error code is not recognized the string "unknown(XXX)" will be returned instead where XXX is the decimal representation of the error code.

Definition at line 1287 of file inotify_watch.c.

Referenced by error_string().

{
    switch(error) {
    case SUCCESS:                                return _("success");
    case INOTIFY_WATCH_ERROR_NULL_WATCH:         return _("watch invalid, was NULL");
    case INOTIFY_WATCH_ERROR_WATCH_ID_NOT_FOUND: return _("could not look up watch id");
    case INOTIFY_WATCH_ALREADY_WATCHING:         return _("already being watched");
    case INOTIFY_WATCH_NOT_WATCHED:              return _("not being watched");
    }
    return NULL;
}

int inotify_watch_fini

(

void

)

Close the inotify monitoring back end, stop all monitoring, free all resources.

Returns:

SUCCESS (0) or non-zero error code otherwise

Definition at line 1197 of file inotify_watch.c.

Referenced by lwatch_fini().

{
    unsigned long i, count;
    hash_entry_t *entries, *entry;
    struct path_watch_t *pw;

    flush_inotify_cookie_cache();

    hash_entries(watch_id_table, &count, &entries);
    for (i = 0, entry = entries; i < count; i++, entry++) {
        pw = entry->value.ptr;
        log_msg(LOG_VERBOSE_DEBUG, _("destroying [%d] \"%s\"\n"),  pw->watch_id, pw->path);
        destroy_path_watch(&pw);
    }
    free(entries);

    if (hash_count(watch_path_table) != 0) {
        log_msg(LOG_ERROR, _("watch_path_table not empty (%d) after removing all watches\n"),
                hash_count(watch_path_table));
    }

    if (hash_count(watch_id_table) != 0) {
        log_msg(LOG_ERROR, _("watch_id_table not empty (%d) after removing all watches\n"),
                hash_count(watch_id_table));
    }

    hash_destroy(watch_path_table);
    hash_destroy(watch_id_table);
    hash_destroy(target_table);
    close(inotify_fd);

    return SUCCESS;
}

int inotify_watch_init

(

void

)

Initialize the inotify monitoring back end.

Returns:

SUCCESS (0) or non-zero error code otherwise

Definition at line 1162 of file inotify_watch.c.

Referenced by lwatch_init().

{
    int error;

    inotify_lost_cookie_callback = lost_rename_callback;

    if ((inotify_fd = inotify_init()) < 0) {
        error = errno;
        log_msg(LOG_ERROR, _("inotify_init() failed (%s)\n"), error_string(error));
        return error;
    }


    if ((error = hash_create(INITIAL_HASH_TABLE_SIZE, &watch_path_table, NULL)) != HASH_SUCCESS) {
        log_msg(LOG_ERROR, _("inotify_watch_init: cannot create pathname hash table\n"));
        return error;
    }

    if ((error = hash_create(INITIAL_HASH_TABLE_SIZE, &watch_id_table, NULL)) != HASH_SUCCESS) {
        log_msg(LOG_ERROR, _("inotify_watch_init: cannot create watch id hash table\n"));
        return error;
    }

    if ((error = hash_create(INITIAL_HASH_TABLE_SIZE, &target_table, NULL)) != HASH_SUCCESS) {
        log_msg(LOG_ERROR, _("%s: cannot create target hash table\n"));
        return error;
    }

    return SUCCESS;
}

bool is_path_watched

(

const char *

path

)

Return true if the given path is being watched by inotify.

Parameters:

[in]

path

The path to check for inotify watching

Returns:

true if the path is watched by inotify, false otherwise

Note, this is distinct from asking if a path is target, a target is something we've been asked to monitor. In the process of monitoring we will ask inotify to watch certain directories which are not targets, but may contain targets.

See also:

is_watch_target() Also see Vocabulary Terms for an explanation of targets vs. watched objects.

Definition at line 1267 of file inotify_watch.c.

{
    hash_key_t key;

    key.type = HASH_KEY_STRING;
    key.str = path;

    return hash_has_key(watch_path_table, &key);
}

bool is_watch_target

(

const char *

path

)

Return true if path parameter is a watch target.

Parameters:

[in]

path

The path we're testing to see if it's a watch target

Returns:

True if path parameter is a watch target

Note, This answers the question if the path is a target to monitor. In other words it's something we've specifically been asked to monitor. Our implementation will establish inotify watches as a consequence of monitoring a target and is_path_watched() is correct way to ask if inotify is watching a path as opposed to this function which reports if path is target to monitor.

See also:

is_path_watched() Also see Vocabulary Terms for an explanation of targets vs. watched objects.

Definition at line 1245 of file inotify_watch.c.

Referenced by inotify_start_monitoring(), inotify_stop_monitoring(), process_event(), and start_monitoring().

{
    hash_key_t key;

    key.type = HASH_KEY_STRING;
    key.str = path;

    return hash_has_key(target_table, &key);
}

char* path_watch_string

(

struct path_watch_t *

pw

)

Render a path_watch_t struct as a string.

Parameters:

[in]

pw

The path watch object to render as a string

Returns:

malloc'ed string, caller must free

Definition at line 1382 of file inotify_watch.c.

Referenced by process_event(), and watch_path_table_string().

{
    char *files;
    char *fw_string;
    int len;

    if (!pw) return strdup("(null)");

    files = keys_string(pw->descendant_path_table, "        ", "\n");

    len = asprintf(&fw_string, "[%d] \"%s\" n_files=%ld%s%s",
                   pw->watch_id, pw->path,
                   hash_count(pw->descendant_path_table),
                   hash_count(pw->descendant_path_table) ? "\n" : "", files);

    free(files);
    return fw_string;
}

int read_events

(

void

)

Loop used to read inotify events and dispatch them.

Returns:

SUCCESS (0) or non-zero error code otherwise

Definition at line 1636 of file inotify_watch.c.

Referenced by main_loop().

{
    char buf[1024 * (INOTIFY_EVENT_SIZE + 16)]; /* reasonable guess as to size of 1024 events */
    int len, error, i;
    bool done;

    /*
     * The behavior when the buffer given to read(2) is too small to return information
     * about the next event depends on the kernel version: in kernels before 2.6.21,
     * read(2) returns 0; since kernel 2.6.21, read(2) fails with the error EINVAL.
     */

    done = false;
    while (!done) {
        len = read (inotify_fd, buf, sizeof(buf));
        i = 0;
        if (len <= 0) {
            error = errno;
            if (error == EINTR || error == EAGAIN) { /* need to reissue system call */
                continue;
            }
            else if (error == EINVAL || len == 0) {
                log_msg(LOG_ERROR, _("failed, buffer too small (%s)\n"),
                        error_string(error));
                return error;
            } else {
                log_msg(LOG_ERROR, _("failed (%s)\n"),
                        error_string(error));
                return error;
            }
        }
        while (i < len) {
            struct inotify_event *event;

            event = (struct inotify_event *) &buf[i];

            process_event(event);
            i += INOTIFY_EVENT_SIZE + event->len;
        }
        done = true;
    }
    return SUCCESS;
}

lwatch_event_callback_t register_lwatch_event_callback

(

lwatch_event_callback_t

callback

)

Register a callback to receive log watch events.

Parameters:

[in]

callback

The callback which will be invoked to send a log watch event.

Returns:

The previous callback pointer.

Definition at line 1685 of file inotify_watch.c.

Referenced by lwatch_init().

{
    lwatch_event_callback_t prev_callback = lwatch_event_callback;
    lwatch_event_callback = callback;
    return prev_callback;
}