Skip to content
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.

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

Feature request: Document rustix::runtime #1180

Open
zackw opened this issue Oct 5, 2024 · 7 comments
Open

Feature request: Document rustix::runtime #1180

zackw opened this issue Oct 5, 2024 · 7 comments

Comments

@zackw
Copy link

zackw commented Oct 5, 2024

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
Copy link
Author

zackw commented Oct 5, 2024

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

@zackw zackw closed this as completed Oct 5, 2024
@zackw zackw changed the title Feature request: process::_exit Feature request: Document rustix::runtime Oct 5, 2024
@zackw
Copy link
Author

zackw commented Oct 5, 2024

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

@zackw zackw reopened this Oct 5, 2024
@sunfishcode
Copy link
Member

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
Copy link
Author

zackw commented Oct 7, 2024

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
Copy link
Member

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
Copy link
Author

zackw commented Oct 12, 2024

@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 zackw closed this as completed Oct 12, 2024
@zackw
Copy link
Author

zackw commented Oct 12, 2024

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants