Document unimplemented functions. #1315
Conversation
Add documentation for several functions which rustix does not implement, or not yet implement, so that users searching for them may learn more.
| /// | ||
| /// [Eyra]: https://github.com/sunfishcode/eyra?tab=readme-ov-file#eyra | ||
| /// [origin]: https://github.com/sunfishcode/origin?tab=readme-ov-file#origin | ||
| pub mod libc_internals { |
There was a problem hiding this comment.
This list is incomplete - most obviously, there are a lot more pthread functions, and I think there are also more groups of kernel primitives that the C library needs to be intimately involved in any use of, e.g. rseq. It might be better to just say that it's incomplete rather than to try to make it exhaustive.
It's really unfortunate that pthreads implementations for Linux tend to interpose on the signal handling API. As far as I know, C libraries for other kernels do not need to do this. Not having full access to the signal handling API (and the fork/exec API) is a significant hindrance for projects like CLI shells; I think rustix's approach to those ideally ought to be that it calls into libc when configured to use libc as a back end, and makes direct system calls when not so configured.
There was a problem hiding this comment.
This list is incomplete - most obviously, there are a lot more pthread functions, and I think there are also more groups of kernel primitives that the C library needs to be intimately involved in any use of, e.g.
rseq. It might be better to just say that it's incomplete rather than to try to make it exhaustive.
The list is for people searching for specific names. So I've gone ahead and added all the pthread_* functions and rseq, and also added a comment saying it's not exhaustive.
It's really unfortunate that pthreads implementations for Linux tend to interpose on the signal handling API. As far as I know, C libraries for other kernels do not need to do this. Not having full access to the signal handling API (and the fork/exec API) is a significant hindrance for projects like CLI shells; I think rustix's approach to those ideally ought to be that it calls into libc when configured to use libc as a back end, and makes direct system calls when not so configured.
I think CLI shells can do everything they need using the public libc APIs to signals and fork/exec. If you want wrappers providing better ergonomics, that could be a separate library. If you don't want to use an actual libc and want direct syscalls, then origin and eyra are where the party's at.
| not_implemented!(shmdt); | ||
| not_implemented!(shmget); | ||
| not_implemented!(shmctl); | ||
| } |
There was a problem hiding this comment.
Signal handling functions in this list (tgkill, raise, signalfd, pidfd_send_signal) belong in the "awkward to provide this without interfering with the system C library" list.
There was a problem hiding this comment.
These might be ok. It's generally ok to raise signals, because libc's alreaedy have to accept that signals can get raised from outside the process too. We may want to gate them behind cfg(feature = "use-libc-sigrt") and reject reserved signal values though. Or make them unsafe with a safety condition of "don't use reserved signals, on penalty of UB".
There was a problem hiding this comment.
Ah, you also mentioned signalfd here. We should think about reserved signals there also, but otherwise, since it doesn't involve actual handlers, it might be ok.
| not_implemented!(_Exit); | ||
| not_implemented!(exit_group); | ||
| not_implemented!(sigpending); | ||
| not_implemented!(sigsuspend); |
There was a problem hiding this comment.
I tentatively categorized sigpending and sigsuspend as things we may be able to do, because they don't interfere with any signal handlers. But I guess this is all why I inserted some "probably"s into the comments. I haven't thought about all these super deeply yet.
| @@ -478,6 +486,9 @@ pub unsafe fn sigprocmask(how: How, set: Option<&Sigset>) -> io::Result<Sigset> | |||
|
|
|||
| /// `sigpending()`—Query the pending signals. | |||
| /// | |||
| /// If this is ever exposed publicly, we should think about whether it should | |||
| /// mask out signals reserved by libc. | |||
There was a problem hiding this comment.
Probably similar to how runtime signals are handled --- use libc sigrt in public API, but leave "raw" syscall which doesn't even care about libc in semi-public API
Add documentation for several functions which rustix does not implement, or not yet implement, so that users searching for them may learn more.