monitor.c File Reference

Monitor files for changes. More...

#include "config.h"
#include <errno.h>
#include <limits.h>
#include <poll.h>
#include <stdbool.h>
#include <stdint.h>
#include <string.h>
#include <sys/inotify.h>
#include <sys/stat.h>
#include <sys/types.h>
#include <unistd.h>
#include "mutt/lib.h"
#include "core/lib.h"
#include "monitor.h"
#include "index/lib.h"
#include <fcntl.h>

Include dependency graph for monitor.c:

Go to the source code of this file.

Data Structures
struct	Monitor
	A watch on a file. More...
struct	MonitorInfo
	Information about a monitored file. More...

Macros
#define	INOTIFY_MASK_DIR   (IN_MOVED_TO | IN_ATTRIB | IN_CLOSE_WRITE | IN_ISDIR)
#define	INOTIFY_MASK_FILE   IN_CLOSE_WRITE
#define	EVENT_BUFLEN   MAX(4096, sizeof(struct inotify_event) + NAME_MAX + 1)

Enumerations
enum	ResolveResult {   RESOLVE_RES_FAIL_NOMAILBOX = -3 , RESOLVE_RES_FAIL_NOTYPE = -2 , RESOLVE_RES_FAIL_STAT = -1 , RESOLVE_RES_OK_NOTEXISTING = 0 ,   RESOLVE_RES_OK_EXISTING = 1 }
	Results for the Monitor functions. More...

Functions
static void	mutt_poll_fd_add (int fd, short events)
	Add a file to the watch list.
static int	mutt_poll_fd_remove (int fd)
	Remove a file from the watch list.
static int	monitor_init (void)
	Set up file monitoring.
static void	monitor_check_cleanup (void)
	Close down file monitoring.
static struct Monitor *	monitor_new (struct MonitorInfo *info, int descriptor)
	Create a new file monitor.
static void	monitor_info_free (struct MonitorInfo *info)
	Shutdown a file monitor.
static void	monitor_delete (struct Monitor *monitor)
	Free a file monitor.
static int	monitor_handle_ignore (int desc)
	Listen for when a backup file is closed.
static enum ResolveResult	monitor_resolve (struct MonitorInfo *info, struct Mailbox *m)
	Get the monitor for a mailbox.
int	mutt_monitor_poll (void)
	Check for filesystem changes.
int	mutt_monitor_add (struct Mailbox *m)
	Add a watch for a mailbox.
int	mutt_monitor_remove (struct Mailbox *m)
	Remove a watch for a mailbox.

Variables
bool	MonitorFilesChanged = false
	Set to true when a monitored file has changed.
bool	MonitorCurMboxChanged = false
	Set to true when the current mailbox has changed.
static int	INotifyFd = -1
	Inotify file descriptor.
static struct Monitor *	Monitor = NULL
	Linked list of monitored Mailboxes.
static size_t	PollFdsCount = 0
	Number of used entries in the PollFds array.
static size_t	PollFdsLen = 0
	Size of PollFds array.
static struct pollfd *	PollFds = NULL
	Array of monitored file descriptors.
static int	MonitorCurMboxDescriptor = -1
	Monitor file descriptor of the current mailbox.

Detailed Description

Monitor files for changes.

Authors

• Gero Treuner
• Richard Russon
• Ian Zimmerman
• Pietro Cerutti
• R Primus

Copyright

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Definition in file monitor.c.

Macro Definition Documentation

INOTIFY_MASK_DIR

#define INOTIFY_MASK_DIR   (IN_MOVED_TO | IN_ATTRIB | IN_CLOSE_WRITE | IN_ISDIR)

Definition at line 70 of file monitor.c.

INOTIFY_MASK_FILE

#define INOTIFY_MASK_FILE   IN_CLOSE_WRITE

Definition at line 71 of file monitor.c.

EVENT_BUFLEN

#define EVENT_BUFLEN   MAX(4096, sizeof(struct inotify_event) + NAME_MAX + 1)

Definition at line 73 of file monitor.c.

Enumeration Type Documentation

ResolveResult

enum ResolveResult

Results for the Monitor functions.

Enumerator
RESOLVE_RES_FAIL_NOMAILBOX	No Mailbox to work on.
RESOLVE_RES_FAIL_NOTYPE	Can't identify Mailbox type.
RESOLVE_RES_FAIL_STAT	Can't stat() the Mailbox file.
RESOLVE_RES_OK_NOTEXISTING	File exists, no monitor is attached.
RESOLVE_RES_OK_EXISTING	File exists, monitor is already attached.

Definition at line 78 of file monitor.c.

{
  RESOLVE_RES_FAIL_NOMAILBOX = -3, 
  RESOLVE_RES_FAIL_NOTYPE = -2,    
  RESOLVE_RES_FAIL_STAT = -1,      
  RESOLVE_RES_OK_NOTEXISTING = 0,  
  RESOLVE_RES_OK_EXISTING = 1,     
};

Function Documentation

mutt_poll_fd_add()

void mutt_poll_fd_add ( int fd, short events )

static

Add a file to the watch list.

Parameters

fd	File to watch
events	Events to listen for, e.g. POLLIN

Definition at line 119 of file monitor.c.

{
  int i = 0;
  for (; (i < PollFdsCount) && (PollFds[i].fd != fd); i++)
    ; // do nothing
 
  if (i == PollFdsCount)
  {
    if (PollFdsCount == PollFdsLen)
    {
      PollFdsLen += 2;
      MUTT_MEM_REALLOC(&PollFds, PollFdsLen, struct pollfd);
    }
    PollFdsCount++;
    PollFds[i].fd = fd;
    PollFds[i].events = events;
  }
  else
  {
    PollFds[i].events |= events;
  }
}

Here is the caller graph for this function:

mutt_poll_fd_remove()

int mutt_poll_fd_remove ( int fd )

static

Remove a file from the watch list.

Parameters

fd	File to remove

Return values

0	Success
-1	Error

Definition at line 148 of file monitor.c.

{
  int i = 0;
  for (; (i < PollFdsCount) && (PollFds[i].fd != fd); i++)
    ; // do nothing
 
  if (i == PollFdsCount)
    return -1;
  int d = PollFdsCount - i - 1;
  if (d != 0)
    memmove(&PollFds[i], &PollFds[i + 1], d * sizeof(struct pollfd));
  PollFdsCount--;
  return 0;
}

Here is the caller graph for this function:

monitor_init()

int monitor_init ( void )

static

Set up file monitoring.

Return values

0	Success
-1	Error

Definition at line 168 of file monitor.c.

{
  if (INotifyFd != -1)
    return 0;
 
#ifdef HAVE_INOTIFY_INIT1
  INotifyFd = inotify_init1(IN_NONBLOCK | IN_CLOEXEC);
  if (INotifyFd == -1)
  {
    mutt_debug(LL_DEBUG2, "inotify_init1 failed, errno=%d %s\n", errno, strerror(errno));
    return -1;
  }
#else
  INotifyFd = inotify_init();
  if (INotifyFd == -1)
  {
    mutt_debug(LL_DEBUG2, "monitor: inotify_init failed, errno=%d %s\n", errno,
               strerror(errno));
    return -1;
  }
  fcntl(INotifyFd, F_SETFL, O_NONBLOCK);
  fcntl(INotifyFd, F_SETFD, FD_CLOEXEC);
#endif
  mutt_poll_fd_add(0, POLLIN);
  mutt_poll_fd_add(INotifyFd, POLLIN);
 
  return 0;
}

Here is the call graph for this function:

Here is the caller graph for this function:

monitor_check_cleanup()

void monitor_check_cleanup ( void )

static

Close down file monitoring.

Definition at line 200 of file monitor.c.

{
  if (!Monitor && (INotifyFd != -1))
  {
    mutt_poll_fd_remove(INotifyFd);
    close(INotifyFd);
    INotifyFd = -1;
    MonitorFilesChanged = false;
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

monitor_new()

struct Monitor * monitor_new ( struct MonitorInfo * info, int descriptor )

static

Create a new file monitor.

Parameters

info	Details of file to monitor
descriptor	Watch descriptor

Return values

ptr	Newly allocated Monitor

Definition at line 217 of file monitor.c.

{
  struct Monitor *monitor = MUTT_MEM_CALLOC(1, struct Monitor);
  monitor->type = info->type;
  monitor->st_dev = info->st_dev;
  monitor->st_ino = info->st_ino;
  monitor->desc = descriptor;
  monitor->next = Monitor;
  if (info->type == MUTT_MH)
    monitor->mh_backup_path = mutt_str_dup(info->path);
 
  Monitor = monitor;
 
  return monitor;
}

Here is the call graph for this function:

Here is the caller graph for this function:

monitor_info_free()

void monitor_info_free ( struct MonitorInfo * info )

static

Shutdown a file monitor.

Parameters

info	Monitor to shut down

Definition at line 237 of file monitor.c.

{
  buf_dealloc(&info->path_buf);
}

Here is the call graph for this function:

Here is the caller graph for this function:

monitor_delete()

void monitor_delete ( struct Monitor * monitor )

static

Free a file monitor.

Parameters

monitor

Monitor to free

Definition at line 246 of file monitor.c.

{
  if (!monitor)
    return;
 
  struct Monitor **ptr = &Monitor;
 
  while (true)
  {
    if (!*ptr)
      return;
    if (*ptr == monitor)
      break;
    ptr = &(*ptr)->next;
  }
 
  FREE(&monitor->mh_backup_path);
  monitor = monitor->next;
  FREE(ptr);
  *ptr = monitor;
}

Here is the caller graph for this function:

monitor_handle_ignore()

int monitor_handle_ignore ( int desc )

static

Listen for when a backup file is closed.

Parameters

desc	Watch descriptor

Return values

>=0	New descriptor
-1	Error

Definition at line 274 of file monitor.c.

{
  int new_desc = -1;
  struct Monitor *iter = Monitor;
  struct stat st = { 0 };
 
  while (iter && (iter->desc != desc))
    iter = iter->next;
 
  if (iter)
  {
    if ((iter->type == MUTT_MH) && (stat(iter->mh_backup_path, &st) == 0))
    {
      new_desc = inotify_add_watch(INotifyFd, iter->mh_backup_path, INOTIFY_MASK_FILE);
      if (new_desc == -1)
      {
        mutt_debug(LL_DEBUG2, "inotify_add_watch failed for '%s', errno=%d %s\n",
                   iter->mh_backup_path, errno, strerror(errno));
      }
      else
      {
        mutt_debug(LL_DEBUG3, "inotify_add_watch descriptor=%d for '%s'\n",
                   desc, iter->mh_backup_path);
        iter->st_dev = st.st_dev;
        iter->st_ino = st.st_ino;
        iter->desc = new_desc;
      }
    }
    else
    {
      mutt_debug(LL_DEBUG3, "cleanup watch (implicitly removed) - descriptor=%d\n", desc);
    }
 
    if (MonitorCurMboxDescriptor == desc)
      MonitorCurMboxDescriptor = new_desc;
 
    if (new_desc == -1)
    {
      monitor_delete(iter);
      monitor_check_cleanup();
    }
  }
 
  return new_desc;
}

Here is the call graph for this function:

Here is the caller graph for this function:

monitor_resolve()

enum ResolveResult monitor_resolve ( struct MonitorInfo * info, struct Mailbox * m )

static

Get the monitor for a mailbox.

Parameters

[out]	info	Details of the mailbox's monitor
[in]	m	Mailbox

Return values

>=0	mailbox is valid and locally accessible: 0: no monitor / 1: preexisting monitor
-3	no mailbox (MonitorInfo: no fields set)
-2	type not set
-1	stat() failed (see errno; MonitorInfo fields: type, is_dir, path)

If m is NULL, try to get the current mailbox from the Index.

Definition at line 332 of file monitor.c.

{
  char *fmt = NULL;
  struct stat st = { 0 };
 
  struct Mailbox *m_cur = get_current_mailbox();
  if (m)
  {
    info->type = m->type;
    info->path = m->realpath;
  }
  else if (m_cur)
  {
    info->type = m_cur->type;
    info->path = m_cur->realpath;
  }
  else
  {
    return RESOLVE_RES_FAIL_NOMAILBOX;
  }
 
  if (info->type == MUTT_UNKNOWN)
  {
    return RESOLVE_RES_FAIL_NOTYPE;
  }
  else if (info->type == MUTT_MAILDIR)
  {
    info->is_dir = true;
    fmt = "%s/new";
  }
  else
  {
    info->is_dir = false;
    if (info->type == MUTT_MH)
      fmt = "%s/.mh_sequences";
  }
  if (fmt)
  {
    buf_printf(&info->path_buf, fmt, info->path);
    info->path = buf_string(&info->path_buf);
  }
  if (stat(info->path, &st) != 0)
    return RESOLVE_RES_FAIL_STAT;
 
  struct Monitor *iter = Monitor;
  while (iter && ((iter->st_ino != st.st_ino) || (iter->st_dev != st.st_dev)))
    iter = iter->next;
 
  info->st_dev = st.st_dev;
  info->st_ino = st.st_ino;
  info->monitor = iter;
 
  return iter ? RESOLVE_RES_OK_EXISTING : RESOLVE_RES_OK_NOTEXISTING;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_monitor_poll()

int mutt_monitor_poll

(

void

)

Check for filesystem changes.

Return values

-3	unknown/unexpected events: poll timeout / fds not handled by us
-2	monitor detected changes, no STDIN input
-1	error (see errno)
0	(1) input ready from STDIN, or (2) monitoring inactive -> no poll()

Wait for I/O ready file descriptors or signals.

MonitorFilesChanged also reflects changes to monitored files.

Only STDIN and INotify file handles currently expected/supported. More would ask for common infrastructure (sockets?).

Definition at line 401 of file monitor.c.

{
  int rc = 0;
  char buf[EVENT_BUFLEN]
      __attribute__((aligned(__alignof__(struct inotify_event)))) = { 0 };
 
  MonitorFilesChanged = false;
 
  if (INotifyFd != -1)
  {
    int fds = poll(PollFds, PollFdsCount, 1000); // 1 Second
 
    if (fds == -1)
    {
      rc = -1;
      if (errno != EINTR)
      {
        mutt_debug(LL_DEBUG2, "poll() failed, errno=%d %s\n", errno, strerror(errno));
      }
    }
    else
    {
      bool input_ready = false;
      for (int i = 0; fds && (i < PollFdsCount); i++)
      {
        if (PollFds[i].revents)
        {
          fds--;
          if (PollFds[i].fd == 0)
          {
            input_ready = true;
          }
          else if (PollFds[i].fd == INotifyFd)
          {
            MonitorFilesChanged = true;
            mutt_debug(LL_DEBUG3, "file change(s) detected\n");
            char *ptr = buf;
            const struct inotify_event *event = NULL;
 
            while (true)
            {
              int len = read(INotifyFd, buf, sizeof(buf));
              if (len == -1)
              {
                if (errno != EAGAIN)
                {
                  mutt_debug(LL_DEBUG2, "read inotify events failed, errno=%d %s\n",
                             errno, strerror(errno));
                }
                break;
              }
 
              while (ptr < (buf + len))
              {
                event = (const struct inotify_event *) ptr;
                mutt_debug(LL_DEBUG3, "+ detail: descriptor=%d mask=0x%x\n",
                           event->wd, event->mask);
                if (event->mask & IN_IGNORED)
                  monitor_handle_ignore(event->wd);
                else if (event->wd == MonitorCurMboxDescriptor)
                  MonitorCurMboxChanged = true;
                ptr += sizeof(struct inotify_event) + event->len;
              }
            }
          }
        }
      }
      if (!input_ready)
        rc = MonitorFilesChanged ? -2 : -3;
    }
  }
 
  return rc;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_monitor_add()

int mutt_monitor_add

(

struct Mailbox *

m

)

Add a watch for a mailbox.

Parameters

m	Mailbox to watch

Return values

0	success: new or already existing monitor
-1	failed: no mailbox, inaccessible file, create monitor/watcher failed

If m is NULL, try to get the current mailbox from the Index.

Definition at line 484 of file monitor.c.

{
  struct MonitorInfo info = { 0 };
 
  int rc = 0;
  enum ResolveResult desc = monitor_resolve(&info, m);
  if (desc != RESOLVE_RES_OK_NOTEXISTING)
  {
    if (!m && (desc == RESOLVE_RES_OK_EXISTING))
      MonitorCurMboxDescriptor = info.monitor->desc;
    rc = (desc == RESOLVE_RES_OK_EXISTING) ? 0 : -1;
    goto cleanup;
  }
 
  uint32_t mask = info.is_dir ? INOTIFY_MASK_DIR : INOTIFY_MASK_FILE;
  if (((INotifyFd == -1) && (monitor_init() == -1)) ||
      ((desc = inotify_add_watch(INotifyFd, info.path, mask)) == -1))
  {
    mutt_debug(LL_DEBUG2, "inotify_add_watch failed for '%s', errno=%d %s\n",
               info.path, errno, strerror(errno));
    rc = -1;
    goto cleanup;
  }
 
  mutt_debug(LL_DEBUG3, "inotify_add_watch descriptor=%d for '%s'\n", desc, info.path);
  if (!m)
    MonitorCurMboxDescriptor = desc;
 
  monitor_new(&info, desc);
 
cleanup:
  monitor_info_free(&info);
  return rc;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_monitor_remove()

int mutt_monitor_remove

(

struct Mailbox *

m

)

Remove a watch for a mailbox.

Parameters

m

Mailbox

Return values

0	monitor removed (not shared)
1	monitor not removed (shared)
2	no monitor

If m is NULL, try to get the current mailbox from the Index.

Definition at line 528 of file monitor.c.

{
  struct MonitorInfo info = { 0 };
  struct MonitorInfo info2 = { 0 };
  int rc = 0;
 
  if (!m)
  {
    MonitorCurMboxDescriptor = -1;
    MonitorCurMboxChanged = false;
  }
 
  if (monitor_resolve(&info, m) != RESOLVE_RES_OK_EXISTING)
  {
    rc = 2;
    goto cleanup;
  }
 
  struct Mailbox *m_cur = get_current_mailbox();
  if (m_cur)
  {
    if (m)
    {
      if ((monitor_resolve(&info2, NULL) == RESOLVE_RES_OK_EXISTING) &&
          (info.st_ino == info2.st_ino) && (info.st_dev == info2.st_dev))
      {
        rc = 1;
        goto cleanup;
      }
    }
    else
    {
      if (mailbox_find(m_cur->realpath))
      {
        rc = 1;
        goto cleanup;
      }
    }
  }
 
  inotify_rm_watch(info.monitor->desc, INotifyFd);
  mutt_debug(LL_DEBUG3, "inotify_rm_watch for '%s' descriptor=%d\n", info.path,
             info.monitor->desc);
 
  monitor_delete(info.monitor);
  monitor_check_cleanup();
 
cleanup:
  monitor_info_free(&info);
  monitor_info_free(&info2);
  return rc;
}

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

MonitorFilesChanged

bool MonitorFilesChanged = false

Set to true when a monitored file has changed.

true after a monitored file has changed

Set to true when a monitored file has changed.

Definition at line 53 of file monitor.c.

MonitorCurMboxChanged

bool MonitorCurMboxChanged = false

Set to true when the current mailbox has changed.

true after the current mailbox has changed

Set to true when the current mailbox has changed.

Definition at line 55 of file monitor.c.

INotifyFd

int INotifyFd = -1

static

Inotify file descriptor.

Definition at line 58 of file monitor.c.

Monitor

struct Monitor* Monitor = NULL

static

Linked list of monitored Mailboxes.

Definition at line 60 of file monitor.c.

PollFdsCount

size_t PollFdsCount = 0

static

Number of used entries in the PollFds array.

Definition at line 62 of file monitor.c.

PollFdsLen

size_t PollFdsLen = 0

static

Size of PollFds array.

Definition at line 64 of file monitor.c.

PollFds

struct pollfd* PollFds = NULL

static

Array of monitored file descriptors.

Definition at line 66 of file monitor.c.

MonitorCurMboxDescriptor

int MonitorCurMboxDescriptor = -1

static

Monitor file descriptor of the current mailbox.

Definition at line 68 of file monitor.c.