fsnotify

package
v1.3.8 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 17, 2022 License: MIT, BSD-3-Clause Imports: 10 Imported by: 0

README

File system notifications for Go

Go Reference Go Report Card Maintainers Wanted

fsnotify utilizes golang.org/x/sys rather than syscall from the standard library.

Cross platform: Windows, Linux, BSD and macOS.

Adapter OS Status
inotify Linux 2.6.27 or later, Android* Supported
kqueue BSD, macOS, iOS* Supported
ReadDirectoryChangesW Windows Supported
FSEvents macOS Planned
FEN Solaris 11 In Progress
fanotify Linux 2.6.37+ Maybe
USN Journals Windows Maybe
Polling *
All* Maybe

* Android and iOS are untested.

Please see the documentation and consult the FAQ for usage information.

API stability

fsnotify is a fork of howeyc/fsnotify with a new API as of v1.0. The API is based on this design document.

All releases are tagged based on Semantic Versioning.

Usage

package main

import (
	"log"

	"github.com/fsnotify/fsnotify"
)

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

	done := make(chan bool)
	go func() {
		for {
			select {
			case event, ok := <-watcher.Events:
				if !ok {
					return
				}
				log.Println("event:", event)
				if event.Op&fsnotify.Write == fsnotify.Write {
					log.Println("modified file:", event.Name)
				}
			case err, ok := <-watcher.Errors:
				if !ok {
					return
				}
				log.Println("error:", err)
			}
		}
	}()

	err = watcher.Add("/tmp/foo")
	if err != nil {
		log.Fatal(err)
	}
	<-done
}

Contributing

Please refer to CONTRIBUTING before opening an issue or pull request.

FAQ

When a file is moved to another directory is it still being watched?

No (it shouldn't be, unless you are watching where it was moved to).

When I watch a directory, are all subdirectories watched as well?

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 separate goroutine?

As of now, yes. Looking into making this single-thread friendly (see howeyc #7)

Why am I receiving multiple events for the same file on OS X?

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

How many files can be watched at once?

There are OS-specific limits as to how many watches can be created:

  • Linux: /proc/sys/fs/inotify/max_user_watches contains the limit, reaching this limit results in a "no space left on device" error.
  • BSD / OSX: sysctl variables "kern.maxfiles" and "kern.maxfilesperproc", reaching these limits results in a "too many open files" error.

Why don't notifications work with NFS filesystems or filesystem in userspace (FUSE)?

fsnotify requires support from underlying OS to work. The current NFS protocol does not provide network level support for file notifications.

Documentation

Overview

Package fsnotify provides a platform-independent interface for file system notifications.

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrEventOverflow = errors.New("fsnotify queue overflow")
)

Common errors that can be reported by a watcher

Functions

This section is empty.

Types

type Event

type Event struct {
	Name string // Relative path to the file or directory.
	Op   Op     // File operation that triggered the event.
}

Event represents a single file system notification.

func (Event) String

func (e Event) String() string

String returns a string representation of the event in the form "file: REMOVE|WRITE|..."

type Op

type Op uint32

Op describes a set of file operations.

const (
	Create Op = 1 << iota
	Write
	Remove
	Rename
	Chmod
)

These are the generalized file operations that can trigger a notification.

func (Op) String

func (op Op) String() string

type Watcher

type Watcher struct {
	Events chan Event
	Errors chan error
	// contains filtered or unexported fields
}

Watcher watches a set of files, delivering events to a channel.

func NewWatcher

func NewWatcher() (*Watcher, error)

NewWatcher establishes a new watcher with the underlying OS and begins waiting for events.

func (*Watcher) Add

func (w *Watcher) Add(name string) error

Add starts watching the named file or directory (non-recursively).

func (*Watcher) Close

func (w *Watcher) Close() error

Close removes all watches and closes the events channel.

func (*Watcher) Remove

func (w *Watcher) Remove(name string) error

Remove stops watching the named file or directory (non-recursively).

func (*Watcher) WatchList

func (w *Watcher) WatchList() []string

WatchList returns the directories and files that are being monitered.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL