[selvmaya]

I was learning how to use unix datagrams and was confused about why my vec wasn't receiving any bytes. I thought for a while I was doing something conceptually wrong with binding or connecting my sockets (I was working with two different concurrent programs, like you typically might), but it turns out I just misunderstood the API.

This documentation PR rewords the description slightly, and modifies the example for recv and recv_from to include a notice about buffers being of a large enough length.

The original examples use Vec::as_mut_slice, but since &mut Vec<u8> dereferences a mutable slice &mut [u8], and because you might reach for the latter for brevity or because of how other APIs work, I changed it to use &mut Vec<u8>, with an additional note to make the intent more clear.
We can change this back if it is believed to be clearer, I just want the added comment/hint to be as clear as possible.

[rustbot]

Thanks for the pull request, and welcome! The Rust Project has assigned @Mark-Simulacrum (or someone else) to review your changes, you should hear from them (or someone else) within the next two weeks.

Please see the contribution instructions and our LLM policy for more information.

Why was this reviewer chosen?

The reviewer was selected based on:

• Owners of files modified in this PR: @ChrisDenton, libs
• @ChrisDenton, libs expanded to 13 candidates
• Random selection from ChrisDenton, JohnTitor, Mark-Simulacrum

[Mark-Simulacrum]

Hm, I'm not sure I understand the confusion. Can you say more (maybe provide a playground link) about "The reason for this is because linux/unix doesn't know about vecs, and can only modify the slice of bytes in-place."? I agree it doesn't "know" about Vecs, but this is true for all such APIs. We also make no particular guarantees about how the read is performed (in-place or via intermediate buffers), though it shouldn't be required to go via an intermediate buffer on any common OS.

[selvmaya]

I see what you mean, and I've reworded the change a bit.

The motivation can be summarized with this playground link:
https://play.rust-lang.org/?version=stable&mode=debug&edition=2024&gist=5f52322f5b6947599acb3a95818827e1

Basically, a &mut Vec<u8> may implicitly dereference to a &mut [u8]. This doesn't happen for a buffer like &mut String, so you won't see it happen for a lot of functions, and for writing where you are instead implictly using a shared/non-mutable slice like &str or &[u8], this isn't an issue. But specifically when reading into a buffer, you have to make sure the slice is big enough, which may cause some confusion. Some common std::io APIs like Stdin::read_line use a &mut String to read, and thus can extend itself as needed instead of having to be initialized with some non-zero length.

I'll concede that this is a simple fix in code, I just want to make it more obvious to users of API that it operates on a slice even if give it a &mut Vec<u8>.