doc(socket): add a note on how to enable NONBLOCK / CLOEXEC on macOS #2619
Conversation
| /// | ||
| /// Note: macOS supports `NONBLOCK` through separate call to `fcntl`, | ||
| /// e.g. `nix::fcntl::fcntl(fd, F_SETFL(O_NONBLOCK))` |
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
What does this PR do
Adds rustdoc comment on
SockFlagoptions forNONBLOCKandCLOEXEChinting on how to achieve that functionality on macOSSee discussion in #863
Checklist:
CONTRIBUTING.md