Module docs for std::os::unix::io inconsistent with I/O Safety discussion in std::io

[jsgf]

Location

https://doc.rust-lang.org/stable/std/os/unix/io/index.html

Summary

In std::io, it correctly says:

Note that exclusive ownership of a file descriptor does not imply exclusive ownership of the underlying kernel object that the file descriptor references (also called “file description” on some operating systems). File descriptors basically work like Arc: when you receive an owned file descriptor, you cannot know whether there are any other file descriptors that reference the same kernel object. However, when you create a new kernel object, you know that you are holding the only reference to it. Just be careful not to lend it to anyone, since they can obtain a clone and then you can no longer know what the reference count is! In that sense, OwnedFd is like Arc and BorrowedFd<'a> is like &'a Arc

However the table in std::io::unix::io has the table saying:

BorrowedFd<'a> => &'a _
OwnedFd => Box<_>

This is incorrect and potentially very misleading, because the result of dupping a file descriptor creates a new fd which shares the same underlying file structure in the kernel. In particular, for seekable fds they share the current file offset (ie, used by read write and lseek) and in some cases, file locking state. (In addition to inode state and underlying file/pipe/etc contents.)

The language here should reflect the language in std::io.

[jsgf]

cc @RalfJung @joshtriplett - I think this is something that #114780 should have addressed.

[RalfJung]

Yeah the model described in os::unix::io doesn't take into account dup and the indirection layer of "file descriptors" vs "file descriptions". (That was already the case before #114780 though, it just became a lot more apparent with that PR.)