vendor/github.com/fsnotify/fsnotify/inotify.go

   1 // Copyright 2010 The Go Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style
   3 // license that can be found in the LICENSE file.
   4
   5 // +build linux
   6
   7 package fsnotify
   8
   9 import (
  10         "errors"
  11         "fmt"
  12         "io"
  13         "os"
  14         "path/filepath"
  15         "strings"
  16         "sync"
  17         "unsafe"
  18
  19         "golang.org/x/sys/unix"
  20 )
  21
  22 // Watcher watches a set of files, delivering events to a channel.
  23 type Watcher struct {
  24         Events   chan Event
  25         Errors   chan error
  26         mu       sync.Mutex // Map access
  27         fd       int
  28         poller   *fdPoller
  29         watches  map[string]*watch // Map of inotify watches (key: path)
  30         paths    map[int]string    // Map of watched paths (key: watch descriptor)
  31         done     chan struct{}     // Channel for sending a "quit message" to the reader goroutine
  32         doneResp chan struct{}     // Channel to respond to Close
  33 }
  34
  35 // NewWatcher establishes a new watcher with the underlying OS and begins waiting for events.
  36 func NewWatcher() (*Watcher, error) {
  37         // Create inotify fd
  38         fd, errno := unix.InotifyInit1(unix.IN_CLOEXEC)
  39         if fd == -1 {
  40                 return nil, errno
  41         }
  42         // Create epoll
  43         poller, err := newFdPoller(fd)
  44         if err != nil {
  45                 unix.Close(fd)
  46                 return nil, err
  47         }
  48         w := &Watcher{
  49                 fd:       fd,
  50                 poller:   poller,
  51                 watches:  make(map[string]*watch),
  52                 paths:    make(map[int]string),
  53                 Events:   make(chan Event),
  54                 Errors:   make(chan error),
  55                 done:     make(chan struct{}),
  56                 doneResp: make(chan struct{}),
  57         }
  58
  59         go w.readEvents()
  60         return w, nil
  61 }
  62
  63 func (w *Watcher) isClosed() bool {
  64         select {
  65         case <-w.done:
  66                 return true
  67         default:
  68                 return false
  69         }
  70 }
  71
  72 // Close removes all watches and closes the events channel.
  73 func (w *Watcher) Close() error {
  74         if w.isClosed() {
  75                 return nil
  76         }
  77
  78         // Send 'close' signal to goroutine, and set the Watcher to closed.
  79         close(w.done)
  80
  81         // Wake up goroutine
  82         w.poller.wake()
  83
  84         // Wait for goroutine to close
  85         <-w.doneResp
  86
  87         return nil
  88 }
  89
  90 // Add starts watching the named file or directory (non-recursively).
  91 func (w *Watcher) Add(name string) error {
  92         name = filepath.Clean(name)
  93         if w.isClosed() {
  94                 return errors.New("inotify instance already closed")
  95         }
  96
  97         const agnosticEvents = unix.IN_MOVED_TO | unix.IN_MOVED_FROM |
  98                 unix.IN_CREATE | unix.IN_ATTRIB | unix.IN_MODIFY |
  99                 unix.IN_MOVE_SELF | unix.IN_DELETE | unix.IN_DELETE_SELF
 100
 101         var flags uint32 = agnosticEvents
 102
 103         w.mu.Lock()
 104         defer w.mu.Unlock()
 105         watchEntry := w.watches[name]
 106         if watchEntry != nil {
 107                 flags |= watchEntry.flags | unix.IN_MASK_ADD
 108         }
 109         wd, errno := unix.InotifyAddWatch(w.fd, name, flags)
 110         if wd == -1 {
 111                 return errno
 112         }
 113
 114         if watchEntry == nil {
 115                 w.watches[name] = &watch{wd: uint32(wd), flags: flags}
 116                 w.paths[wd] = name
 117         } else {
 118                 watchEntry.wd = uint32(wd)
 119                 watchEntry.flags = flags
 120         }
 121
 122         return nil
 123 }
 124
 125 // Remove stops watching the named file or directory (non-recursively).
 126 func (w *Watcher) Remove(name string) error {
 127         name = filepath.Clean(name)
 128
 129         // Fetch the watch.
 130         w.mu.Lock()
 131         defer w.mu.Unlock()
 132         watch, ok := w.watches[name]
 133
 134         // Remove it from inotify.
 135         if !ok {
 136                 return fmt.Errorf("can't remove non-existent inotify watch for: %s", name)
 137         }
 138
 139         // We successfully removed the watch if InotifyRmWatch doesn't return an
 140         // error, we need to clean up our internal state to ensure it matches
 141         // inotify's kernel state.
 142         delete(w.paths, int(watch.wd))
 143         delete(w.watches, name)
 144
 145         // inotify_rm_watch will return EINVAL if the file has been deleted;
 146         // the inotify will already have been removed.
 147         // watches and pathes are deleted in ignoreLinux() implicitly and asynchronously
 148         // by calling inotify_rm_watch() below. e.g. readEvents() goroutine receives IN_IGNORE
 149         // so that EINVAL means that the wd is being rm_watch()ed or its file removed
 150         // by another thread and we have not received IN_IGNORE event.
 151         success, errno := unix.InotifyRmWatch(w.fd, watch.wd)
 152         if success == -1 {
 153                 // TODO: Perhaps it's not helpful to return an error here in every case.
 154                 // the only two possible errors are:
 155                 // EBADF, which happens when w.fd is not a valid file descriptor of any kind.
 156                 // EINVAL, which is when fd is not an inotify descriptor or wd is not a valid watch descriptor.
 157                 // Watch descriptors are invalidated when they are removed explicitly or implicitly;
 158                 // explicitly by inotify_rm_watch, implicitly when the file they are watching is deleted.
 159                 return errno
 160         }
 161
 162         return nil
 163 }
 164
 165 type watch struct {
 166         wd    uint32 // Watch descriptor (as returned by the inotify_add_watch() syscall)
 167         flags uint32 // inotify flags of this watch (see inotify(7) for the list of valid flags)
 168 }
 169
 170 // readEvents reads from the inotify file descriptor, converts the
 171 // received events into Event objects and sends them via the Events channel
 172 func (w *Watcher) readEvents() {
 173         var (
 174                 buf   [unix.SizeofInotifyEvent * 4096]byte // Buffer for a maximum of 4096 raw events
 175                 n     int                                  // Number of bytes read with read()
 176                 errno error                                // Syscall errno
 177                 ok    bool                                 // For poller.wait
 178         )
 179
 180         defer close(w.doneResp)
 181         defer close(w.Errors)
 182         defer close(w.Events)
 183         defer unix.Close(w.fd)
 184         defer w.poller.close()
 185
 186         for {
 187                 // See if we have been closed.
 188                 if w.isClosed() {
 189                         return
 190                 }
 191
 192                 ok, errno = w.poller.wait()
 193                 if errno != nil {
 194                         select {
 195                         case w.Errors <- errno:
 196                         case <-w.done:
 197                                 return
 198                         }
 199                         continue
 200                 }
 201
 202                 if !ok {
 203                         continue
 204                 }
 205
 206                 n, errno = unix.Read(w.fd, buf[:])
 207                 // If a signal interrupted execution, see if we've been asked to close, and try again.
 208                 // http://man7.org/linux/man-pages/man7/signal.7.html :
 209                 // "Before Linux 3.8, reads from an inotify(7) file descriptor were not restartable"
 210                 if errno == unix.EINTR {
 211                         continue
 212                 }
 213
 214                 // unix.Read might have been woken up by Close. If so, we're done.
 215                 if w.isClosed() {
 216                         return
 217                 }
 218
 219                 if n < unix.SizeofInotifyEvent {
 220                         var err error
 221                         if n == 0 {
 222                                 // If EOF is received. This should really never happen.
 223                                 err = io.EOF
 224                         } else if n < 0 {
 225                                 // If an error occurred while reading.
 226                                 err = errno
 227                         } else {
 228                                 // Read was too short.
 229                                 err = errors.New("notify: short read in readEvents()")
 230                         }
 231                         select {
 232                         case w.Errors <- err:
 233                         case <-w.done:
 234                                 return
 235                         }
 236                         continue
 237                 }
 238
 239                 var offset uint32
 240                 // We don't know how many events we just read into the buffer
 241                 // While the offset points to at least one whole event...
 242                 for offset <= uint32(n-unix.SizeofInotifyEvent) {
 243                         // Point "raw" to the event in the buffer
 244                         raw := (*unix.InotifyEvent)(unsafe.Pointer(&buf[offset]))
 245
 246                         mask := uint32(raw.Mask)
 247                         nameLen := uint32(raw.Len)
 248
 249                         if mask&unix.IN_Q_OVERFLOW != 0 {
 250                                 select {
 251                                 case w.Errors <- ErrEventOverflow:
 252                                 case <-w.done:
 253                                         return
 254                                 }
 255                         }
 256
 257                         // If the event happened to the watched directory or the watched file, the kernel
 258                         // doesn't append the filename to the event, but we would like to always fill the
 259                         // the "Name" field with a valid filename. We retrieve the path of the watch from
 260                         // the "paths" map.
 261                         w.mu.Lock()
 262                         name, ok := w.paths[int(raw.Wd)]
 263                         // IN_DELETE_SELF occurs when the file/directory being watched is removed.
 264                         // This is a sign to clean up the maps, otherwise we are no longer in sync
 265                         // with the inotify kernel state which has already deleted the watch
 266                         // automatically.
 267                         if ok && mask&unix.IN_DELETE_SELF == unix.IN_DELETE_SELF {
 268                                 delete(w.paths, int(raw.Wd))
 269                                 delete(w.watches, name)
 270                         }
 271                         w.mu.Unlock()
 272
 273                         if nameLen > 0 {
 274                                 // Point "bytes" at the first byte of the filename
 275                                 bytes := (*[unix.PathMax]byte)(unsafe.Pointer(&buf[offset+unix.SizeofInotifyEvent]))
 276                                 // The filename is padded with NULL bytes. TrimRight() gets rid of those.
 277                                 name += "/" + strings.TrimRight(string(bytes[0:nameLen]), "\000")
 278                         }
 279
 280                         event := newEvent(name, mask)
 281
 282                         // Send the events that are not ignored on the events channel
 283                         if !event.ignoreLinux(mask) {
 284                                 select {
 285                                 case w.Events <- event:
 286                                 case <-w.done:
 287                                         return
 288                                 }
 289                         }
 290
 291                         // Move to the next event in the buffer
 292                         offset += unix.SizeofInotifyEvent + nameLen
 293                 }
 294         }
 295 }
 296
 297 // Certain types of events can be "ignored" and not sent over the Events
 298 // channel. Such as events marked ignore by the kernel, or MODIFY events
 299 // against files that do not exist.
 300 func (e *Event) ignoreLinux(mask uint32) bool {
 301         // Ignore anything the inotify API says to ignore
 302         if mask&unix.IN_IGNORED == unix.IN_IGNORED {
 303                 return true
 304         }
 305
 306         // If the event is not a DELETE or RENAME, the file must exist.
 307         // Otherwise the event is ignored.
 308         // *Note*: this was put in place because it was seen that a MODIFY
 309         // event was sent after the DELETE. This ignores that MODIFY and
 310         // assumes a DELETE will come or has come if the file doesn't exist.
 311         if !(e.Op&Remove == Remove || e.Op&Rename == Rename) {
 312                 _, statErr := os.Lstat(e.Name)
 313                 return os.IsNotExist(statErr)
 314         }
 315         return false
 316 }
 317
 318 // newEvent returns an platform-independent Event based on an inotify mask.
 319 func newEvent(name string, mask uint32) Event {
 320         e := Event{Name: name}
 321         if mask&unix.IN_CREATE == unix.IN_CREATE || mask&unix.IN_MOVED_TO == unix.IN_MOVED_TO {
 322                 e.Op |= Create
 323         }
 324         if mask&unix.IN_DELETE_SELF == unix.IN_DELETE_SELF || mask&unix.IN_DELETE == unix.IN_DELETE {
 325                 e.Op |= Remove
 326         }
 327         if mask&unix.IN_MODIFY == unix.IN_MODIFY {
 328                 e.Op |= Write
 329         }
 330         if mask&unix.IN_MOVE_SELF == unix.IN_MOVE_SELF || mask&unix.IN_MOVED_FROM == unix.IN_MOVED_FROM {
 331                 e.Op |= Rename
 332         }
 333         if mask&unix.IN_ATTRIB == unix.IN_ATTRIB {
 334                 e.Op |= Chmod
 335         }
 336         return e
 337 }