vendor/rustix/src/io/fcntl.rs

   1 //! The Unix `fcntl` function is effectively lots of different functions
   2 //! hidden behind a single dynamic dispatch interface. In order to provide
   3 //! a type-safe API, rustix makes them all separate functions so that they
   4 //! can have dedicated static type signatures.
   5 //!
   6 //! `fcntl` functions which are not specific to files or directories live
   7 //! in 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")]
  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")]
  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 = "wasi", target_os = "espidf")))]
 102 #[inline]
 103 #[doc(alias = "F_DUPFD_CLOEXEC")]
 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 least
 109 /// `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")]
 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 }