Feature request: Document rustix::runtime

[zackw]

rustix does not currently expose the _exit system call as far as I can tell. This would be useful in at least two contexts:

• On the child side of a fork (which is also missing right now but I trust it's already on your list of things that need to be added)
• In #[no_std] crates that nonetheless have the kernel available (e.g. the various projects trying to make it possible to write Rust programs that do not use a C library).

[zackw]

I don't know how I managed to miss runtime::exit_group. Apologies for the noise.

[zackw]

I missed runtime::exit_group because the runtime feature and module aren't documented. Please consider this a request to fix that.

[sunfishcode]

If you generate the documentation with RUSTDOCFLAGS="--cfg document_experimental_runtime_api", it will include the docs for the runtime module.

If you'd like something more than that, it would be helpful to say more about your use case, to inform possible solutions here. Are you using origin, and if so can you use origin::program::exit_immediately? Do you just need exit_group or do you need more things currently in rustix::runtime?

[zackw]

If you generate the documentation

I would like the documentation on docs.rs to include the full API, please and thank you.

I understand that the parts of the API that are currently undocumented may be subject to change with less notice than the rest of the API, but I think you should have them publicly documented anyway, so that people don't waste time looking for alternative crates and/or trying to write syscall stubs by hand.

it would be helpful to say more about your use case

The short version is that I need functionality equivalent to (a subset of) origin, but usable with stable Rust, and so I am implementing it myself. The code is public: https://git.sr.ht/~zackw/root-scaffold/tree/main/item/src/glue It's not planned to be a general purpose library, only enough glue for the needs of the top-level binary (the goal is briefly discussed in the top-level README).

Right now the bits of the undocumented API that I need are runtime::exit_group and param::init, but I will definitely also need execve, and maybe also fork and signal handling. I do not, however, need threads at all and do not intend to spend any time on the possibility.

As a general principle, also, I feel that rustix ought to provide a documented interface to every single system call Linux has. It's fine if the documentation says "This is unsafe even by the normal standards of unsafe code, we haven't figured out how to define anything like a safe wrapper for it, and we don't plan on doing that work anytime soon, but we will change this API when we do get around to it". But if someone needs a particular system call and rustix doesn't document a stub for it, they're not going to give up, they're going to grumble and reach for the inline assembly.

[sunfishcode]

Thinking about this issue and sunfishcode/eyra#51, I ended up finding it feasible to make origin support stable Rust. So origin 0.21.2 (just released) now works on stable Rust, if you'd like to use that.

Looking at root-scaffold, I ended up writing a patch, which I've posted here, which ports it to origin.

It's mostly straightforward and should support everything, except for the atexit_hook argument. Do you need that, or is that just from looking at how other libc's work? It's used by dynamic linkers to implement DT_FINI sections in DSOs loaded before _start.

I also agree that we should ideally move stuff in rustix::runtime out to public modules, where possible, and cover more of Linux's syscall surface area in general. It's a lot though; Linux has many thousands of syscalls, if you include all the ioctls and prctls and fcntls and things, so complete coverage hasn't been a priority.

[zackw]

@sunfishcode Gosh, thanks! I have adopted your patch with some tweaking. Maybe I'll actually get around to coding up the thing I wanted to code in the first place!

I honored the atexit_hook because it's in the ABI; I think Linux always passes NULL, at least for statically linked executables, but it was easy enough to implement and so why not check that compliance box.

It's a lot though; Linux has many thousands of syscalls, if you include all the ioctls and prctls and fcntls and things

I sympathize, but also this project is going to need some weird ioctls :-)

... But rustix lets you write your own ioctl stubs already, so that won't actually be a problem. I feel like "a documented interface for every non-obsoleted top-level syscall" ("top-level" defined by what gets a __NR_ constant in asm/unistd.h) should be a feasible goal, and the intersection of that with the API specified in POSIX even more so. (The latter, in particular, includes execve and signal handling.)

[zackw]

I misclicked on "close with comment" instead of just "comment", apologies for the noise.