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.