gonotify

README

Gonotify

Simple Golang inotify wrapper.

Provides following primitives:

• Low level

  • Inotify - wrapper around inotify(7)
  • InotifyEvent - generated file/folder event. Contains Name (full path), watch descriptior and Mask that describes the event.

• Higher level

  • FileWatcher - higher level utility, helps to watch the list of files for changes, creation or removal
  • DirWatcher - higher level utility, recursively watches given root folder for added, removed or changed files.
  • FileEvent - embeds InotifyEvent and keeps additional field Eof to notify user that there will be no more events.

Use FileWatcher and DirWatcher as an example and build your own utility classes.

License

MIT. See LICENSE file for more details.

Documentation

Index

• Constants
• func InMaskToString(in_mask uint32) string
• type DirWatcher
  • func NewDirWatcher(fileMask uint32, root string) (*DirWatcher, error)
  • func (d *DirWatcher) Close()
• type FileEvent
• type FileWatcher
  • func NewFileWatcher(mask uint32, files ...string) (*FileWatcher, error)
  • func (f *FileWatcher) Close()
• type Inotify
  • func NewInotify() (*Inotify, error)
  • func (i *Inotify) AddWatch(pathName string, mask uint32) error
  • func (i *Inotify) Close() error
  • func (i *Inotify) Read() ([]InotifyEvent, error)
  • func (i *Inotify) RmWatch(pathName string) error
  • func (i *Inotify) RmWd(wd uint32) error
• type InotifyEvent
  • func (i InotifyEvent) GoString() string
  • func (i InotifyEvent) String() string

Constants

const (
	IN_ACCESS        = uint32(syscall.IN_ACCESS)        // File was accessed
	IN_ATTRIB        = uint32(syscall.IN_ATTRIB)        // Metadata changed
	IN_CLOSE_WRITE   = uint32(syscall.IN_CLOSE_WRITE)   // File opened for writing was closed.
	IN_CLOSE_NOWRITE = uint32(syscall.IN_CLOSE_NOWRITE) // File or directory not opened for writing was closed.
	IN_CREATE        = uint32(syscall.IN_CREATE)        // File/directory created in watched directory
	IN_DELETE        = uint32(syscall.IN_DELETE)        // File/directory deleted from watched directory.
	IN_DELETE_SELF   = uint32(syscall.IN_DELETE_SELF)   // Watched file/directory was itself deleted.
	IN_MODIFY        = uint32(syscall.IN_MODIFY)        // File was modified
	IN_MOVE_SELF     = uint32(syscall.IN_MOVE_SELF)     // Watched file/directory was itself moved.
	IN_MOVED_FROM    = uint32(syscall.IN_MOVED_FROM)    // Generated for the directory containing the old filename when a file is renamed.
	IN_MOVED_TO      = uint32(syscall.IN_MOVED_TO)      // Generated for the directory containing the new filename when a file is renamed.
	IN_OPEN          = uint32(syscall.IN_OPEN)          // File or directory was opened.

	IN_ALL_EVENTS = uint32(syscall.IN_ALL_EVENTS) // bit mask of all of the above events.
	IN_MOVE       = uint32(syscall.IN_MOVE)       // Equates to IN_MOVED_FROM | IN_MOVED_TO.
	IN_CLOSE      = uint32(syscall.IN_CLOSE)      // Equates to IN_CLOSE_WRITE | IN_CLOSE_NOWRITE.

	IN_DONT_FOLLOW = uint32(syscall.IN_DONT_FOLLOW) // Don't dereference pathname if it is a symbolic link.
	IN_EXCL_UNLINK = uint32(syscall.IN_EXCL_UNLINK) // Don't generate events for children if they have been unlinked from the directory.
	IN_MASK_ADD    = uint32(syscall.IN_MASK_ADD)    // Add (OR) the events in mask to the watch mask
	IN_ONESHOT     = uint32(syscall.IN_ONESHOT)     // Monitor the filesystem object corresponding to pathname for one event, then remove from watch list.
	IN_ONLYDIR     = uint32(syscall.IN_ONLYDIR)     // Watch pathname only if it is a directory.

	IN_IGNORED    = uint32(syscall.IN_IGNORED)    // Watch was removed explicitly or automatically
	IN_ISDIR      = uint32(syscall.IN_ISDIR)      // Subject of this event is a directory.
	IN_Q_OVERFLOW = uint32(syscall.IN_Q_OVERFLOW) // Event queue overflowed (wd is -1 for this event).

	IN_UNMOUNT = uint32(syscall.IN_UNMOUNT) // Filesystem containing watched object was unmounted.
)

Functions

func InMaskToString

func InMaskToString(in_mask uint32) string

Types

type DirWatcher

type DirWatcher struct {
	C chan FileEvent
	// contains filtered or unexported fields
}

DirWatcher recursively watches the given root folder, waiting for file events. Events can be masked by providing fileMask. DirWatcher does not generate events for folders or subfolders.

func NewDirWatcher

func NewDirWatcher(fileMask uint32, root string) (*DirWatcher, error)

NewDirWatcher creates DirWatcher recursively waiting for events in the given root folder and emitting FileEvents in channel C, that correspond to fileMask. Folder events are ignored (having IN_ISDIR set to 1)

func (*DirWatcher) Close

func (d *DirWatcher) Close()

type FileEvent

type FileEvent struct {
	InotifyEvent
	Eof bool
}

FileEvent is the wrapper around InotifyEvent with additional Eof marker. Reading from FileEvents from DirWatcher.C or FileWatcher.C may end with Eof when underlying inotify is closed

type FileWatcher

type FileWatcher struct {
	C chan FileEvent
	// contains filtered or unexported fields
}

FileWatcher waits for events generated by filesystem for a specific list of file paths, including IN_CREATE for not yet existing files and IN_DELETE for removed.

func NewFileWatcher

func NewFileWatcher(mask uint32, files ...string) (*FileWatcher, error)

NewFileWatcher creates FileWatcher with provided inotify mask and list of files to wait events for.

func (*FileWatcher) Close

func (f *FileWatcher) Close()

type Inotify

type Inotify struct {
	// contains filtered or unexported fields
}

Inotify is the low level wrapper around inotify_init(), inotify_add_watch() and inotify_rm_watch()

func NewInotify

func NewInotify() (*Inotify, error)

NewInotify creates new inotify instance

func (*Inotify) AddWatch

func (i *Inotify) AddWatch(pathName string, mask uint32) error

AddWatch adds given path to list of watched files / folders

func (*Inotify) Close

func (i *Inotify) Close() error

Close should be called when inotify is no longer needed in order to cleanup used resources.

func (*Inotify) Read

func (i *Inotify) Read() ([]InotifyEvent, error)

Read reads portion of InotifyEvents and may fail with an error

func (*Inotify) RmWatch

func (i *Inotify) RmWatch(pathName string) error

RmWatch removes watch by pathName

func (*Inotify) RmWd

func (i *Inotify) RmWd(wd uint32) error

RmWd removes watch by watch descriptor

type InotifyEvent

type InotifyEvent struct {
	// Watch descriptor
	Wd uint32
	// File or directory name
	Name string
	// Contains bits that describe the event that occurred
	Mask uint32
	// Usually 0, but if events (like IN_MOVED_FROM and IN_MOVED_TO) are linked then they will have equal cookie
	Cookie uint32
}

InotifyEvent is the go representation of inotify_event found in sys/inotify.h

func (InotifyEvent) GoString

func (i InotifyEvent) GoString() string

func (InotifyEvent) String

func (i InotifyEvent) String() string