Expose OFlags::LARGEFILE and document its behavior (#1020)

This flag can be reported by `fcntl_getfl` but is ignored currently.
It is also used in FUSE requests. But typical users do not need to care
about it since it will be added automatically by rustix and/or libc on
relevent calls.

Author: oxalica

src/backend/libc/c.rs

@@ -91,6 +91,16 @@ pub(crate) const MSG_DONTWAIT: c_int = libc::MSG_NONBLOCK;
 #[cfg(feature = "net")]
 pub(crate) const SO_NOSIGPIPE: c_int = 0x0800;
 
+// It is defined as 0 in libc under 64-bit platforms, but is automatically set by kernel.
+// https://github.com/torvalds/linux/blob/v6.7/fs/open.c#L1458-L1459
+#[cfg(linux_kernel)]
+pub(crate) const O_LARGEFILE: c_int = linux_raw_sys::general::O_LARGEFILE as _;
+
+// Gated under `_LARGEFILE_SOURCE` but automatically set by the kernel.
+// https://github.com/illumos/illumos-gate/blob/fb2cb638e5604b214d8ea8d4f01ad2e77b437c17/usr/src/ucbhead/sys/fcntl.h#L64
+#[cfg(target_os = "illumos")]
+pub(crate) const O_LARGEFILE: c_int = 0x2000;
+
 // On PowerPC, the regular `termios` has the `termios2` fields and there is no
 // `termios2`. linux-raw-sys has aliases `termios2` to `termios` to cover this
 // difference, but we still need to manually import it since `libc` doesn't

src/backend/libc/fs/types.rs

@@ -328,6 +328,14 @@ bitflags! {
         #[cfg(target_os = "freebsd")]
         const EMPTY_PATH = bitcast!(c::O_EMPTY_PATH);
 
+        /// `O_LARGEFILE`
+        ///
+        /// Note that rustix and/or libc will automatically set this flag when appropriate on
+        /// `open(2)` and friends, thus typical users do not need to care about it.
+        /// It will may be reported in return of `fcntl_getfl`, though.
+        #[cfg(any(linux_kernel, target_os = "illumos"))]
+        const LARGEFILE = bitcast!(c::O_LARGEFILE);
+
         /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
         const _ = !0;
     }

src/backend/linux_raw/fs/syscalls.rs

@@ -58,7 +58,7 @@ use {
 #[inline]
 pub(crate) fn open(path: &CStr, flags: OFlags, mode: Mode) -> io::Result<OwnedFd> {
     // Always enable support for large files.
-    let flags = flags | OFlags::from_bits_retain(c::O_LARGEFILE);
+    let flags = flags | OFlags::LARGEFILE;
 
     #[cfg(any(target_arch = "aarch64", target_arch = "riscv64"))]
     {
@@ -78,7 +78,7 @@ pub(crate) fn openat(
     mode: Mode,
 ) -> io::Result<OwnedFd> {
     // Always enable support for large files.
-    let flags = flags | OFlags::from_bits_retain(c::O_LARGEFILE);
+    let flags = flags | OFlags::LARGEFILE;
 
     unsafe { ret_owned_fd(syscall_readonly!(__NR_openat, dirfd, path, flags, mode)) }
 }

src/backend/linux_raw/fs/types.rs

@@ -250,6 +250,13 @@ bitflags! {
         /// `O_DIRECT`
         const DIRECT = linux_raw_sys::general::O_DIRECT;
 
+        /// `O_LARGEFILE`
+        ///
+        /// Note that rustix and/or libc will automatically set this flag when appropriate on
+        /// `open(2)` and friends, thus typical users do not need to care about it.
+        /// It will may be reported in return of `fcntl_getfl`, though.
+        const LARGEFILE = linux_raw_sys::general::O_LARGEFILE;
+
         /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
         const _ = !0;
     }

tests/fs/file.rs

@@ -112,15 +112,10 @@ fn test_file() {
     // Test `fcntl_getfl`.
     let fl = rustix::fs::fcntl_getfl(&file).unwrap();
 
-    // On Linux, rustix automatically sets `O_LARGEFILE`, so clear it here so
-    // that we can test that no other bits are present.
-    #[cfg(linux_kernel)]
-    let fl = fl - rustix::fs::OFlags::from_bits_retain(linux_raw_sys::general::O_LARGEFILE);
-
-    // On illumos, the system automatically sets `O_LARGEFILE`, so clear it
-    // here so that we can test that no other bits are present.
-    #[cfg(target_os = "illumos")]
-    let fl = fl - rustix::fs::OFlags::from_bits_retain(0x2000);
+    // Clear O_LARGEFILE, which may be set by rustix on 32-bit Linux or automatically by some
+    // kernel on 64-bit (Linux and illumos).
+    #[cfg(any(linux_kernel, target_os = "illumos"))]
+    let fl = fl - rustix::fs::OFlags::LARGEFILE;
 
     assert_eq!(fl, rustix::fs::OFlags::empty());