Deprecate unshare and add unshare_unsafe.

src/backend/libc/thread/syscalls.rs

@@ -343,8 +343,8 @@ pub(crate) fn setns(fd: BorrowedFd<'_>, nstype: c::c_int) -> io::Result<c::c_int
 
 #[cfg(linux_kernel)]
 #[inline]
-pub(crate) fn unshare(flags: crate::thread::UnshareFlags) -> io::Result<()> {
-    unsafe { ret(c::unshare(flags.bits() as i32)) }
+pub(crate) unsafe fn unshare(flags: crate::thread::UnshareFlags) -> io::Result<()> {
+    ret(c::unshare(flags.bits() as i32))
 }
 
 #[cfg(linux_kernel)]

src/backend/linux_raw/thread/syscalls.rs

@@ -372,8 +372,8 @@ pub(crate) fn setns(fd: BorrowedFd<'_>, nstype: c::c_int) -> io::Result<c::c_int
 }
 
 #[inline]
-pub(crate) fn unshare(flags: crate::thread::UnshareFlags) -> io::Result<()> {
-    unsafe { ret(syscall_readonly!(__NR_unshare, flags)) }
+pub(crate) unsafe fn unshare(flags: crate::thread::UnshareFlags) -> io::Result<()> {
+    ret(syscall_readonly!(__NR_unshare, flags))
 }
 
 #[inline]

src/thread/setns.rs

@@ -1,3 +1,10 @@
+//! Thread-specific namespace functions.
+//!
+//! # Safety
+//!
+//! The `unshare` function can cause threads to use different file descriptor tables.
+#![allow(unsafe_code)]
+
 use bitflags::bitflags;
 use linux_raw_sys::general::{
     CLONE_FILES, CLONE_FS, CLONE_NEWCGROUP, CLONE_NEWIPC, CLONE_NEWNET, CLONE_NEWNS, CLONE_NEWPID,
@@ -127,13 +134,29 @@ pub fn move_into_thread_name_spaces(
     syscalls::setns(fd, allowed_types.bits() as c_int).map(|_r| ())
 }
 
+/// `unshare(flags)`—Deprecated in favor of [`unshare_unsafe`].
+///
+/// This function should be unsafe; see the safety comment on `unshare_unsafe`.
+#[deprecated(since = "1.1.0", note = "Use `unshare_unsafe`")]
+pub fn unshare(flags: UnshareFlags) -> io::Result<()> {
+    // SAFETY: This is not actually safe. This function is deprecated and users
+    // should use `unshare_unsafe` instead.
+    unsafe { syscalls::unshare(flags) }
+}
+
 /// `unshare(flags)`—Disassociate parts of the current thread's execution
 /// context with other threads.
 ///
+/// # Safety
+///
+/// When using `UnshareFlags::FILES`, this function can cause one thread to be
+/// unable to use file descriptors created on a different thread. Callers must
+/// ensure that threads never observe file descriptors from unshared tables.
+///
 /// # References
 ///  - [Linux]
 ///
 /// [Linux]: https://man7.org/linux/man-pages/man2/unshare.2.html
-pub fn unshare(flags: UnshareFlags) -> io::Result<()> {
+pub unsafe fn unshare_unsafe(flags: UnshareFlags) -> io::Result<()> {
     syscalls::unshare(flags)
 }