lwatch.h File Reference

Public interface for watching log files. More...

#include <sys/param.h>
#include "watch_database.h"

Go to the source code of this file.

Classes
struct	lwatch_event_t
	Watch event. More...
Defines
#define	LWATCH_ERROR_BASE   -4000
	Base error code (minimum value) for log watch errors.
#define	LWATCH_ERROR_LIMIT   (LWATCH_ERROR_BASE + 50)
	Maximum error code for log watch errors.
#define	IS_LWATCH_ERROR(error)   (((error) >= LWATCH_ERROR_BASE) && ((error) < LWATCH_ERROR_LIMIT))
	Return true if error code is within the range for log watch errors.
#define	LWATCH_ERROR_CANNOT_MONITOR   (LWATCH_ERROR_BASE + 1)
	cannot monitor target
#define	LWATCH_ERROR_CANNOT_FIND_PATH_INFO   (LWATCH_ERROR_BASE + 2)
	cannot find path info
#define	LWATCH_ERROR_LOST_RENAME   (LWATCH_ERROR_BASE + 3)
	one of the paths for a rename event is unknown
#define	LWATCH_ERROR_STAT_NOT_VALID   (LWATCH_ERROR_BASE + 4)
	stat information is not valid
Typedefs
typedef int(*	lwatch_event_callback_t )(struct lwatch_event_t *event)
	This callback is used when a watch event occurs.
Enumerations
enum	lwatch_event_type {   LWATCH_EVENT_CREATE, LWATCH_EVENT_DELETE, LWATCH_EVENT_RENAME, LWATCH_EVENT_MODIFY,   LWATCH_EVENT_OPEN, LWATCH_EVENT_CLOSE }
	The set of log watch event types. More...
Functions
int	destroy_path_info (struct lwatch_path_info_t **ppath_info)
	Release lwatch_path_info_t resources, free it's memory, set variable to NULL.
int	update_stat_info (struct stat *cur_stat_info, struct lwatch_path_info_t *path_info)
	Merge stat information into path into our saved information about the file.
bool	is_log_backup (const char *path)
	Given a path name return true if it appears to be a rotated backup of a primary log file.

---

Detailed Description

Public interface for watching log files.

Definition in file lwatch.h.

---

Define Documentation

#define IS_LWATCH_ERROR

(

error

)

(((error) >= LWATCH_ERROR_BASE) && ((error) < LWATCH_ERROR_LIMIT))

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

Parameters:

[in]

error

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

Returns:

True if error code is a log watch error.

Definition at line 39 of file lwatch.h.

Referenced by error_string().

---

Typedef Documentation

typedef int(* lwatch_event_callback_t)(struct lwatch_event_t *event)

This callback is used when a watch event occurs.

Parties interested in receiving watch events register a callback of this type. When a watch event occurs their callback is invoked passing the watch event to it.

Definition at line 87 of file lwatch.h.

---

Enumeration Type Documentation

enum lwatch_event_type

The set of log watch event types.

Enumerator:

LWATCH_EVENT_CREATE	a file or directory was created
LWATCH_EVENT_DELETE	a file or directory was deleted
LWATCH_EVENT_RENAME	a file or directory was renamed
LWATCH_EVENT_MODIFY	a file or directory was modified
LWATCH_EVENT_OPEN	a file or directory was opened
LWATCH_EVENT_CLOSE	a file or directory was closed

Definition at line 53 of file lwatch.h.

             {
    LWATCH_EVENT_CREATE,        /**< a file or directory was created */
    LWATCH_EVENT_DELETE,        /**< a file or directory was deleted */
    LWATCH_EVENT_RENAME,        /**< a file or directory was renamed */
    LWATCH_EVENT_MODIFY,        /**< a file or directory was modified */
    LWATCH_EVENT_OPEN,          /**< a file or directory was opened */
    LWATCH_EVENT_CLOSE          /**< a file or directory was closed */
} lwatch_event_type;

---

Function Documentation

int destroy_path_info

(

struct lwatch_path_info_t **

ppath_info

)

Release lwatch_path_info_t resources, free it's memory, set variable to NULL.

Parameters:

[out]

ppath_info

Pointer to a pointer of saved information about a file. Upon a successful return this pointer will be set to NULL.

Returns:

SUCCESS (0) or non-zero error code otherwise

Definition at line 1151 of file lwatch.c.

{
    struct lwatch_path_info_t *path_info;

    if (!ppath_info) return EINVAL;
    path_info = *ppath_info;
    if (!path_info) return EINVAL;

    free(path_info);
    *ppath_info = NULL;

    return SUCCESS;
}

bool is_log_backup

(

const char *

path

)

Given a path name return true if it appears to be a rotated backup of a primary log file.

Parameters:

[in]

path

The path name to test.

Returns:

SUCCESS (0) or non-zero error code otherwise

By convention backing up log files is done via a process called rotation where the current version of a (primary) log file is renamed to a backup name and the primary log file is reopened. Usually the last N copies of the backup are kept, backup.1 is moved to backup.2, backup.2 is moved to backup.3, and backup.N+1 is discarded (hence the notion of rotation). Also by convention the name of backup files is the name of the primary file with a rotation number appended, or the date of the rotation appended.

This routine uses regular expressions to intuit from a pathname if the pathname appears to follow a rotation backup naming convention. Only the pathname is considered, the file contents are not examined.

Currently there are two rotation backup naming conventions which are looked for, both are supported by the logrotate facility found on many machines.

• numbered backups
• dated backups

See also:

logrotate_numbered_backup_regexp

logrotate_date_backup_regexp

Definition at line 1229 of file lwatch.c.

Referenced by find_log_files_callback(), and start_monitoring().

{
    int num_matches;

    if ((num_matches = regexp_search(&logrotate_numbered_backup_regexp, path)) > 0) {
# if 0
        // FIXME: currently we don't use the sub-fields, this code is left as an
        // example of how to do that

        char directory[PATH_MAX];
        char filename[PATH_MAX];
        char number[9];
        char extension[PATH_MAX];

        regexp_substring(&logrotate_numbered_backup_regexp, 1, directory, sizeof(directory));
        regexp_substring(&logrotate_numbered_backup_regexp, 2, filename, sizeof(filename));
        regexp_substring(&logrotate_numbered_backup_regexp, 3, number, sizeof(number));
        regexp_substring(&logrotate_numbered_backup_regexp, 4, extension, sizeof(extension));

        if (0) printf(" num_matches=%d directory=\"%s\" filename=\"%s\" number=\"%s\" extension=\"%s\" ",
                      num_matches, directory, filename, number, extension);
#endif
        return true;
    }
    if ((num_matches = regexp_search(&logrotate_date_backup_regexp, path)) > 0) {
# if 0
        // FIXME: currently we don't use the sub-fields, this code is left as an
        // example of how to do that

        char directory[PATH_MAX];
        char filename[PATH_MAX];
        char date[9];
        char year[5];
        char month[3];
        char day[3];
        char extension[PATH_MAX];

        regexp_substring(&logrotate_date_backup_regexp, 1, directory, sizeof(directory));
        regexp_substring(&logrotate_date_backup_regexp, 2, filename, sizeof(filename));
        regexp_substring(&logrotate_date_backup_regexp, 3, date, sizeof(date));
        regexp_substring(&logrotate_date_backup_regexp, 4, year, sizeof(year));
        regexp_substring(&logrotate_date_backup_regexp, 5, month, sizeof(month));
        regexp_substring(&logrotate_date_backup_regexp, 6, day, sizeof(day));
        regexp_substring(&logrotate_date_backup_regexp, 7, extension, sizeof(extension));

        if (0) printf(" num_matches=%d directory=\"%s\" filename=\"%s\" date=\"%s\" year=\"%s\" month=\"%s\" day=\"%s\" extension=\"%s\" ",
                      num_matches, directory, filename, date, year, month, day, extension);
#endif
        return true;
    }
    return false;
}

int update_stat_info	(	struct stat *	cur_stat_info,
		struct lwatch_path_info_t *	path_info
	)

Merge stat information into path into our saved information about the file.

Parameters:

[in]	cur_stat_info	Pointer to stat data to update from, or if NULL call stat() to obtain info
[in]	path_info	Our saved information about the file

Returns:

SUCCESS (0) or non-zero error code otherwise

Definition at line 1173 of file lwatch.c.

Referenced by update_stat_info_and_write().

{
    int error;
    struct stat stat_info;

    if (cur_stat_info == NULL) {
        if (stat(path_info->path, &stat_info) < 0) {
            error = errno;
            log_msg(LOG_ERROR, _("cannot perform stat on \"%s\" (%s) \n"),
                    path_info->path, error_string(error));
            return error;
        }
        cur_stat_info = &stat_info;
    }

    path_info->dev               = cur_stat_info->st_dev;
    path_info->inode             = cur_stat_info->st_ino;
    path_info->mode              = cur_stat_info->st_mode;
    path_info->uid               = cur_stat_info->st_uid;
    path_info->gid               = cur_stat_info->st_gid;
    path_info->size              = cur_stat_info->st_size;
    path_info->access_time       = cur_stat_info->st_atime;
    path_info->modification_time = cur_stat_info->st_mtime;
    path_info->change_time       = cur_stat_info->st_ctime;

    path_info->flags |= STAT_DATA_VALID_FLAG;

    return SUCCESS;
}