fswatch

README

go-fswatch: Go bindings for libfswatch

Go bindings for libfswatch.

libfswatch provides comprehensive, cross-platform file change monitoring capabilities.

Features

go-fswatch exposes all features provided by fswatch and libfswatch through an idiomatic Go API:

• cross-platform: inotify (Linux), FSEvents (macOS), Windows, kqueue (*BSD), File Events Notification (Solaris) and polling
• watch files and directories
• recursive watching
• file and directory filtering (using regular expressions)
• events filtering

Install

First, install libfswatch:

1. Download the latest release (fswatch-<version>.tar.gz)
2. Compile and install libfswatch:

tar xzf fswatch-*.tar.gz
cd fswatch-*
./configure
make
sudo make install

Then, you can use this Go module as usual:

go get github.com/dunglas/go-fswatch

Usage and Examples

See the documentation.

Cgo

This package depends on cgo. If you are looking for non-cgo alternatives, see:

• fsnotify (doesn't support FSEvents nor polling)
• notify (doesn't support include/exclude filters)

Credits

Created by Kévin Dunglas and sponsored by Les-Tilleuls.coop.

Documentation

Overview

Package fswatch provides bindings for libfswatch.

Example

s, err := fswatch.NewSession([]string{"/tmp"}, func(e []fswatch.Event) {
	fmt.Printf("%s", filepath.Base(e[0].Path))
})
if err != nil {
	panic(err)
}

// Start() is blocking, it must be called in a dedicated goroutine
go func() {
	if err := s.Start(); err != nil {
		panic(err)
	}
}()

// Give some time to the monitor to start, this is a limitation of the underlying C library
time.Sleep(5 * time.Second)

f, err := os.Create("/tmp/foo.txt")
if err != nil {
	panic(err)
}
defer f.Close()

if err := s.Stop(); err != nil {
	panic(err)
}
// Give some time to the monitor to stop, this is a limitation of the underlying C library
time.Sleep(3 * time.Second)

if err := s.Destroy(); err != nil {
	panic(err)
}

Output:

foo.txt

Index

• Constants
• Variables
• type Callback
• type Event
• type EventType
• type Filter
• type FilterType
• type MonitorType
• type Option
  • func WithAllowOverflow(allowOverflow bool) Option
  • func WithDirectoryOnly(directoryOnly bool) Option
  • func WithEventTypeFilters(eventTypes []EventType) Option
  • func WithFilters(filters []Filter) Option
  • func WithFollowSymlinks(followSymlinks bool) Option
  • func WithLatency(latency float64) Option
  • func WithMonitorType(monitorType MonitorType) Option
  • func WithProperties(properties map[string]string) Option
  • func WithRecursive(recursive bool) Option
• type Session
  • func NewSession(paths []string, c Callback, options ...Option) (*Session, error)
  • func (s *Session) Destroy() error
  • func (s *Session) Start() error
  • func (s *Session) Stop() error

Examples

• Package

Constants

const (
	/* System default */
	SystemDefaultMonitor MonitorType = C.system_default_monitor_type
	/* macOS FSEvents */
	FseventsMonitor = C.fsevents_monitor_type
	/* BSD `kqueue` */
	KqueueMonitor = C.kqueue_monitor_type
	/* Linux `inotify` */
	InotifyMonitor = C.inotify_monitor_type
	/* Windows */
	WindowsMonitor = C.windows_monitor_type
	/* `stat()`-based poll  */
	PollMonitor = C.poll_monitor_type
	/* Solaris/Illumos */
	FenMonitor = C.fen_monitor_type
)

Variables

var (
	UnknownError               = errors.New("an unknown error has occurred")
	SessionUnknownError        = errors.New("the session specified by the handle is unknown")
	MonitorAlreadyExistsError  = errors.New("the session already contains a monitor")
	MemoryError                = errors.New("an error occurred while invoking a memory management routine")
	UnknownMonitorTypeError    = errors.New("the specified monitor type does not exist")
	CallbackNotSetError        = errors.New("the callback has not been set")
	PathsNotSetError           = errors.New("the paths to watch have not been set")
	MissingContextError        = errors.New("the callback context has not been set")
	InvalidPathError           = errors.New("the path is invalid")
	InvalidCallbackError       = errors.New("the callback is invalid")
	InvalidLatencyError        = errors.New("the latency is invalid")
	InvalidRegexError          = errors.New("the regular expression is invalid")
	MonitorAlreadyRunningError = errors.New("a monitor is already running in the specified session")
	UnknownValueError          = errors.New("the value is unknown")
	InvalidPropertyError       = errors.New("the property is invalid")
)

Types

type Callback

type Callback func([]Event)

type Event

type Event struct {
	Path  string
	Time  time.Time
	Types []EventType
}

type EventType

type EventType C.enum_fsw_event_flag

var (
	/* No event has occurred. */
	NoOp EventType = C.NoOp
	/* Platform-specific placeholder for event type that cannot currently be mapped. */
	PlatformSpecific EventType = C.PlatformSpecific
	/* An object was created. */
	Created EventType = C.Created
	/* An object was updated. */
	Updated EventType = C.Updated
	/* An object was removed. */
	Removed EventType = C.Removed
	/* An object was renamed. */
	Renamed EventType = C.Renamed
	/* The owner of an object was modified. */
	OwnerModified EventType = C.OwnerModified
	/* The attributes of an object were modified. */
	AttributeModified EventType = C.AttributeModified
	/* An object was moved from this location. */
	MovedFrom EventType = C.MovedFrom
	/* An object was moved to this location. */
	MovedTo EventType = C.MovedTo
	/* The object is a file. */
	IsFile EventType = C.IsFile
	/* The object is a directory. */
	IsDir EventType = C.IsDir
	/* The object is a symbolic link. */
	IsSymLink EventType = C.IsSymLink
	/* The link count of an object has changed. */
	Link EventType = C.Link
	/* The event queue has overflowed. */
	Overflow EventType = C.Overflow
)

type Filter

type Filter struct {
	// POSIX regular expression used to match the paths (see https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html).
	Text       string
	FilterType FilterType
	// Indicates if the regular expression is case sensitive or not.
	CaseSensitive bool
	// Indicates if the regular exoression is an extended regular expression or not (see https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04).
	Extended bool
}

type FilterType

type FilterType C.enum_fsw_filter_type

var (
	FilterInclude FilterType = C.filter_include
	FilterExclude FilterType = C.filter_exclude
)

type MonitorType

type MonitorType C.enum_fsw_monitor_type

type Option

type Option func(h *opt) error

Option instances allow to configure monitors.

func WithAllowOverflow

func WithAllowOverflow(allowOverflow bool) Option

func WithDirectoryOnly

func WithDirectoryOnly(directoryOnly bool) Option

func WithEventTypeFilters

func WithEventTypeFilters(eventTypes []EventType) Option

func WithFilters

func WithFilters(filters []Filter) Option

func WithFollowSymlinks

func WithFollowSymlinks(followSymlinks bool) Option

func WithLatency

func WithLatency(latency float64) Option

func WithMonitorType

func WithMonitorType(monitorType MonitorType) Option

func WithProperties

func WithProperties(properties map[string]string) Option

func WithRecursive

func WithRecursive(recursive bool) Option

type Session

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

func NewSession

func NewSession(paths []string, c Callback, options ...Option) (*Session, error)

NewSession creates a new monitor session.

At least one path must be passed. The callback is invoked when the monitor receives change events satisfying all the session criteria.

func (*Session) Destroy

func (s *Session) Destroy() error

Destroy frees allocated system resources. It must be called when the session is not used anymore.

func (*Session) Start

func (s *Session) Start() error

Start starts the monitor. Start must be called in a dedicated goroutine. Depending on the type of monitor this call might return when a monitor is stopped or not.

func (*Session) Stop

func (s *Session) Stop() error

Stop stops a running monitor.