Skip to content

doc(socket): add a note on how to enable NONBLOCK / CLOEXEC on macOS #2619

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

doc(socket): add a note on how to enable NONBLOCK / CLOEXEC on macOS #2619

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
eaa9309
doc(socket): add note on how to enable NONBLOCK on macOS
kskalski Mar 24, 2025
0170654
Also document CLOEXEC
kskalski Mar 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions src/sys/socket/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -290,12 +290,18 @@ libc_bitflags! {
/// Additional socket options
pub struct SockFlag: c_int {
/// Set non-blocking mode on the new socket
///
/// Note: macOS supports `NONBLOCK` through separate call to `fcntl`,
/// e.g. `nix::fcntl::fcntl(fd, F_SETFL(O_NONBLOCK))`
Comment on lines +293 to +295
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The variant is not available on macOS, so macOS users won't see this hint when reading Nix's doc.

BTW, do we really need to document this? Googling "set file descriptor non-blocking" directly leads me to this: https://stackoverflow.com/questions/27266346/how-to-set-file-descriptor-non-blocking

Copy link
Author

@kskalski kskalski Mar 25, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My story with that is: I don't use macOS, but people on my team do, so when I was using this API the issue came up that this flag won't compile for everyone and together with that the false assumption, that macOS (or maybe just nix) doesn't support NONBLOCK.

My searches on the macOS support gave some arguments that it actually exists (at this point my understanding was it's just nix's shortcoming). Unfortunately only much later after going through comments on this PR (#863) I realized it's just a difference in macOS and linux API, not the complete lack of support.
Given that - the usecase of linux developer looking up on how to enable feature on macOS would be much better served having the doc comments somewhere around even if macOS developer has those flags hidden. And in any case, it's still shown on https://docs.rs/nix/latest/nix/sys/socket/struct.SockFlag.html#associatedconstant.SOCK_NONBLOCK

Googling "set file descriptor non-blocking"

Not completely fair - this search is for the actual solution, not the problem, so surely it yields good answer. The real question "does macOS support NONBLOCK and why nix crate doesn't expose it" is a bit harder to answer.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do get what you said here, but Nix should not do such cross-platform documentation, I do not remember such things ever happened since I maintained this lib.

Regarding Nix's documentation, we try to be well-documented, but platform's man pages are the right place that you should refer to when figuring out something, $ man 2 socket. And if you believe what Apple man pages say, SOCK_NONBLOCK is a symbol that macOS does not provide. (I say so because Apple man pages are usually outdated, you need to search darwin's source code if you wanna do serious research)

I think I will document why Nix's socket() function has an extra flags argument, this can confuse users when they read the doc.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yap, those are valid points. From the perspective of nix user I think some hint on "why" specific flag variants are selectively available only on some platforms would be useful, but as you say it might belong to the level of flags enum or somewhere else.

#[cfg(any(linux_android,
freebsdlike,
netbsdlike,
solarish))]
SOCK_NONBLOCK;
/// Set close-on-exec on the new descriptor
///
/// Note: macOS supports `CLOEXEC` through separate call to `fcntl`,
/// e.g. `nix::fcntl::fcntl(fd, F_SETFL(O_CLOEXEC))`
#[cfg(any(linux_android,
freebsdlike,
netbsdlike,
Expand Down