Rollup merge of rust-lang#129409 - grinapo:patch-1, r=Amanieu

Expand std::os::unix::fs::chown() doc with a warning

Include warning about losing setuid/gid when chowning, per POSIX.

It is about the underlying system call but it is rather useful to mention it in the help in case someone accidentally forgets (don't look at me :)).

Author: GuillaumeGomez

std/src/os/unix/fs.rs

@@ -987,6 +987,11 @@ impl DirBuilderExt for fs::DirBuilder {
 /// Changing the group typically requires either being the owner and a member of the group, or
 /// having privileges.
 ///
+/// Be aware that changing owner clears the `suid` and `sgid` permission bits in most cases
+/// according to POSIX, usually even if the user is root. The sgid is not cleared when
+/// the file is non-group-executable. See: <https://www.man7.org/linux/man-pages/man2/chown.2.html>
+/// This call may also clear file capabilities, if there was any.
+///
 /// If called on a symbolic link, this will change the owner and group of the link target. To
 /// change the owner and group of the link itself, see [`lchown`].
 ///