1 //! The Unix `fcntl` function is effectively lots of different functions hidden
2 //! behind a single dynamic dispatch interface. In order to provide a type-safe
3 //! API, rustix makes them all separate functions so that they can have
4 //! dedicated static type signatures.
5 //!
6 //! `fcntl` functions which are not specific to files or directories live in
7 //! the [`io`] module instead.
8 //!
9 //! [`io`]: crate::io
10 
11 use crate::{backend, io};
12 use backend::fd::{AsFd, OwnedFd, RawFd};
13 
14 pub use backend::io::types::FdFlags;
15 
16 /// `fcntl(fd, F_GETFD)`—Returns a file descriptor's flags.
17 ///
18 /// # References
19 ///  - [POSIX]
20 ///  - [Linux]
21 ///  - [Apple]
22 ///  - [FreeBSD]
23 ///  - [NetBSD]
24 ///  - [OpenBSD]
25 ///  - [DragonFly BSD]
26 ///  - [illumos]
27 ///  - [glibc]
28 ///
29 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/fcntl.html
30 /// [Linux]: https://man7.org/linux/man-pages/man2/fcntl.2.html
31 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/fcntl.2.html
32 /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=fcntl&sektion=2
33 /// [NetBSD]: https://man.netbsd.org/fcntl.2
34 /// [OpenBSD]: https://man.openbsd.org/fcntl.2
35 /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=fcntl&section=2
36 /// [illumos]: https://illumos.org/man/2/fcntl
37 /// [glibc]: https://www.gnu.org/software/libc/manual/html_node/Control-Operations.html#index-fcntl-function
38 #[inline]
39 #[doc(alias = "F_GETFD")]
fcntl_getfd<Fd: AsFd>(fd: Fd) -> io::Result<FdFlags>40 pub fn fcntl_getfd<Fd: AsFd>(fd: Fd) -> io::Result<FdFlags> {
41     backend::io::syscalls::fcntl_getfd(fd.as_fd())
42 }
43 
44 /// `fcntl(fd, F_SETFD, flags)`—Sets a file descriptor's flags.
45 ///
46 /// # References
47 ///  - [POSIX]
48 ///  - [Linux]
49 ///  - [Apple]
50 ///  - [FreeBSD]
51 ///  - [NetBSD]
52 ///  - [OpenBSD]
53 ///  - [DragonFly BSD]
54 ///  - [illumos]
55 ///  - [glibc]
56 ///
57 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/fcntl.html
58 /// [Linux]: https://man7.org/linux/man-pages/man2/fcntl.2.html
59 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/fcntl.2.html
60 /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=fcntl&sektion=2
61 /// [NetBSD]: https://man.netbsd.org/fcntl.2
62 /// [OpenBSD]: https://man.openbsd.org/fcntl.2
63 /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=fcntl&section=2
64 /// [illumos]: https://illumos.org/man/2/fcntl
65 /// [glibc]: https://www.gnu.org/software/libc/manual/html_node/Control-Operations.html#index-fcntl-function
66 #[inline]
67 #[doc(alias = "F_SETFD")]
fcntl_setfd<Fd: AsFd>(fd: Fd, flags: FdFlags) -> io::Result<()>68 pub fn fcntl_setfd<Fd: AsFd>(fd: Fd, flags: FdFlags) -> io::Result<()> {
69     backend::io::syscalls::fcntl_setfd(fd.as_fd(), flags)
70 }
71 
72 /// `fcntl(fd, F_DUPFD_CLOEXEC)`—Creates a new `OwnedFd` instance, with value
73 /// at least `min`, that has `O_CLOEXEC` set and that shares the same
74 /// underlying [file description] as `fd`.
75 ///
76 /// POSIX guarantees that `F_DUPFD_CLOEXEC` will use the lowest unused file
77 /// descriptor which is at least `min`, however it is not safe in general to
78 /// rely on this, as file descriptors may be unexpectedly allocated on other
79 /// threads or in libraries.
80 ///
81 /// # References
82 ///  - [POSIX]
83 ///  - [Linux]
84 ///  - [Apple]
85 ///  - [FreeBSD]
86 ///  - [NetBSD]
87 ///  - [OpenBSD]
88 ///  - [DragonFly BSD]
89 ///  - [illumos]
90 ///  - [glibc]
91 ///
92 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/fcntl.html
93 /// [Linux]: https://man7.org/linux/man-pages/man2/fcntl.2.html
94 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/fcntl.2.html
95 /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=fcntl&sektion=2
96 /// [NetBSD]: https://man.netbsd.org/fcntl.2
97 /// [OpenBSD]: https://man.openbsd.org/fcntl.2
98 /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=fcntl&section=2
99 /// [illumos]: https://illumos.org/man/2/fcntl
100 /// [glibc]: https://www.gnu.org/software/libc/manual/html_node/Control-Operations.html#index-fcntl-function
101 #[cfg(not(any(target_os = "espidf", target_os = "wasi")))]
102 #[inline]
103 #[doc(alias = "F_DUPFD_CLOEXEC")]
fcntl_dupfd_cloexec<Fd: AsFd>(fd: Fd, min: RawFd) -> io::Result<OwnedFd>104 pub fn fcntl_dupfd_cloexec<Fd: AsFd>(fd: Fd, min: RawFd) -> io::Result<OwnedFd> {
105     backend::io::syscalls::fcntl_dupfd_cloexec(fd.as_fd(), min)
106 }
107 
108 /// `fcntl(fd, F_DUPFD)`—Creates a new `OwnedFd` instance, with value at
109 /// least `min`, that shares the same underlying [file description] as `fd`.
110 ///
111 /// POSIX guarantees that `F_DUPFD` will use the lowest unused file descriptor
112 /// which is at least `min`, however it is not safe in general to rely on this,
113 /// as file descriptors may be unexpectedly allocated on other threads or in
114 /// libraries.
115 ///
116 /// # References
117 ///  - [POSIX]
118 ///  - [Linux]
119 ///  - [Apple]
120 ///  - [FreeBSD]
121 ///  - [NetBSD]
122 ///  - [OpenBSD]
123 ///  - [DragonFly BSD]
124 ///  - [illumos]
125 ///  - [glibc]
126 ///
127 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/fcntl.html
128 /// [Linux]: https://man7.org/linux/man-pages/man2/fcntl.2.html
129 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/fcntl.2.html
130 /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=fcntl&sektion=2
131 /// [NetBSD]: https://man.netbsd.org/fcntl.2
132 /// [OpenBSD]: https://man.openbsd.org/fcntl.2
133 /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=fcntl&section=2
134 /// [illumos]: https://illumos.org/man/2/fcntl
135 /// [glibc]: https://www.gnu.org/software/libc/manual/html_node/Control-Operations.html#index-fcntl-function
136 #[cfg(target_os = "espidf")]
137 #[inline]
138 #[doc(alias = "F_DUPFD")]
fcntl_dupfd<Fd: AsFd>(fd: Fd, min: RawFd) -> io::Result<OwnedFd>139 pub fn fcntl_dupfd<Fd: AsFd>(fd: Fd, min: RawFd) -> io::Result<OwnedFd> {
140     backend::io::syscalls::fcntl_dupfd(fd.as_fd(), min)
141 }
142