Implement SunOS FileSystemWatcher using portfs event ports by gwr · Pull Request #124716 · dotnet/runtime

gwr · 2026-02-22T01:54:47Z

This implementation uses SunOS portfs (event ports) to watch for directory changes. Unlike Linux inotify, portfs can only detect WHEN a directory changes, not WHAT changed. Therefore, this implementation:

Maintains a snapshot of each watched directory's contents
When portfs signals a change, re-reads the directory
Compares new vs old snapshots to detect creates/deletes/modifications
Generates appropriate FileSystemWatcher events

Key implementation details:

Uses pinned GC.AllocateArray for file_obj structures required by portfs
When watching attributes or timestamps watches directory contents too
Each watched objct gets a unique cookie for identification
port_get returns the cookie to indicate which object changed
Optimized snapshot comparison with sorted single-pass algorithm
Supports IncludeSubdirectories by recursively watching child directories
Track mtime of the watched directory to avoid missing changes
Implement graceful cancellation using PortSend

Native changes (pal_io.c):

SystemNative_PortCreate: Opens event port file descriptor
SystemNative_PortAssociate: Associates directory with port using file_obj
SystemNative_PortGet: Waits for events, returns cookie identifying directory
SystemNative_PortSend: Send an event (used in cancellation)
SystemNative_PortDissociate: Removes directory association

Performance notes:

Less efficient than inotify (must re-read directories on each change)
Better than polling (blocks until change occurs)
Memory overhead for directory snapshots

Passes all System.IO.FileSystem.Watcher.Tests

dotnet-policy-service · 2026-02-22T01:55:50Z

Tagging subscribers to this area: @dotnet/area-system-io
See info in area-owners.md if you want to be subscribed.

Copilot

Pull request overview

This PR implements FileSystemWatcher support for SunOS (Solaris/illumos) using the portfs (event ports) API. Unlike Linux's inotify which reports specific file changes, portfs only signals that a directory has changed, requiring the implementation to maintain snapshots and perform comparisons to determine what actually changed.

Changes:

Native interop layer for portfs operations (port_create, port_associate, port_get, port_send, port_dissociate)
SunOS-specific FileSystemWatcher implementation using snapshot-based change detection
Hybrid monitoring mode that watches both directories (for name changes) and individual files (for attribute changes)
Support for recursive subdirectory monitoring with resource limits (50 subdirs, 1000 files per directory)

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 18 comments.

Show a summary per file

File	Description
src/native/libs/configure.cmake	CMake configuration for portfs feature detection (has critical bug)
src/native/libs/System.Native/pal_io.h	Header declarations for portfs native functions (has spelling errors)
src/native/libs/System.Native/pal_io.c	Native implementation of portfs wrapper functions (has critical string lifetime bug)
src/native/libs/System.Native/entrypoints.c	Export table entries for new portfs functions
src/native/libs/Common/pal_config.h.in	Configuration flag for HAVE_SUNOS_PORTFS
src/libraries/System.IO.FileSystem.Watcher/tests/System.IO.FileSystem.Watcher.Tests.csproj	Added illumos and solaris to test target frameworks
src/libraries/System.IO.FileSystem.Watcher/src/System/IO/FileSystemWatcher.SunOS.cs	Main SunOS implementation with snapshot comparison and event generation (multiple issues)
src/libraries/System.IO.FileSystem.Watcher/src/System.IO.FileSystem.Watcher.csproj	Added SunOS-specific source files and target frameworks
src/libraries/Common/src/Interop/SunOS/portfs/Interop.portfs.cs	Managed P/Invoke declarations for portfs (has hardcoded struct size issue)

src/libraries/System.IO.FileSystem.Watcher/src/System/IO/FileSystemWatcher.SunOS.cs

src/libraries/Common/src/Interop/SunOS/portfs/Interop.portfs.cs

src/libraries/System.IO.FileSystem.Watcher/src/System/IO/FileSystemWatcher.SunOS.cs

src/native/libs/System.Native/pal_io.h

src/libraries/System.IO.FileSystem.Watcher/src/System/IO/FileSystemWatcher.SunOS.cs

src/native/libs/System.Native/pal_io.c

src/libraries/System.IO.FileSystem.Watcher/src/System/IO/FileSystemWatcher.SunOS.cs

Copilot

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 13 comments.

src/libraries/System.IO.FileSystem.Watcher/src/System/IO/FileSystemWatcher.SunOS.cs

src/native/libs/System.Native/pal_io.c

src/libraries/System.IO.FileSystem.Watcher/src/System/IO/FileSystemWatcher.SunOS.cs

src/native/libs/configure.cmake

Copilot

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 10 comments.

src/libraries/System.IO.FileSystem.Watcher/src/System/IO/FileSystemWatcher.SunOS.cs

src/native/libs/System.Native/pal_io.c

src/libraries/System.IO.FileSystem.Watcher/src/System/IO/FileSystemWatcher.SunOS.cs

src/native/libs/System.Native/pal_io.h

src/libraries/Common/src/Interop/SunOS/portfs/Interop.portfs.cs

src/libraries/System.IO.FileSystem.Watcher/src/System/IO/FileSystemWatcher.SunOS.cs

src/native/libs/configure.cmake

src/libraries/Common/src/Interop/SunOS/portfs/Interop.portfs.cs

Copilot

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 5 comments.

src/libraries/System.IO.FileSystem.Watcher/src/System/IO/FileSystemWatcher.SunOS.cs

Copilot

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 5 comments.

src/native/libs/System.Native/pal_io.c

src/libraries/Common/src/Interop/SunOS/portfs/Interop.portfs.cs

src/libraries/System.IO.FileSystem.Watcher/src/System/IO/FileSystemWatcher.SunOS.cs

Copilot

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

src/libraries/System.IO.FileSystem.Watcher/src/System/IO/FileSystemWatcher.SunOS.cs

github.com/dotnet/pull/124716#discussion_r2838494096

gwr · 2026-02-22T22:08:56Z

Now that I seem to be caught-up with Copilot feedback, I've squashed so I can more easily cherry pick this into a local branch with other necessary fixes so I can re-test.

am11 · 2026-02-22T23:05:14Z

@tmds, could you please take a look?

Portfs is a generic I/O eventing facility in SunOS-like platforms: port_create(3C) - https://smartos.org/man/3c/port_create. I might be mistaken, but regarding time complexity: with your recent Linux inotify overhaul, the kernel:userland path is essentially O(1). On illumos/Solaris, this implemention's kernel:userland portion is O(n log n) due to the snapshot comparison required to reconstruct file-level changes. This complexity is probably unavoidable given the lack of per-file events, but (perhaps?) still better than not having any watcher support.

Copilot

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 5 comments.

src/libraries/System.IO.FileSystem.Watcher/src/System/IO/FileSystemWatcher.SunOS.cs

Copilot

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 5 comments.

src/libraries/System.IO.FileSystem.Watcher/src/System/IO/FileSystemWatcher.SunOS.cs

src/native/libs/System.Native/pal_io.c

src/native/libs/System.Native/pal_io.h

src/libraries/System.IO.FileSystem.Watcher/src/System/IO/FileSystemWatcher.SunOS.cs

Copilot

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 4 comments.

src/libraries/System.IO.FileSystem.Watcher/src/System/IO/FileSystemWatcher.SunOS.cs

src/native/libs/System.Native/pal_io.h

src/libraries/System.IO.FileSystem.Watcher/src/System/IO/FileSystemWatcher.SunOS.cs

This implementation uses SunOS portfs (event ports) to watch for directory changes. Unlike Linux inotify, portfs can only detect WHEN a directory changes, not WHAT changed. Therefore, this implementation: 1. Maintains a snapshot of each watched directory's contents 2. When portfs signals a change, re-reads the directory 3. Compares new vs old snapshots to detect creates/deletes/modifications 4. Generates appropriate FileSystemWatcher events Key implementation details: - Uses pinned GC.AllocateArray for file_obj structures required by portfs - When watching attributes or timestamps watches directory contents too - Each watched objct gets a unique cookie for identification - port_get returns the cookie to indicate which object changed - Optimized snapshot comparison with sorted single-pass algorithm - Supports IncludeSubdirectories by recursively watching child directories - Track mtime of the watched directory to avoid missing changes - Implement graceful cancellation using PortSend Native changes (pal_io.c): - SystemNative_PortCreate: Opens event port file descriptor - SystemNative_PortAssociate: Associates directory with port using file_obj - SystemNative_PortGet: Waits for events, returns cookie identifying directory - SystemNative_PortSend: Send an event (used in cancellation) - SystemNative_PortDissociate: Removes directory association Performance notes: - Less efficient than inotify (must re-read directories on each change) - Better than polling (blocks until change occurs) - Memory overhead for directory snapshots Passes 99% of System.IO.FileSystem.Watcher.Tests --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

gwr · 2026-02-23T15:17:16Z

Squashed the last dozen updates to simplify local testing.

gwr · 2026-02-26T14:56:02Z

Can anyone help me interpret the CI build analysis?
Is there anything there I need to fix?

gwr · 2026-03-02T22:00:52Z

src/native/libs/System.Native/pal_io.c

BTW, I wondered if I should add functions like this to pal_io.c or create a new pal_portfs.c or pal_sunos.c or something for the SunOS-specific additions. Guidance? Thanks.

gwr · 2026-03-03T02:11:55Z

Still needs a reviewer. Thanks.

am11 · 2026-03-03T12:44:20Z

To me it looks good. I had a question from @tmds about the overhead #124716 (comment). If the plan is to switch to inotify in the future when it gets stable upstream, we can treat it as a stopgap and merge this. Thanks for pushing it forward @gwr!

gwr · 2026-03-03T14:12:57Z

The only test failure is name="System.IO.Tests.FileSystemWatcherTests_netstandard17.EndInit_ResumesPausedEnableRaisingEvents(setBeforeBeginInit: False)" which has active issue #103584 so I think that's OK.

tmds · 2026-03-03T15:47:04Z

This complexity is probably unavoidable given the lack of per-file events, but (perhaps?) still better than not having any watcher support.

It sounds like it is implemented as good as the kernel allows.

Without this, it's likely an app is broken in some way, so I also consider it better to have this than to throw PNSE.

src/libraries/System.IO.FileSystem.Watcher/src/System/IO/FileSystemWatcher.SunOS.cs

Copilot

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 9 comments.

src/libraries/System.IO.FileSystem.Watcher/src/System/IO/FileSystemWatcher.SunOS.cs

Copilot · 2026-03-05T02:21:39Z

src/libraries/System.IO.FileSystem.Watcher/src/System/IO/FileSystemWatcher.SunOS.cs

+                foreach (var (name, watch) in _nameToWatchMap)
+                {
+                    unsafe


foreach (var (name, watch) in _nameToWatchMap) doesn't use name. With TreatWarningsAsErrors=true, this unused deconstruction local will fail the build. Iterate _nameToWatchMap.Values (or similar) to avoid declaring an unused variable.

Copilot · 2026-03-05T02:21:39Z

src/libraries/System.IO.FileSystem.Watcher/src/System/IO/FileSystemWatcher.SunOS.cs

+                // FileName/DirectoryName: detect when entries are added/removed
+                if ((filters & (NotifyFilters.FileName | NotifyFilters.DirectoryName)) != 0)
+                    mask |= (int)Interop.PortFs.PortEvent.FILE_MODIFIED;
+
+                // LastWrite/Size: detect content/size changes
+                if ((filters & (NotifyFilters.LastWrite | NotifyFilters.Size)) != 0)
+                {
+                    mask |= (int)Interop.PortFs.PortEvent.FILE_MODIFIED;
+                    mask |= (int)Interop.PortFs.PortEvent.FILE_TRUNC;
+                }


GetPortEventMask adds FILE_MODIFIED when NotifyFilters.FileName/DirectoryName are set. That makes sense for the directory association (detect entry add/remove), but when this same mask is used for individual file associations it can cause spurious Changed events for content/mtime updates even if the user didn't request LastWrite/Size. Consider using separate masks for directory-vs-file associations (or only enabling FILE_MODIFIED for per-file watches when LastWrite/Size are requested).

Copilot · 2026-03-05T02:21:39Z

src/libraries/System.IO.FileSystem.Watcher/src/System/IO/FileSystemWatcher.SunOS.cs

+
+                // File still exists - generate change event
+                // The event mask we used in PortAssociate already filtered to only
+                // the attributes we care about based on NotifyFilters


HandleFileEvent ignores the events bitmask returned by port_get and always raises WatcherChangeTypes.Changed. This prevents filtering to only the NotifyFilters the user asked for (e.g., distinguishing FILE_ATTRIB vs FILE_MODIFIED vs FILE_ACCESS) and compounds the risk of emitting Changed when only name filters were intended to drive directory diffs. Use the events flags to decide whether to raise a Changed event (and which NotifyFilters it satisfies) before notifying.

Suggested change

// the attributes we care about based on NotifyFilters

// the attributes we care about based on NotifyFilters

if ((events & _portEventMask) == 0)

{

return;

}

Copilot · 2026-03-05T02:21:39Z

src/libraries/System.IO.FileSystem.Watcher/src/System/IO/FileSystemWatcher.SunOS.cs

+                            // report error and return. The event loop will naturally exit when
+                            // no more events arrive since the directory is no longer associated.
+                            if (_weakWatcher.TryGetTarget(out FileSystemWatcher? watcher))
+                            {
+                                Interop.ErrorInfo error = Interop.Sys.GetLastErrorInfo();
+                                watcher.OnError(new ErrorEventArgs(
+                                    Interop.GetExceptionForIoErrno(error, _directoryPath)));
+                            }


If ReassociateDirectory fails, the code reports an error but keeps the event loop alive with an infinite PortGet(..., null) wait. With no directory association, no further events may arrive, so this thread can block forever and leak the port/resources until the user explicitly stops the watcher. Consider canceling the instance (or otherwise waking and exiting the loop) when reassociation fails so the watcher shuts down deterministically after a terminal error.

Suggested change

// report error and return. The event loop will naturally exit when

// no more events arrive since the directory is no longer associated.

if (_weakWatcher.TryGetTarget(out FileSystemWatcher? watcher))

{

Interop.ErrorInfo error = Interop.Sys.GetLastErrorInfo();

watcher.OnError(new ErrorEventArgs(

Interop.GetExceptionForIoErrno(error, _directoryPath)));

}

// report an error and cancel this instance so the event loop wakes and

// shuts down deterministically rather than blocking indefinitely.

if (_weakWatcher.TryGetTarget(out FileSystemWatcher? watcher))

{

Interop.ErrorInfo error = Interop.Sys.GetLastErrorInfo();

watcher.OnError(new ErrorEventArgs(

Interop.GetExceptionForIoErrno(error, _directoryPath)));

}

CancellationCallback();

src/libraries/System.IO.FileSystem.Watcher/src/System/IO/FileSystemWatcher.SunOS.cs

Copilot · 2026-03-05T02:21:40Z

src/native/libs/System.Native/pal_io.c

+    // Use the provided mtime from managed code
+    // This is the mtime captured before reading the directory
+    fo->fo_mtime.tv_sec = mtime->tv_sec;
+    fo->fo_mtime.tv_nsec = mtime->tv_nsec;
+    fo->fo_name = (char *)dirPath;


SystemNative_PortAssociate dereferences mtime and assigns fo->fo_name = dirPath without validating either pointer, but the header comment describes both as optional. Either make these parameters required (update the comment + add asserts) or handle null values safely to avoid a potential native null-deref if a caller ever passes null.

Copilot · 2026-03-05T02:21:40Z

src/native/libs/System.Native/pal_io.h

+ *   pFileObj - A pointer identifying the event source (for example, a file object).
+ *   dirPath  - Optional directory path used to identify the event source.
+ *   mtime    - Optional pointer to the last modification time of the event source.
+ *   events   - A bitmask of events to monitor for the event source.
+ *   cookie   - An opaque value returned to the caller when an event is delivered.
+ *
+ * Returns 0 on success, or -1 if an error occurred (in which case, errno is set appropriately).
+ */
+PALEXPORT int32_t SystemNative_PortAssociate(intptr_t port, intptr_t pFileObj, const char *dirPath, TimeSpec *mtime, int32_t events, uintptr_t cookie);


The docs for SystemNative_PortAssociate say dirPath and mtime are optional, but the current native implementation requires them (it unconditionally uses both). Please align the contract with reality: either update this comment to mark them required (and consider adding asserts) or update the native code to tolerate null pointers.

src/libraries/System.IO.FileSystem.Watcher/src/System/IO/FileSystemWatcher.SunOS.cs

Copilot AI review requested due to automatic review settings February 22, 2026 01:54

github-actions bot added the area-System.IO label Feb 22, 2026

dotnet-policy-service bot added the community-contribution Indicates that the PR has been added by a community member label Feb 22, 2026

Copilot started reviewing on behalf of gwr February 22, 2026 01:55 View session

Copilot AI reviewed Feb 22, 2026

View reviewed changes

gwr force-pushed the illumos-fswatch branch 2 times, most recently from cbe385d to 04c54a8 Compare February 22, 2026 02:19

Copilot AI review requested due to automatic review settings February 22, 2026 02:19

Copilot started reviewing on behalf of gwr February 22, 2026 02:20 View session

Copilot AI reviewed Feb 22, 2026

View reviewed changes

gwr force-pushed the illumos-fswatch branch from 04c54a8 to 51c7175 Compare February 22, 2026 02:49

Copilot AI review requested due to automatic review settings February 22, 2026 02:54

gwr force-pushed the illumos-fswatch branch from 51c7175 to 67cef49 Compare February 22, 2026 02:54

Copilot started reviewing on behalf of gwr February 22, 2026 02:55 View session

gwr force-pushed the illumos-fswatch branch 2 times, most recently from 8b4f6e2 to 3c5ee5f Compare February 22, 2026 03:00

Copilot AI reviewed Feb 22, 2026

View reviewed changes

gwr force-pushed the illumos-fswatch branch from 3c5ee5f to 0041bd0 Compare February 22, 2026 03:07

Copilot AI review requested due to automatic review settings February 22, 2026 03:15

gwr force-pushed the illumos-fswatch branch from 0041bd0 to 14e88e4 Compare February 22, 2026 03:15

Copilot started reviewing on behalf of gwr February 22, 2026 03:15 View session

Copilot AI reviewed Feb 22, 2026

View reviewed changes

jkotas added the os-SunOS SunOS, currently not officially supported label Feb 22, 2026

gwr force-pushed the illumos-fswatch branch from 14e88e4 to 3d59aa7 Compare February 22, 2026 05:21

Copilot AI review requested due to automatic review settings February 22, 2026 05:40

gwr force-pushed the illumos-fswatch branch from 3d59aa7 to 9af44c9 Compare February 22, 2026 05:40

Copilot started reviewing on behalf of gwr February 22, 2026 05:40 View session

Copilot AI reviewed Feb 22, 2026

View reviewed changes

gwr force-pushed the illumos-fswatch branch from 9af44c9 to 09b82ba Compare February 22, 2026 05:57

Copilot AI reviewed Feb 22, 2026

View reviewed changes

src/libraries/System.IO.FileSystem.Watcher/src/System/IO/FileSystemWatcher.SunOS.cs Outdated Show resolved Hide resolved

src/libraries/System.IO.FileSystem.Watcher/src/System/IO/FileSystemWatcher.SunOS.cs Show resolved Hide resolved

gwr added a commit to gwr/dotnet-runtime that referenced this pull request Feb 22, 2026

Add locking around subdirectoryWatchers changes

4d0b898

github.com/dotnet/pull/124716#discussion_r2838494096

gwr force-pushed the illumos-fswatch branch from 4d0b898 to 8821346 Compare February 22, 2026 22:07

Copilot AI review requested due to automatic review settings February 23, 2026 03:41

gwr force-pushed the illumos-fswatch branch from 8821346 to b12ec20 Compare February 23, 2026 03:41

Copilot started reviewing on behalf of gwr February 23, 2026 03:42 View session

Copilot AI reviewed Feb 23, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings February 23, 2026 04:22

Copilot started reviewing on behalf of gwr February 23, 2026 04:23 View session

Copilot AI reviewed Feb 23, 2026

View reviewed changes

This was referenced Feb 23, 2026

[wasm/browser] Failed to connect to socket /run/dbus/system_bus_socket #120176

Open

[wasm] Microsoft.Playwright.TargetClosedException : Target page, context or browser has been closed #121195

Open

Copilot AI review requested due to automatic review settings February 23, 2026 12:44

Copilot AI reviewed Feb 23, 2026

View reviewed changes

This was referenced Feb 25, 2026

Fix assert in JIT:new() during early initialization #124715

Merged

Tracking issue for illumos and Solaris x86-64 port work #34944

Open

gwr commented Mar 2, 2026

View reviewed changes

jkotas reviewed Mar 3, 2026

View reviewed changes

src/libraries/System.IO.FileSystem.Watcher/src/System/IO/FileSystemWatcher.SunOS.cs Outdated Show resolved Hide resolved

Drop resource limits

34899b9

Copilot AI reviewed Mar 5, 2026

View reviewed changes

missed some things to remove

6243c6e

Conversation

gwr commented Feb 22, 2026

Uh oh!

dotnet-policy-service bot commented Feb 22, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

gwr commented Feb 22, 2026

Uh oh!

am11 commented Feb 22, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!