golang/mikael/madonctl: vendor/github.com/fsnotify/fsnotify/README.md@6d9efbef00a9 (annotated)

242 2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	1	# File system notifications for Go
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	2
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	3	[![GoDoc](https://godoc.org/github.com/fsnotify/fsnotify?status.svg)](https://godoc.org/github.com/fsnotify/fsnotify) [![Go Report Card](https://goreportcard.com/badge/github.com/fsnotify/fsnotify)](https://goreportcard.com/report/github.com/fsnotify/fsnotify)
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	4
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	5	fsnotify utilizes [golang.org/x/sys](https://godoc.org/golang.org/x/sys) rather than `syscall` from the standard library. Ensure you have the latest version installed by running:
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	6
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	7	```console
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	8	go get -u golang.org/x/sys/...
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	9	```
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	10
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	11	Cross platform: Windows, Linux, BSD and macOS.
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	12
256 6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	13	\| Adapter \| OS \| Status \|
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	14	\| --------------------- \| -------------------------------- \| ------------------------------------------------------------------------------------------------------------------------------- \|
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	15	\| inotify \| Linux 2.6.27 or later, Android\* \| Supported [![Build Status](https://travis-ci.org/fsnotify/fsnotify.svg?branch=master)](https://travis-ci.org/fsnotify/fsnotify) \|
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	16	\| kqueue \| BSD, macOS, iOS\* \| Supported [![Build Status](https://travis-ci.org/fsnotify/fsnotify.svg?branch=master)](https://travis-ci.org/fsnotify/fsnotify) \|
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	17	\| ReadDirectoryChangesW \| Windows \| Supported [![Build Status](https://travis-ci.org/fsnotify/fsnotify.svg?branch=master)](https://travis-ci.org/fsnotify/fsnotify) \|
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	18	\| FSEvents \| macOS \| [Planned](https://github.com/fsnotify/fsnotify/issues/11) \|
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	19	\| FEN \| Solaris 11 \| [In Progress](https://github.com/fsnotify/fsnotify/issues/12) \|
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	20	\| fanotify \| Linux 2.6.37+ \| [Planned](https://github.com/fsnotify/fsnotify/issues/114) \|
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	21	\| USN Journals \| Windows \| [Maybe](https://github.com/fsnotify/fsnotify/issues/53) \|
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	22	\| Polling \| All \| [Maybe](https://github.com/fsnotify/fsnotify/issues/9) \|
242 2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	23
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	24	\* Android and iOS are untested.
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	25
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	26	Please see [the documentation](https://godoc.org/github.com/fsnotify/fsnotify) and consult the [FAQ](#faq) for usage information.
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	27
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	28	## API stability
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	29
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	30	fsnotify is a fork of [howeyc/fsnotify](https://godoc.org/github.com/howeyc/fsnotify) with a new API as of v1.0. The API is based on [this design document](http://goo.gl/MrYxyA).
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	31
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	32	All [releases](https://github.com/fsnotify/fsnotify/releases) are tagged based on [Semantic Versioning](http://semver.org/). Further API changes are [planned](https://github.com/fsnotify/fsnotify/milestones), and will be tagged with a new major revision number.
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	33
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	34	Go 1.6 supports dependencies located in the `vendor/` folder. Unless you are creating a library, it is recommended that you copy fsnotify into `vendor/github.com/fsnotify/fsnotify` within your project, and likewise for `golang.org/x/sys`.
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	35
256 6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	36	## Usage
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	37
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	38	```go
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	39	package main
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	40
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	41	import (
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	42	"log"
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	43
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	44	"github.com/fsnotify/fsnotify"
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	45	)
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	46
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	47	func main() {
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	48	watcher, err := fsnotify.NewWatcher()
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	49	if err != nil {
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	50	log.Fatal(err)
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	51	}
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	52	defer watcher.Close()
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	53
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	54	done := make(chan bool)
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	55	go func() {
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	56	for {
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	57	select {
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	58	case event, ok := <-watcher.Events:
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	59	if !ok {
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	60	return
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	61	}
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	62	log.Println("event:", event)
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	63	if event.Op&fsnotify.Write == fsnotify.Write {
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	64	log.Println("modified file:", event.Name)
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	65	}
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	66	case err, ok := <-watcher.Errors:
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	67	if !ok {
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	68	return
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	69	}
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	70	log.Println("error:", err)
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	71	}
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	72	}
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	73	}()
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	74
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	75	err = watcher.Add("/tmp/foo")
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	76	if err != nil {
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	77	log.Fatal(err)
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	78	}
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	79	<-done
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	80	}
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	81	```
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	82
242 2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	83	## Contributing
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	84
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	85	Please refer to [CONTRIBUTING][] before opening an issue or pull request.
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	86
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	87	## Example
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	88
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	89	See [example_test.go](https://github.com/fsnotify/fsnotify/blob/master/example_test.go).
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	90
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	91	## FAQ
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	92
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	93	When a file is moved to another directory is it still being watched?
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	94
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	95	No (it shouldn't be, unless you are watching where it was moved to).
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	96
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	97	When I watch a directory, are all subdirectories watched as well?
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	98
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	99	No, you must add watches for any directory you want to watch (a recursive watcher is on the roadmap [#18][]).
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	100
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	101	Do I have to watch the Error and Event channels in a separate goroutine?
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	102
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	103	As of now, yes. Looking into making this single-thread friendly (see [howeyc #7][#7])
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	104
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	105	Why am I receiving multiple events for the same file on OS X?
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	106
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	107	Spotlight indexing on OS X can result in multiple events (see [howeyc #62][#62]). A temporary workaround is to add your folder(s) to the Spotlight Privacy settings until we have a native FSEvents implementation (see [#11][]).
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	108
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	109	How many files can be watched at once?
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	110
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	111	There are OS-specific limits as to how many watches can be created:
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	112	* Linux: /proc/sys/fs/inotify/max_user_watches contains the limit, reaching this limit results in a "no space left on device" error.
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	113	* BSD / OSX: sysctl variables "kern.maxfiles" and "kern.maxfilesperproc", reaching these limits results in a "too many open files" error.
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	114
256 6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	115	Why don't notifications work with NFS filesystems or filesystem in userspace (FUSE)?
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	116
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	117	fsnotify requires support from underlying OS to work. The current NFS protocol does not provide network level support for file notifications.
6d9efbef00a9 Update dependencies Mikael Berthe <mikael@lilotux.net> parents: 242 diff changeset	118
242 2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	119	[#62]: https://github.com/howeyc/fsnotify/issues/62
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	120	[#18]: https://github.com/fsnotify/fsnotify/issues/18
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	121	[#11]: https://github.com/fsnotify/fsnotify/issues/11
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	122	[#7]: https://github.com/howeyc/fsnotify/issues/7
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	123
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	124	[contributing]: https://github.com/fsnotify/fsnotify/blob/master/CONTRIBUTING.md
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	125
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	126	## Related Projects
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	127
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	128	* [notify](https://github.com/rjeczalik/notify)
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	129	* [fsevents](https://github.com/fsnotify/fsevents)
2a9ec03fe5a1 Use vendoring for backward compatibility Mikael Berthe <mikael@lilotux.net> parents: diff changeset	130

author	Mikael Berthe <mikael@lilotux.net>
	Sun, 11 Jul 2021 10:35:56 +0200
changeset 256	6d9efbef00a9
parent 242	2a9ec03fe5a1
child 260	445e01aede7e
permissions	-rw-r--r--