summaryrefslogtreecommitdiff
path: root/inotify
diff options
context:
space:
mode:
Diffstat (limited to 'inotify')
-rw-r--r--inotify/bits.go67
-rw-r--r--inotify/inotify.go47
-rw-r--r--inotify/inutil/inotify_util.go32
-rw-r--r--inotify/syscall.go42
4 files changed, 140 insertions, 48 deletions
diff --git a/inotify/bits.go b/inotify/bits.go
index eb0270f..18d8566 100644
--- a/inotify/bits.go
+++ b/inotify/bits.go
@@ -1,3 +1,24 @@
+// Copyright (C) 2015 Luke Shumaker
+//
+// Many of the comments in this file are taken from the GNU libc
+// header file <sys/inotify.h>
+//
+// Copyright (C) 2005-2015 Free Software Foundation, Inc.
+//
+// The GNU C Library is free software; you can redistribute it and/or
+// modify it under the terms of the GNU Lesser General Public
+// License as published by the Free Software Foundation; either
+// version 2.1 of the License, or (at your option) any later version.
+//
+// The GNU C Library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+// Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with the GNU C Library; if not, see
+// <http://www.gnu.org/licenses/>.
+
package inotify
const (
@@ -7,39 +28,39 @@ const (
IN_NONBLOCK int = 00004000
)
-type Fd int
-type Wd int
+type file int // File Descriptor
+type Wd int // Watch Descriptor
type Mask uint32
const (
// Supported events suitable for the `mask` parameter of Inotify.AddWatch().
- IN_ACCESS Mask = (1<< 0) // File was accessed.
- IN_MODIFY Mask = (1<< 1) // File was modified.
- IN_ATTRIB Mask = (1<< 2) // Metadata changed.
- IN_CLOSE_WRITE Mask = (1<< 3) // Writtable file was closed.
- IN_CLOSE_NOWRITE Mask = (1<< 4) // Unwrittable file closed.
- IN_OPEN Mask = (1<< 5) // File was opened.
- IN_MOVED_FROM Mask = (1<< 6) // File was moved from X.
- IN_MOVED_TO Mask = (1<< 7) // File was moved to Y.
- IN_CREATE Mask = (1<< 8) // Subfile was created.
- IN_DELETE Mask = (1<< 9) // Subfile was deleted.
- IN_DELETE_SELF Mask = (1<<10) // Self was deleted.
- IN_MOVE_SELF Mask = (1<<11) // Self was moved.
+ IN_ACCESS Mask = (1 << 0) // File was accessed.
+ IN_MODIFY Mask = (1 << 1) // File was modified.
+ IN_ATTRIB Mask = (1 << 2) // Metadata changed.
+ IN_CLOSE_WRITE Mask = (1 << 3) // Writtable file was closed.
+ IN_CLOSE_NOWRITE Mask = (1 << 4) // Unwrittable file closed.
+ IN_OPEN Mask = (1 << 5) // File was opened.
+ IN_MOVED_FROM Mask = (1 << 6) // File was moved from X.
+ IN_MOVED_TO Mask = (1 << 7) // File was moved to Y.
+ IN_CREATE Mask = (1 << 8) // Subfile was created.
+ IN_DELETE Mask = (1 << 9) // Subfile was deleted.
+ IN_DELETE_SELF Mask = (1 << 10) // Self was deleted.
+ IN_MOVE_SELF Mask = (1 << 11) // Self was moved.
// Events that appear in output without subscribing to them.
- IN_UNMOUNT Mask = (1<<13) // Backing fs was unmounted.
- IN_Q_OVERFLOW Mask = (1<<14) // Event queued overflowed.
- IN_IGNORED Mask = (1<<15) // File was ignored (expect no more events).
+ IN_UNMOUNT Mask = (1 << 13) // Backing fs was unmounted.
+ IN_Q_OVERFLOW Mask = (1 << 14) // Event queued overflowed.
+ IN_IGNORED Mask = (1 << 15) // File was ignored (expect no more events).
// Special flags that you may pass to Inotify.AddWatch()...
// except for IN_ISDIR, which is a flag that is set on output events.
- IN_ONLYDIR Mask = (1<<24) // Only watch the path if it is a directory.
- IN_DONT_FOLLOW Mask = (1<<25) // Do not follow a sym link.
- IN_EXCL_UNLINK Mask = (1<<26) // Exclude events on unlinked objects.
- IN_MASK_ADD Mask = (1<<29) // Add to the mask of an already existing watch.
- IN_ISDIR Mask = (1<<30) // Event occurred against dir.
- IN_ONESHOT Mask = (1<<31) // Only send event once.
+ IN_ONLYDIR Mask = (1 << 24) // Only watch the path if it is a directory.
+ IN_DONT_FOLLOW Mask = (1 << 25) // Do not follow a sym link.
+ IN_EXCL_UNLINK Mask = (1 << 26) // Exclude events on unlinked objects.
+ IN_MASK_ADD Mask = (1 << 29) // Add to the mask of an already existing watch.
+ IN_ISDIR Mask = (1 << 30) // Event occurred against dir.
+ IN_ONESHOT Mask = (1 << 31) // Only send event once.
// Convenience macros */
IN_CLOSE Mask = (IN_CLOSE_WRITE | IN_CLOSE_NOWRITE) // Close.
diff --git a/inotify/inotify.go b/inotify/inotify.go
index 0d67b44..2fd3a83 100644
--- a/inotify/inotify.go
+++ b/inotify/inotify.go
@@ -1,3 +1,21 @@
+// Copyright 2015 Luke Shumaker <lukeshu@sbcglobal.net>.
+//
+// This is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License as
+// published by the Free Software Foundation; either version 2.1 of the
+// License, or (at your option) any later version.
+//
+// This software is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this manual; if not, see
+// <http://www.gnu.org/licenses/>.
+
+// Package inotify provides an interface to the Linux inotify system.
+// The inotify system is a mechanism for monitoring filesystem events.
package inotify
import (
@@ -7,7 +25,7 @@ import (
)
type Inotify struct {
- fd Fd
+ fd file
fdLock sync.RWMutex
buffFull [4096]byte
buff []byte
@@ -15,12 +33,14 @@ type Inotify struct {
}
type Event struct {
- Wd Wd /* Watch descriptor */
- Mask Mask /* Mask describing event */
- Cookie uint32 /* Unique cookie associating related events (for rename(2)) */
- Name *string /* Optional name */
+ Wd Wd // Watch descriptor
+ Mask Mask // Mask describing event
+ Cookie uint32 // Unique cookie associating related events (for rename(2))
+ Name *string // Optional name
}
+// Create an inotify instance. The variant InotifyInit1() allows
+// flags to access extra functionality.
func InotifyInit() (*Inotify, error) {
fd, err := inotify_init()
o := Inotify{
@@ -30,6 +50,8 @@ func InotifyInit() (*Inotify, error) {
return &o, err
}
+// Create an inotify instance, with flags specifying extra
+// functionality.
func InotifyInit1(flags int) (*Inotify, error) {
fd, err := inotify_init1(flags)
o := Inotify{
@@ -39,18 +61,29 @@ func InotifyInit1(flags int) (*Inotify, error) {
return &o, err
}
+// Add a watch to the inotify instance, or modifies an existing watch
+// item.
func (o *Inotify) AddWatch(path string, mask Mask) (Wd, error) {
o.fdLock.RLock()
defer o.fdLock.RUnlock()
return inotify_add_watch(o.fd, path, mask)
}
+// Remove a watch from the inotify instance.
func (o *Inotify) RmWatch(wd Wd) error {
o.fdLock.RLock()
defer o.fdLock.RUnlock()
return inotify_rm_watch(o.fd, wd)
}
+// Close the inotify instance; further calls to this object will
+// error.
+//
+// Events recieved before Close() is called may still be Read() after
+// the call to Close().
+//
+// Beware that if Close() is called while waiting on Read(), it will
+// block until events are read.
func (o *Inotify) Close() error {
o.fdLock.Lock()
defer o.fdLock.Unlock()
@@ -58,6 +91,10 @@ func (o *Inotify) Close() error {
return sysclose(o.fd)
}
+// Read an event from the inotify instance.
+//
+// Events recieved before Close() is called may still be Read() after
+// the call to Close().
func (o *Inotify) Read() (Event, error) {
o.buffLock.Lock()
defer o.buffLock.Unlock()
diff --git a/inotify/inutil/inotify_util.go b/inotify/inutil/inotify_util.go
index 3a5eed5..c643e59 100644
--- a/inotify/inutil/inotify_util.go
+++ b/inotify/inutil/inotify_util.go
@@ -1,3 +1,20 @@
+// Copyright 2015 Luke Shumaker <lukeshu@sbcglobal.net>.
+//
+// This is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License as
+// published by the Free Software Foundation; either version 2.1 of
+// the License, or (at your option) any later version.
+//
+// This software is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this manual; if not, see
+// <http://www.gnu.org/licenses/>.
+
+// Package inutil provides a channel-based interface to inotify.
package inutil
import (
@@ -6,25 +23,21 @@ import (
"syscall"
)
-const (
- // Flags for the parameter of InotifyInit1().
- // These, oddly, appear to be 24-bit numbers.
- IN_CLOEXEC = inotify.IN_CLOEXEC
-)
-
type Watcher struct {
Events <-chan inotify.Event
- events chan<- inotify.Event
Errors <-chan error
+ events chan<- inotify.Event
errors chan<- error
in *inotify.Inotify
}
+// Wraps inotify.InotifyInit()
func WatcherInit() (*Watcher, error) {
in, err := inotify.InotifyInit()
return newWatcher(in, err)
}
+// Wraps inotify.InotifyInit1()
func WatcherInit1(flags int) (*Watcher, error) {
in, err := inotify.InotifyInit1(flags &^ inotify.IN_NONBLOCK)
return newWatcher(in, err)
@@ -44,14 +57,19 @@ func newWatcher(in *inotify.Inotify, err error) (*Watcher, error) {
return o, err
}
+// Wraps inotify.Inotify.AddWatch(); adds or modifies a watch.
func (o *Watcher) AddWatch(path string, mask inotify.Mask) (inotify.Wd, error) {
return o.in.AddWatch(path, mask)
}
+// Wraps inotify.Inotify.RmWatch(); removes a watch.
func (o *Watcher) RmWatch(wd inotify.Wd) error {
return o.in.RmWatch(wd)
}
+// Wraps inotify.Inotify.Close(). Unlike inotify.Inotify.Close(),
+// this cannot block. Also unlike inotify.Inotify.Close(), nothing
+// may be received from the channel after this is called.
func (o *Watcher) Close() {
func() {
defer recover()
diff --git a/inotify/syscall.go b/inotify/syscall.go
index 721a10a..d1b5140 100644
--- a/inotify/syscall.go
+++ b/inotify/syscall.go
@@ -1,3 +1,19 @@
+// Copyright 2015 Luke Shumaker <lukeshu@sbcglobal.net>.
+//
+// This is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License as
+// published by the Free Software Foundation; either version 2.1 of
+// the License, or (at your option) any later version.
+//
+// This software is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this manual; if not, see
+// <http://www.gnu.org/licenses/>.
+
package inotify
import (
@@ -12,27 +28,27 @@ func newPathError(op string, path string, err error) error {
return &os.PathError{Op: op, Path: path, Err: err}
}
-/* Create and initialize inotify instance. */
-func inotify_init() (Fd, error) {
+// Create and initialize inotify instance.
+func inotify_init() (file, error) {
fd, errno := syscall.InotifyInit()
- return Fd(fd), os.NewSyscallError("inotify_init", errno)
+ return file(fd), os.NewSyscallError("inotify_init", errno)
}
-/* Create and initialize inotify instance. */
-func inotify_init1(flags int) (Fd, error) {
+// Create and initialize inotify instance.
+func inotify_init1(flags int) (file, error) {
fd, errno := syscall.InotifyInit1(flags)
- return Fd(fd), os.NewSyscallError("inotify_init1", errno)
+ return file(fd), os.NewSyscallError("inotify_init1", errno)
}
-/* Add watch of object NAME to inotify instance FD. Notify about
- events specified by MASK. */
-func inotify_add_watch(fd Fd, name string, mask Mask) (Wd, error) {
+// Add watch of object NAME to inotify instance FD. Notify about
+// events specified by MASK.
+func inotify_add_watch(fd file, name string, mask Mask) (Wd, error) {
wd, errno := syscall.InotifyAddWatch(int(fd), name, uint32(mask))
return Wd(wd), newPathError("inotify_add_watch", name, errno)
}
-/* Remove the watch specified by WD from the inotify instance FD. */
-func inotify_rm_watch(fd Fd, wd Wd) error {
+// Remove the watch specified by WD from the inotify instance FD.
+func inotify_rm_watch(fd file, wd Wd) error {
success, errno := syscall.InotifyRmWatch(int(fd), uint32(wd))
switch success {
case -1:
@@ -49,11 +65,11 @@ func inotify_rm_watch(fd Fd, wd Wd) error {
panic("should never happen")
}
-func sysclose(fd Fd) error {
+func sysclose(fd file) error {
return os.NewSyscallError("close", syscall.Close(int(fd)))
}
-func sysread(fd Fd, p []byte) (int, error) {
+func sysread(fd file, p []byte) (int, error) {
n, err := syscall.Read(int(fd), p)
return n, os.NewSyscallError("read", err)
}