Audit and document the system calls made for each "primitive" IO API

[aturon]

Now that IO reform is complete, we have a large number of "primitive" IO APIs -- functions in Rust that roughly correspond to a single system API, like opening a file or extracting its metadata.

We need to go through all of these APIs and add a section like # Platform notes which details which system API(s) are being used for each platform (usually, a Unix/Windows division suffices).

This documentation is very important for understanding the interaction of the std IO APIs with the underlying system, which is relevant when using lowering APIs, when sandboxing and application, and likely for other scenarios as well.

[steveklabnik]

I believe that #27537 has just superseded this ticket. @alexcrichton ?

[alexcrichton]

Oops, that's actually a duplicate of this, I tried to find this and wasn't able to find it!

[nathansizemore]

I'd love to start contributing some docs and this seems like a decent place to
dig in and start sending PRs as I knock out a module.
For something like, std::fs::remove_file, I'm assuming something along the
lines of this would be a decent start?

Platform Notes

Windows

p is first converted to UTF-16 and then passed to DeleteFileW.

Defined in

FileAPI.h

Defined as

BOOL DeleteFileW(LPCWSTR lpFileName);

Unix

p is first converted to a cstr and then passed to unlink

Defined in

unistd.h

Defined as

int unlink(const char *pathname);

Which could go into the comments above that function in std::fs; however, for
trait implementations such as std::io::Read, it is going to be difficult
to document various OS details due to trait implementer docs having no
overriding effects in the implementor documentation over the base docs defined
in the trait's definition comments. Or, this feature might already exist and I
just have no idea how to use it?

I see this being important for the following reason, TcpStream::read on
Unix will invoke the read syscall for a file descriptor, but if on Windows,
the recv syscall will be used with flags as 0. Assumptions can be made that
both are probably using Berkeley Sockets, but neither OS users know for sure,
nor does a Unix user know if pulling the fd out directly and setting flags will
have any effect on the behavior.

[alexcrichton]

@nathansizemore you're certainly more than welcome to jump in and help! That looks pretty good to me, but you probably don't need to go into quite so much detail about things like the C signature or the header file the functions come from. I think it's fine to basically say the behavior on Windows is to call the DeleteFileW function for example.

Documenting trait implementations may be a little trickier, yeah, but adding the docs to the impl itself should work out just fine at least in terms of the source code, and we can be sure to surface them in rustdoc at some point in the future if necessary. For now though it's probably fine to punt on those temporarily as most of the meat of our I/O bindings aren't in trait implementations.

[steveklabnik]

A part of #29359

[steveklabnik]

Triage: no change

[steveklabnik]

Tagging as p-medium; this probably will evolve into a checklist issue, given how big it is.

[steveklabnik]

Triage; no change.

This is a big job, and I think it would be useful, but there also doesn't seem to be a ton of demand. I also wonder if it doesn't tie us too much to specifics; we can say that these are purely informative, not normative, but still... then again, I also am not sure how much of these details would change at this point, really....

[DevQps]

@steveklabnik Personally I think we should probably cease to try and document the exact system calls made by each of these functions? I see the following pro's and con's:

Pro's:

• Users can make performance considerations with knowledge on how the types are implemented under the hood.

Con's:

• It is a lot of work to document all these IO API's.
• The implementation of these types might differ over time, requiring new documentation to be written and updated. Managing all these system calls is probably going to lead to more outdated information.

If people are really that much into performance, some special purpose high performance IO library might be more suited, or they could just take a look into the implementation of each File.

I do however think that we should mention best practices (for performance and safety reasons) when working with IO related types.

[steveklabnik]

I agree with your assessment, basically. This issue was opened a long time ago, but it doesn't seem like there's been that much demand for this.

Maybe @rust-lang/libs can chime in if this is something that they still want, and is worth spending our time on?

[sfackler]

I agree that there's not a ton of value here.

[alexcrichton]

Agreed with @sfackler, so I'm going to close this.