notify

Documentation

Index

• Constants
• type Event
  • func (e Event) String() string
• type EventInfo
• type Watcher
  • func NewWatcher(c chan<- EventInfo) Watcher

Constants

const (
	Create = osSpecificCreate
	Remove = osSpecificRemove
	Write  = osSpecificWrite
	Rename = osSpecificRename

	// All is handful alias for all platform-independent event values.
	All = Create | Remove | Write | Rename
)

Create, Remove, Write and Rename are the only event values guaranteed to be present on all platforms.

const (
	InAccess       = Event(unix.IN_ACCESS)        // File was accessed
	InModify       = Event(unix.IN_MODIFY)        // File was modified
	InAttrib       = Event(unix.IN_ATTRIB)        // Metadata changed
	InCloseWrite   = Event(unix.IN_CLOSE_WRITE)   // Writtable file was closed
	InCloseNowrite = Event(unix.IN_CLOSE_NOWRITE) // Unwrittable file closed
	InOpen         = Event(unix.IN_OPEN)          // File was opened
	InMovedFrom    = Event(unix.IN_MOVED_FROM)    // File was moved from X
	InMovedTo      = Event(unix.IN_MOVED_TO)      // File was moved to Y
	InCreate       = Event(unix.IN_CREATE)        // Subfile was created
	InDelete       = Event(unix.IN_DELETE)        // Subfile was deleted
	InDeleteSelf   = Event(unix.IN_DELETE_SELF)   // Self was deleted
	InMoveSelf     = Event(unix.IN_MOVE_SELF)     // Self was moved
)

Inotify specific masks are legal, implemented events that are guaranteed to work with notify package on linux-based systems.

Types

type Event

type Event uint32

Event represents the type of filesystem action.

Number of available event values is dependent on the target system or the watcher implmenetation used (e.g. it's possible to use either kqueue or FSEvents on Darwin).

Please consult documentation for your target platform to see list of all available events.

func (Event) String

func (e Event) String() string

String implements fmt.Stringer interface.

type EventInfo

type EventInfo interface {
	Event() Event     // event value for the filesystem action
	Path() string     // real path of the file or directory
	Sys() interface{} // underlying data source (can return nil)
}

EventInfo describes an event reported by the underlying filesystem notification subsystem.

It always describes single event, even if the OS reported a coalesced action. Reported path is absolute and clean.

For non-recursive watchpoints its base is always equal to the path passed to corresponding Watch call.

The value of Sys if system-dependent and can be nil.

Sys

Under Darwin (FSEvents) Sys() always returns a non-nil *notify.FSEvent value, which is defined as:

type FSEvent struct {
    Path  string // real path of the file or directory
    ID    uint64 // ID of the event (FSEventStreamEventId)
    Flags uint32 // joint FSEvents* flags (FSEventStreamEventFlags)
}

For possible values of Flags see Darwin godoc for notify or FSEvents documentation for FSEventStreamEventFlags constants:

https://developer.apple.com/library/mac/documentation/Darwin/Reference/FSEvents_Ref/index.html#//apple_ref/doc/constant_group/FSEventStreamEventFlags

Under Linux (inotify) Sys() always returns a non-nil *unix.InotifyEvent value, defined as:

type InotifyEvent struct {
    Wd     int32    // Watch descriptor
    Mask   uint32   // Mask describing event
    Cookie uint32   // Unique cookie associating related events (for rename(2))
    Len    uint32   // Size of name field
    Name   [0]uint8 // Optional null-terminated name
}

More information about inotify masks and the usage of inotify_event structure can be found at:

http://man7.org/linux/man-pages/man7/inotify.7.html

Under Darwin, DragonFlyBSD, FreeBSD, NetBSD, OpenBSD (kqueue) Sys() always returns a non-nil *notify.Kevent value, which is defined as:

type Kevent struct {
    Kevent *syscall.Kevent_t // Kevent is a kqueue specific structure
    FI     os.FileInfo       // FI describes file/dir
}

More information about syscall.Kevent_t can be found at:

https://www.freebsd.org/cgi/man.cgi?query=kqueue

Under Windows (ReadDirectoryChangesW) Sys() always returns nil. The documentation of watcher's WinAPI function can be found at:

https://msdn.microsoft.com/en-us/library/windows/desktop/aa365465%28v=vs.85%29.aspx

type Watcher

type Watcher interface {
	// Watch requests a watcher creation for the given path and given event set.
	Watch(path string, event Event) error

	// Unwatch requests a watcher deletion for the given path and given event set.
	Unwatch(path string) error

	// Rewatch provides a functionality for modifying existing watch-points, like
	// expanding its event set.
	//
	// Rewatch modifies existing watch-point under for the given path. It passes
	// the existing event set currently registered for the given path, and the
	// new, requested event set.
	//
	// It is guaranteed that Tree will not pass to Rewatch zero value for any
	// of its arguments. If old == new and watcher can be upgraded to
	// recursiveWatcher interface, a watch for the corresponding path is expected
	// to be changed from recursive to the non-recursive one.
	Rewatch(path string, old, new Event) error

	// Close unwatches all paths that are registered. When Close returns, it
	// is expected it will report no more events.
	Close() error
}

Watcher is a intermediate interface for wrapping inotify, ReadDirChangesW, FSEvents, kqueue and poller implementations.

The watcher implementation is expected to do its own mapping between paths and create watchers if underlying event notification does not support it. For the ease of implementation it is guaranteed that paths provided via Watch and Unwatch methods are absolute and clean.

func NewWatcher

func NewWatcher(c chan<- EventInfo) Watcher

NewWatcher creates new non-recursive inotify backed by inotify.