refs/tags/v1.7.0 - third_party/github.com/fsnotify/fsnotify

tag	e78666528154600ed55506fb4bd38b758e091c22
tagger	Martin Tournoij <martin@arp242.net>	Sun Oct 22 07:24:10 2023 +0100
object	cfc9c4f277ea6ec18de92444b31983b183deb4fb

Release 1.7.0

This version of fsnotify needs Go 1.17.

Additions:

- illumos: add FEN backend to support illumos and Solaris. ([#371])

- all: add `NewBufferedWatcher()` to use a buffered channel, which can
  be useful in cases where you can't control the kernel buffer and
  receive a large number of events in bursts. ([#550], [#572])

- all: add `AddWith()`, which is identical to `Add()` but allows passing
  options. ([#521])

- windows: allow setting the ReadDirectoryChangesW() buffer size with
  `fsnotify.WithBufferSize()`; the default of 64K is the highest value
  that works on all platforms and is enough for most purposes, but in
  some cases a highest buffer is needed. ([#521])

Changes and fixes:

- inotify: remove watcher if a watched path is renamed ([#518])

  After a rename the reported name wasn't updated, or even an empty
  string. Inotify doesn't provide any good facilities to update it, so
  just remove the watcher. This is already how it worked on kqueue and
  FEN.

  On Windows this does work, and remains working.

- windows: don't listen for file attribute changes ([#520])

  File attribute changes are sent as `FILE_ACTION_MODIFIED` by the
  Windows API, with no way to see if they're a file write or attribute
  change, so would show up as a fsnotify.Write event. This is never
  useful, and could result in many spurious Write events.

- windows: return `ErrEventOverflow` if the buffer is full ([#525])

  Before it would merely return "short read", making it hard to detect
  this error.

- kqueue: make sure events for all files are delivered properly when
  removing a watched directory ([#526])

  Previously they would get sent with `""` (empty string) or `"."` as
  the path name.

- kqueue: don't emit spurious Create events for symbolic links ([#524])

  The link would get resolved but kqueue would "forget" it already saw
  the link itself, resulting on a Create for every Write event for the
  directory.

- all: return `ErrClosed` on `Add()` when the watcher is closed ([#516])

- other: add `Watcher.Errors` and `Watcher.Events` to the no-op
  `Watcher` in `backend_other.go`, making it easier to use on
  unsupported platforms such as WASM, AIX, etc. ([#528])

- other: use the `backend_other.go` no-op if the `appengine` build tag
  is set; Google AppEngine forbids usage of the unsafe package so the
  inotify backend won't compile there.

[#371]: https://github.com/fsnotify/fsnotify/pull/371
[#516]: https://github.com/fsnotify/fsnotify/pull/516
[#518]: https://github.com/fsnotify/fsnotify/pull/518
[#520]: https://github.com/fsnotify/fsnotify/pull/520
[#521]: https://github.com/fsnotify/fsnotify/pull/521
[#524]: https://github.com/fsnotify/fsnotify/pull/524
[#525]: https://github.com/fsnotify/fsnotify/pull/525
[#526]: https://github.com/fsnotify/fsnotify/pull/526
[#528]: https://github.com/fsnotify/fsnotify/pull/528
[#537]: https://github.com/fsnotify/fsnotify/pull/537
[#550]: https://github.com/fsnotify/fsnotify/pull/550
[#572]: https://github.com/fsnotify/fsnotify/pull/572

commit	cfc9c4f277ea6ec18de92444b31983b183deb4fb	[log] [tgz]
author	Martin Tournoij <martin@arp242.net>	Sun Oct 22 07:24:00 2023 +0100
committer	Martin Tournoij <martin@arp242.net>	Sun Oct 22 07:24:00 2023 +0100
tree	3af1f5b0f8a3c0e869fd2b2a6e662e5f68415dcd
parent	c3fa8e6aec899190d480cf528805e4fd56b6f471 [diff]

Few more tiny doc fixes >_<

6 files changed

tree: 3af1f5b0f8a3c0e869fd2b2a6e662e5f68415dcd

README.md

fsnotify is a Go library to provide cross-platform filesystem notifications on Windows, Linux, macOS, BSD, and illumos.

Go 1.17 or newer is required; the full documentation is at https://pkg.go.dev/github.com/fsnotify/fsnotify

Platform support:

Backend	OS	Status
inotify	Linux	Supported
kqueue	BSD, macOS	Supported
ReadDirectoryChangesW	Windows	Supported
FEN	illumos	Supported
fanotify	Linux 5.9+	Not yet
AHAFS	AIX	aix branch; experimental due to lack of maintainer and test environment
FSEvents	macOS	Needs support in x/sys/unix
USN Journals	Windows	Needs support in x/sys/windows
Polling	All	Not yet

Linux and illumos should include Android and Solaris, but these are currently untested.

Usage

A basic example:

package main

import (
    "log"

    "github.com/fsnotify/fsnotify"
)

func main() {
    // Create new watcher.
    watcher, err := fsnotify.NewWatcher()
    if err != nil {
        log.Fatal(err)
    }
    defer watcher.Close()

    // Start listening for events.
    go func() {
        for {
            select {
            case event, ok := <-watcher.Events:
                if !ok {
                    return
                }
                log.Println("event:", event)
                if event.Has(fsnotify.Write) {
                    log.Println("modified file:", event.Name)
                }
            case err, ok := <-watcher.Errors:
                if !ok {
                    return
                }
                log.Println("error:", err)
            }
        }
    }()

    // Add a path.
    err = watcher.Add("/tmp")
    if err != nil {
        log.Fatal(err)
    }

    // Block main goroutine forever.
    <-make(chan struct{})
}

Some more examples can be found in cmd/fsnotify, which can be run with:

% go run ./cmd/fsnotify

Further detailed documentation can be found in godoc: https://pkg.go.dev/github.com/fsnotify/fsnotify

FAQ

Will a file still be watched when it's moved to another directory?

No, not unless you are watching the location it was moved to.

Are subdirectories watched?

No, you must add watches for any directory you want to watch (a recursive watcher is on the roadmap: #18).

Do I have to watch the Error and Event channels in a goroutine?

Yes. You can read both channels in the same goroutine using select (you don't need a separate goroutine for both channels; see the example).

Why don't notifications work with NFS, SMB, FUSE, /proc, or /sys?

fsnotify requires support from underlying OS to work. The current NFS and SMB protocols does not provide network level support for file notifications, and neither do the /proc and /sys virtual filesystems.

This could be fixed with a polling watcher (#9), but it's not yet implemented.

Why do I get many Chmod events?

Some programs may generate a lot of attribute changes; for example Spotlight on macOS, anti-virus programs, backup applications, and some others are known to do this. As a rule, it‘s typically best to ignore Chmod events. They’re often not useful, and tend to cause problems.

Spotlight indexing on macOS can result in multiple events (see #15). A temporary workaround is to add your folder(s) to the Spotlight Privacy settings until we have a native FSEvents implementation (see #11).

Watching a file doesn't work well

Watching individual files (rather than directories) is generally not recommended as many programs (especially editors) update files atomically: it will write to a temporary file which is then moved to to destination, overwriting the original (or some variant thereof). The watcher on the original file is now lost, as that no longer exists.

The upshot of this is that a power failure or crash won't leave a half-written file.

Watch the parent directory and use Event.Name to filter out files you're not interested in. There is an example of this in cmd/fsnotify/file.go.

Platform-specific notes

Linux

When a file is removed a REMOVE event won't be emitted until all file descriptors are closed; it will emit a CHMOD instead:

fp := os.Open("file")
os.Remove("file")        // CHMOD
fp.Close()               // REMOVE

This is the event that inotify sends, so not much can be changed about this.

The fs.inotify.max_user_watches sysctl variable specifies the upper limit for the number of watches per user, and fs.inotify.max_user_instances specifies the maximum number of inotify instances per user. Every Watcher you create is an “instance”, and every path you add is a “watch”.

These are also exposed in /proc as /proc/sys/fs/inotify/max_user_watches and /proc/sys/fs/inotify/max_user_instances

To increase them you can use sysctl or write the value to proc file:

# The default values on Linux 5.18
sysctl fs.inotify.max_user_watches=124983
sysctl fs.inotify.max_user_instances=128

To make the changes persist on reboot edit /etc/sysctl.conf or /usr/lib/sysctl.d/50-default.conf (details differ per Linux distro; check your distro's documentation):

fs.inotify.max_user_watches=124983
fs.inotify.max_user_instances=128

Reaching the limit will result in a “no space left on device” or “too many open files” error.

kqueue (macOS, all BSD systems)

kqueue requires opening a file descriptor for every file that‘s being watched; so if you’re watching a directory with five files then that‘s six file descriptors. You will run in to your system’s “max open files” limit faster on these platforms.

The sysctl variables kern.maxfiles and kern.maxfilesperproc can be used to control the maximum number of open files.