docs: Breaking change — SafeFileHandle.IsAsync and FileStream.IsAsync now reflect actual O_NONBLOCK state on Unix (.NET 11)

[Copilot]

In .NET 11 Preview 3, SafeFileHandle.IsAsync and FileStream.IsAsync on Unix changed from always returning true for files opened with FileOptions.Asynchronous to accurately reflecting whether O_NONBLOCK is set on the file descriptor. Regular files now return false; only genuinely non-blocking fds (pipes, sockets) return true.

Changes

• New article docs/core/compatibility/core-libraries/11/safefilehandle-isasync-unix.md covering:
  • SafeFileHandle.IsAsync / FileStream.IsAsync Unix behavior change
  • SendPacketsElement(FileStream, ...) no longer throws ArgumentException on non-Windows for non-async streams
  • Recommended actions for each impacted scenario
• 11.md — added row under Core .NET libraries
• toc.yml — added entry under .NET 11 > Core .NET libraries

Behavior at a glance

// Before (.NET 10): always true for FileOptions.Asynchronous on Unix
using SafeFileHandle h = File.OpenHandle("file.txt", options: FileOptions.Asynchronous);
Console.WriteLine(h.IsAsync); // true (misleading — no O_NONBLOCK on regular file)

// After (.NET 11): reflects actual fd state
SafeFileHandle.CreateAnonymousPipe(out var read, out var write, asyncRead: true, asyncWrite: false);
Console.WriteLine(read.IsAsync);  // true  (O_NONBLOCK set)
Console.WriteLine(write.IsAsync); // false (blocking)
// Regular file: false

---

Internal previews

📄 File	🔗 Preview link
docs/core/compatibility/11.md	Breaking changes in .NET 11
docs/core/compatibility/core-libraries/11/safefilehandle-isasync-unix.md	SafeFileHandle.IsAsync and FileStream.IsAsync accurately reflect non-blocking state on Unix
docs/core/compatibility/toc.yml	docs/core/compatibility/toc

[Copilot]

Pull request overview

Adds a new .NET 11 breaking change article documenting updated Unix semantics for SafeFileHandle.IsAsync and FileStream.IsAsync, and wires the article into the .NET compatibility index and TOC.

Changes:

• Adds a new breaking change article describing the Unix IsAsync behavior update (and related SendPacketsElement behavior on non-Windows).
• Updates the .NET 11 breaking changes index to include the new entry.
• Updates the compatibility TOC to surface the new article under .NET 11 > Core .NET libraries.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
docs/core/compatibility/core-libraries/11/safefilehandle-isasync-unix.md	New breaking change article describing the updated Unix IsAsync behavior and recommended actions.
docs/core/compatibility/11.md	Adds the new breaking change link to the .NET 11 index table.
docs/core/compatibility/toc.yml	Adds a TOC entry so the new article appears in navigation.

[Copilot]

The "Reason for change" section says SafeFileHandle.IsAsync previously reported false for genuinely non-blocking file descriptors (pipes/sockets with O_NONBLOCK), but the "Previous behavior" section only describes the regular-file scenario. Add a sentence in "Previous behavior" clarifying the pipe/socket case (and that the value was based on the open options rather than actual O_NONBLOCK) so the narrative doesn’t read as contradictory.

[gewarren]

@copilot apply changes based on this feedback

[Copilot]

Updated in 2a1f4e0. The "Previous behavior" section now explicitly describes both scenarios: regular files returning true despite no O_NONBLOCK (values based on open options), and genuinely non-blocking pipes/sockets incorrectly returning false.