Documentation ¶
Overview ¶
Package fsevents provides routines for recursively monitoring filesystem events on a Linux system using the inotify kernel subsystem.
Index ¶
- Variables
- func CheckMask(check uint32, mask uint32) bool
- type EventHandler
- type FsEvent
- func (e *FsEvent) IsDirChanged() bool
- func (e *FsEvent) IsDirCreated() bool
- func (e *FsEvent) IsDirEvent() bool
- func (e *FsEvent) IsDirRemoved() bool
- func (e *FsEvent) IsFileChanged() bool
- func (e *FsEvent) IsFileCreated() bool
- func (e *FsEvent) IsFileRemoved() bool
- func (e *FsEvent) IsRootDeletion(rootPath string) bool
- func (e *FsEvent) IsRootMoved(rootPath string) bool
- type WatchDescriptor
- type Watcher
- func (w *Watcher) AddDescriptor(dirPath string, mask uint32) (*WatchDescriptor, error)
- func (w *Watcher) DescriptorExists(watchPath string) bool
- func (w *Watcher) GetDescriptorByPath(watchPath string) *WatchDescriptor
- func (w *Watcher) GetDescriptorByWatch(wd int) *WatchDescriptor
- func (w *Watcher) GetEventCount() uint32
- func (w *Watcher) GetRunningDescriptors() int32
- func (w *Watcher) ListDescriptors() []string
- func (w *Watcher) ReadSingleEvent() (*FsEvent, error)
- func (w *Watcher) RecursiveAdd(rootPath string, mask uint32) error
- func (w *Watcher) RegisterEventHandler(handle EventHandler) error
- func (w *Watcher) RemoveDescriptor(path string) error
- func (w *Watcher) StartAll() error
- func (w *Watcher) StopAll() error
- func (w *Watcher) UnregisterEventHandler(removeMask uint32) error
- func (w *Watcher) Watch()
- func (w *Watcher) WatchAndHandle()
Constants ¶
This section is empty.
Variables ¶
var ( //Top-level Watcher errors ErrWatchNotCreated = errors.New("watcher could not be created") ErrNoRunningDescriptors = errors.New("watcher has no running descriptors") ErrNoEventHandles = errors.New("watcher has no registered event handles") //Descriptor errors ErrDescNotCreated = errors.New("descriptor could not be created") ErrDescNotStart = errors.New("descriptor could not be started") ErrDescRunning = errors.New("descriptor already running") ErrDescNotStopped = errors.New("descriptor could not be stopped") ErrDescAlreadyExists = errors.New("descriptor for that directory already exists") ErrDescNotRunning = errors.New("descriptor not running") ErrDescForEventNotFound = errors.New("descriptor for event not found") ErrDescNotFound = errors.New("descriptor not found") // Event handle errors ErrNoSuchHandle = errors.New("handle not found") ErrHandleError = errors.New("handle returned error") ErrHandleExists = errors.New("a handle for this mask already exists") //Inotify interface errors ErrIncompleteRead = errors.New("incomplete event read") ErrReadError = errors.New("error reading an event") )
var ( // Default inotify flags Accessed uint32 = unix.IN_ACCESS Modified uint32 = unix.IN_MODIFY AttrChange uint32 = unix.IN_ATTRIB CloseWrite uint32 = unix.IN_CLOSE_WRITE CloseRead uint32 = unix.IN_CLOSE_NOWRITE Open uint32 = unix.IN_OPEN MovedFrom uint32 = unix.IN_MOVED_FROM MovedTo uint32 = unix.IN_MOVED_TO Move uint32 = unix.IN_MOVE Create uint32 = unix.IN_CREATE Delete uint32 = unix.IN_DELETE RootDelete uint32 = unix.IN_DELETE_SELF RootMove uint32 = unix.IN_MOVE_SELF IsDir uint32 = unix.IN_ISDIR AllEvents = (Accessed | Modified | AttrChange | CloseWrite | CloseRead | Open | MovedFrom | MovedTo | MovedTo | Create | Delete | RootDelete | RootMove | IsDir) // The directory is not in the watch directory anymore // whether it was moved or deleted, it's *poof* gone DirRemovedEvent = MovedFrom | Delete | IsDir // Whether it was moved or copied into the watch directory, // or created with mkdir, there is a new directory DirCreatedEvent = MovedTo | Create | IsDir // A directory was closed with write permissions, modified, or its // attributes changed in some way DirChangedEvent = CloseWrite | Modified | AttrChange | IsDir // File events FileRemovedEvent = MovedFrom | Delete FileCreatedEvent = MovedTo | Create FileChangedEvent = CloseWrite | Modified | AttrChange // Root watch directory events RootEvent = RootDelete | RootMove )
Functions ¶
Types ¶
type EventHandler ¶
type EventHandler interface { // The Handle method is called by WatchAndHandle in response to a given event Handle(w *Watcher, event *FsEvent) error // The Check method is called to match Events with the correct EventHandle in the Watcher // Check must return true if the event described by the in event matches the argument Check(event *FsEvent) bool // The GetMask method returns the uint32 inotify mask this EventHandle handles GetMask() uint32 }
EventHandler allows for the Watcher to apply pre-registered functions in response to an event.
type FsEvent ¶
type FsEvent struct { // The name of the event's file Name string // The full path of the event Path string // The raw inotify event RawEvent *unix.InotifyEvent // The actual inotify watch descriptor related to this event Descriptor *WatchDescriptor // The serial ID of this event. ID is incremented in ReadSingleEvent upon successful event read ID uint32 // Timestamp of the time the event occurred in UTC Timestamp time.Time }
FsEvent is an inotify event along with the ID and timestamp of the event
func (*FsEvent) IsDirChanged ¶
IsDirChanged returns true if the event describes a directory that was closed with write permissions, modified, or its attributes changed
func (*FsEvent) IsDirCreated ¶
IsDirCreated returns true if the event describes a directory created within the root watch, or moved into the root watch directory
func (*FsEvent) IsDirEvent ¶
IsDirEvent Returns true if the event is a directory event
func (*FsEvent) IsDirRemoved ¶
IsDirRemoved returns true if the event describes a directory that was deleted or moved out of the root watch directory
func (*FsEvent) IsFileChanged ¶
IsFileChanged returns true if the event describes a file that was closed with write permissions, modified, or its attributes changed
func (*FsEvent) IsFileCreated ¶
IsFileCreated returns true if the event describes a file that was moved into, or created within the root watch directory
func (*FsEvent) IsFileRemoved ¶
IsFileRemoved returns true if the event describes a file was deleted or moved out of the root watch directory
func (*FsEvent) IsRootDeletion ¶
IsRootDeletion returns true if the event contains the inotify flag IN_DELETE_SELF and the rootPath argument matches the path in the FsEvent structure. This means the root watch directory has been deleted, and there will be no more events read from the descriptor since it doesn't exist anymore. You should probably handle this gracefully and always check for this event before doing anything else Also be sure to add the RootDelete flag to your watched events when initializing fsevents
func (*FsEvent) IsRootMoved ¶
IsRootMoved returns true if the event contains the inotify flag IN_MOVE_SELF and the rootPath argument matches the path in the FsEvent structure. This means the root watch directory has been moved. This may not matter to you at all, and depends on how you deal with paths in your program. Still, you should check for this event before doing anything else.
type WatchDescriptor ¶
type WatchDescriptor struct { // The path of this descriptor Path string // This descriptor's inotify watch mask Mask uint32 // This descriptor's inotify watch descriptor WatchDescriptor int // Is this watcher currently running? Running bool // InotifyDescriptor of the Watcher this WatchDescriptor belongs to InotifyDescriptor *int }
WatchDescriptor describes a path being watched
func (*WatchDescriptor) DoesPathExist ¶
func (d *WatchDescriptor) DoesPathExist() bool
DoesPathExist returns true if the path described by the descriptor exists
func (*WatchDescriptor) Start ¶
func (d *WatchDescriptor) Start() error
Start starts a WatchDescriptor inotify event watcher. If the descriptor is already running Start returns ErrDescRunning
func (*WatchDescriptor) Stop ¶
func (d *WatchDescriptor) Stop() error
Stop stops a running watch descriptor. If the descriptor is not running Stop returns ErrDescNotRunning
type Watcher ¶
type Watcher struct { sync.Mutex // The main inotify descriptor InotifyDescriptor int // Watch descriptors in this watch key: watch path -> value: WatchDescriptor Descriptors map[string]*WatchDescriptor // How many events have been read by this watcher from the inotify descriptor // This counter is incremented in ReadSingleEvent EventCount uint32 // The event channel we send all events on Events chan *FsEvent // How we report errors Errors chan error // contains filtered or unexported fields }
Watcher is the top-level object that handles EventHandlers and Watchers.
func NewWatcher ¶
NewWatcher allocates a new watcher and initializes an inotify descriptor and the w.Events and w.Error channels, so it should be ran before running descriptor.Start()
func (*Watcher) AddDescriptor ¶
func (w *Watcher) AddDescriptor(dirPath string, mask uint32) (*WatchDescriptor, error)
AddDescriptor adds a descriptor to Watcher w. The descriptor is not started.
func (*Watcher) DescriptorExists ¶
DescriptorExists returns true if a WatchDescriptor exists in Watcher w, false otherwise
func (*Watcher) GetDescriptorByPath ¶
func (w *Watcher) GetDescriptorByPath(watchPath string) *WatchDescriptor
GetDescriptorByPath searches Watcher w for a watch descriptor. Searches by WatchDescriptor's path
func (*Watcher) GetDescriptorByWatch ¶
func (w *Watcher) GetDescriptorByWatch(wd int) *WatchDescriptor
GetDescriptorByWatch searches a Watcher instance for a watch descriptor. Searches by inotify watch descriptor
func (*Watcher) GetEventCount ¶
GetEventCount returns the atomic counter tracking the count of events for this Watcher. atomic/thread-safe.
func (*Watcher) GetRunningDescriptors ¶
GetRunningDescriptors returns the count of currently running or Start()'d descriptors for this watcher.
func (*Watcher) ListDescriptors ¶
ListDescriptors returns a string array of all WatchDescriptors in w *Watcher Both started and stopped. To get a count of running watch descriptors, use GetRunningDescriptors
func (*Watcher) ReadSingleEvent ¶
ReadSingleEvent reads and returns a single event from the watch descriptor.
func (*Watcher) RecursiveAdd ¶
RecursiveAdd adds the directory at rootPath, and all directories below it, using the flags provided in mask
func (*Watcher) RegisterEventHandler ¶
func (w *Watcher) RegisterEventHandler(handle EventHandler) error
RegisterEventHandler registers an EventHandler with Watcher. The EventHandler handle will be applied to any event read by WatchAndHandle matching its mask
func (*Watcher) RemoveDescriptor ¶
RemoveDescriptor removes the WatchDescriptor with the path matching path from the watcher, and stops the inotify watcher
func (*Watcher) StopAll ¶
StopAll stops all running watch descriptors. Does not remove descriptors from the watch
func (*Watcher) UnregisterEventHandler ¶
UnregisterEventHandler Remove an EventHandle from a Watcher's EventHandle list The EventHandler handle will no longer applied to any event read by WatchAndHandle
func (*Watcher) Watch ¶
func (w *Watcher) Watch()
Watch calls ReadSingleEvent (which read-blocks) in a loop while there are running WatchDescriptors in Watcher w Writes events and errors to the channels w.Errors and w.Events
func (*Watcher) WatchAndHandle ¶
func (w *Watcher) WatchAndHandle()
WatchAndHandle calls ReadSingleEvent to read an event, passing it to getEventHandle to retrieve the correct handle for the event mask. Errors returned by the event's Handle are written to w.Errors The event is *not* written to the w.Events channel. If there is no handle registered to handle a specific event in the Watcher, WatchAndHandle immediately writes ErrNoSuchHandle to the w.Errors channel and returns. If there are no running watch descriptors, WatchAndHandle immediately writes ErrNoRunningDescriptors to w.Errors and returns. If there are no registered EventHandles in the Watcher, WatchAndHandle immediately writes ErrNoEventHandles to w.Errors and returns.