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 Treuer
• 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()

static 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()

static 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()

static 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()

static 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()

static 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()

static 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()

static 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()

static 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()

static 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

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

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.