Update NewListener API

- Update NewListener API
- NewListener flags are set based on kernel version
- Update README
- Run Bug tests only when `sudo go test -v -bug` is passed

Author: opcoder0

README.md

@@ -27,7 +27,7 @@ func main() {
                 os.Exit(1)
         }
         mountPoint := "/"
-        listener, err := fanotify.NewListener(mountPoint, 4096, true)
+        listener, err := fanotify.NewListener(mountPoint)
         if err != nil {
                 fmt.Println(err)
                 os.Exit(1)
@@ -77,3 +77,19 @@ Certain flag combinations / actions cause issues with event reporting.
 - Using `fanotify.FileOpened` with any of the actions containing `OrDirectory` (`unix.FAN_ONDIR`) causes an event flood for the directory and then stopping raising any events at all.
 
 - `fanotifyFileOrDirectoryOpened` with any of the other actions causes an event flood for the directory and then stopping raising any events at all.
+
+## Tests
+
+Running tests require `CAP_SYS_ADM` privilege. To run the tests make sure to add `go` to the `sudo` PATH.
+
+The command runs all the tests except the ones that test the flag bugs mentioned in the "Known Issues" section above -
+
+```
+sudo go test -v
+```
+
+To run the tests with flag issues -
+
+```
+sudo go test -v -bug
+```

fanotify_api.go

@@ -74,27 +74,20 @@ type Listener struct {
 // `maxEvents` defines the length of the buffered channel which holds the notifications. The minimum length is 4096.
 // `withName` setting this to true populates the file name under the watched parent.
 //
+// For Linux kernel version 5.0 and earlier no additional information about the underlying filesystem object is available.
+// For Linux kernel versions 5.1 - 5.8 additional information about the underlying filesystem object is correlated to an event.
+// For Linux kernel version 5.9 or later the modified file name is made available in the event.
+//
 // NOTE that this call requires CAP_SYS_ADMIN privilege
-func NewListener(mountpointPath string, maxEvents uint, withName bool) (*Listener, error) {
+func NewListener(mountPoint string) (*Listener, error) {
 	capSysAdmin, err := checkCapSysAdmin()
 	if err != nil {
 		return nil, err
 	}
 	if !capSysAdmin {
 		return nil, ErrCapSysAdmin
 	}
-	if maxEvents < 4096 {
-		maxEvents = 4096
-	}
-	var flags, eventFlags uint
-	if withName {
-		flags = unix.FAN_CLASS_NOTIF | unix.FAN_CLOEXEC | unix.FAN_REPORT_DIR_FID | unix.FAN_REPORT_NAME
-	} else {
-		flags = unix.FAN_CLASS_NOTIF | unix.FAN_CLOEXEC | unix.FAN_REPORT_FID
-	}
-
-	eventFlags = unix.O_RDONLY | unix.O_LARGEFILE | unix.O_CLOEXEC
-	return newListener(mountpointPath, flags, eventFlags, maxEvents)
+	return newListener(mountPoint)
 }
 
 // Start starts the listener and polls the fanotify event notification group for marked events.

fanotify_event.go

@@ -191,11 +191,32 @@ func fanotifyEventOK(meta *unix.FanotifyEventMetadata, n int) bool {
 		int(meta.Event_len) <= n)
 }
 
-func newListener(mountpointPath string, flags, eventFlags, maxEvents uint) (*Listener, error) {
+func newListener(mountpointPath string) (*Listener, error) {
+
+	var flags, eventFlags uint
+
 	maj, min, _, err := kernelVersion()
 	if err != nil {
 		return nil, err
 	}
+	switch {
+	case maj < 5:
+		flags = unix.FAN_CLASS_NOTIF | unix.FAN_CLOEXEC
+	case maj == 5:
+		if min < 1 {
+			flags = unix.FAN_CLASS_NOTIF | unix.FAN_CLOEXEC
+		}
+		if min >= 1 && min < 9 {
+			flags = unix.FAN_CLASS_NOTIF | unix.FAN_CLOEXEC | unix.FAN_REPORT_FID
+		}
+		if min >= 9 {
+			flags = unix.FAN_CLASS_NOTIF | unix.FAN_CLOEXEC | unix.FAN_REPORT_DIR_FID | unix.FAN_REPORT_NAME
+		}
+	case maj > 5:
+		flags = unix.FAN_CLASS_NOTIF | unix.FAN_CLOEXEC | unix.FAN_REPORT_DIR_FID | unix.FAN_REPORT_NAME
+	}
+	eventFlags = unix.O_RDONLY | unix.O_LARGEFILE | unix.O_CLOEXEC
+
 	if err := flagsValid(flags); err != nil {
 		return nil, fmt.Errorf("%w: %v", ErrInvalidFlagCombination, err)
 	}
@@ -233,7 +254,7 @@ func newListener(mountpointPath string, flags, eventFlags, maxEvents uint) (*Lis
 			r *os.File
 			w *os.File
 		}{r, w},
-		Events: make(chan Event, maxEvents),
+		Events: make(chan Event, 4096),
 	}
 	return listener, nil
 }
@@ -340,7 +361,7 @@ func (l *Listener) readEvents() error {
 				panic("metadata structure from the kernel does not match the structure definition at compile time")
 			}
 			if metadata.Fd != unix.FAN_NOFD {
-				// no fid
+				// no fid (applicable to kernels 5.0 and earlier)
 				procFdPath := fmt.Sprintf("/proc/self/fd/%d", metadata.Fd)
 				n1, err := unix.Readlink(procFdPath, name[:])
 				if err != nil {
@@ -360,9 +381,8 @@ func (l *Listener) readEvents() error {
 					Pid:     int(metadata.Pid),
 				}
 				l.Events <- event
-
 			} else {
-				// fid
+				// fid (applicable to kernels 5.1+)
 				fid = (*fanotifyEventInfoFID)(unsafe.Pointer(&buf[i+int(metadata.Metadata_len)]))
 				withName := false
 				switch {