1//! The unsafe `close` for raw file descriptors.
2//!
3//! # Safety
4//!
5//! Operating on raw file descriptors is unsafe.
6#![allow(unsafe_code)]
7
8use crate::backend;
9use backend::fd::RawFd;
10
11/// `close(raw_fd)`—Closes a `RawFd` directly.
12///
13/// Most users won't need to use this, as [`OwnedFd`] automatically closes its
14/// file descriptor on `Drop`.
15///
16/// This function does not return a `Result`, as it is the [responsibility] of
17/// filesystem designers to not return errors from `close`. Users who chose to
18/// use NFS or similar filesystems should take care to monitor for problems
19/// externally.
20///
21/// [responsibility]: https://lwn.net/Articles/576518/
22///
23/// # References
24/// - [Beej's Guide to Network Programming]
25/// - [POSIX]
26/// - [Linux]
27/// - [Apple]
28/// - [Winsock]
29/// - [FreeBSD]
30/// - [NetBSD]
31/// - [OpenBSD]
32/// - [DragonFly BSD]
33/// - [illumos]
34/// - [glibc]
35///
36/// [`OwnedFd`]: crate::fd::OwnedFd
37/// [Beej's Guide to Network Programming]: https://beej.us/guide/bgnet/html/split/system-calls-or-bust.html#close-and-shutdownget-outta-my-face
38/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/close.html
39/// [Linux]: https://man7.org/linux/man-pages/man2/close.2.html
40/// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/close.2.html#//apple_ref/doc/man/2/close
41/// [Winsock]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-closesocket
42/// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=close&sektion=2
43/// [NetBSD]: https://man.netbsd.org/close.2
44/// [OpenBSD]: https://man.openbsd.org/close.2
45/// [DragonFly BSD]: https://man.dragonflybsd.org/?command=close&section=2
46/// [illumos]: https://illumos.org/man/2/close
47/// [glibc]: https://sourceware.org/glibc/manual/latest/html_node/Opening-and-Closing-Files.html#index-close
48///
49/// # Safety
50///
51/// This function takes a `RawFd`, which must be valid before the call, and is
52/// not valid after the call.
53#[inline]
54pub unsafe fn close(raw_fd: RawFd) {
55 backend::io::syscalls::close(raw_fd)
56}
57
58/// `close(raw_fd)`—Closes a `RawFd` directly, and report any errors returned
59/// by the OS.
60///
61/// The rustix developers do not intend the existence of this feature to imply
62/// that anyone should use it.
63///
64/// # Safety
65///
66/// This function takes a `RawFd`, which must be valid before the call, and is
67/// not valid after the call, even if it fails.
68#[cfg(feature = "try_close")]
69pub unsafe fn try_close(raw_fd: RawFd) -> crate::io::Result<()> {
70 backend::io::syscalls::try_close(raw_fd)
71}
72