From 5d29d4c39d1c082535410510be6c54e349e1e3a7 Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Fri, 18 Sep 2015 17:45:34 -0400 Subject: Massive documentation and copyright clean-up. --- inotify/bits.go | 67 +++++++++++++++++++++++++++--------------- inotify/inotify.go | 47 +++++++++++++++++++++++++---- inotify/inutil/inotify_util.go | 32 +++++++++++++++----- inotify/syscall.go | 42 ++++++++++++++++++-------- 4 files changed, 140 insertions(+), 48 deletions(-) (limited to 'inotify') 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 +// +// 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 +// . + 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 . +// +// 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 +// . + +// 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 . +// +// 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 +// . + +// 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 . +// +// 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 +// . + 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) } -- cgit v1.2.3