5 //! Files and file descriptors.
8 //! [`include/linux/file.h`](srctree/include/linux/file.h)
18 /// Flags associated with a [`File`].
20     /// File is opened in append mode.
29     /// File was created if it didn't already exist.
32     /// Direct I/O is enabled for this file.
35     /// File must be a directory.
41     /// Ensure that this file is created with the `open(2)` call.
44     /// Large file size enabled (`off64_t` over `off_t`).
47     /// Do not update the file last access time.
50     /// File should not be used as process's controlling terminal.
56     /// File is using nonblocking I/O.
59     /// File is using nonblocking I/O.
65     /// Used to obtain a path file descriptor.
68     /// Write operations on this file will flush data and metadata.
71     /// This file is an unnamed temporary regular file.
74     /// File should be truncated to length 0.
82     /// use kernel::fs::file;
85     /// if (flags & file::flags::O_ACCMODE) == file::flags::O_RDONLY {
91     /// File is read only.
94     /// File is write only.
97     /// File can be both read and written.
101 /// Wraps the kernel's `struct file`. Thread safe.
103 /// This represents an open file rather than a file on a filesystem. Processes generally reference
104 /// open files using file descriptors. However, file descriptors are not the same as files. A file
105 /// descriptor is just an integer that corresponds to a file, and a single file may be referenced
106 /// by multiple file descriptors.
111 /// `fget`/`get_file` functions and decremented by `fput`. The Rust type `ARef<File>` represents a
112 /// pointer that owns a reference count on the file.
114 /// Whenever a process opens a file descriptor (fd), it stores a pointer to the file in its fd
115 /// table (`struct files_struct`). This pointer owns a reference count to the file, ensuring the
116 /// file isn't prematurely deleted while the file descriptor is open. In Rust terminology, the
117 /// pointers in `struct files_struct` are `ARef<File>` pointers.
121 /// Whenever a process has an fd to a file, it may use something called a "light refcount" as a
126 /// file even if `fdget` does not increment the refcount.
139 /// ### The file position
141 /// Each `struct file` has a position integer, which is protected by the `f_pos_lock` mutex.
142 /// However, if the `struct file` is not shared, then the kernel may avoid taking the lock as a
148 /// file`. However, `fdget_pos` can only avoid taking the `f_pos_lock` if the entire `struct file`
149 /// is not shared, as different processes with an fd to the same `struct file` share the same
157 /// The reference type `&File` is similar to light refcounts:
159 /// * `&File` references don't own a reference count. They can only exist as long as the reference
163 /// * The Rust borrow-checker normally ensures this by enforcing that the `ARef<File>` from which
164 ///   a `&File` is created outlives the `&File`.
166 /// * Using the unsafe [`File::from_raw_file`] means that it is up to the caller to ensure that the
167 ///   `&File` only exists while the reference count is positive.
169 /// * You can think of `fdget` as using an fd to look up an `ARef<File>` in the `struct
170 ///   files_struct` and create an `&File` from it. The "fd cannot be closed" rule is like the Rust
171 ///   rule "the `ARef<File>` must outlive the `&File`".
176 /// * There must not be any active calls to `fdget_pos` on this file that did not take the
179 pub struct File {  struct
180     inner: Opaque<bindings::file>,
183 // SAFETY: This file is known to not have any active `fdget_pos` calls that did not take the
185 unsafe impl Send for File {}  argument
187 // SAFETY: This file is known to not have any active `fdget_pos` calls that did not take the
189 unsafe impl Sync for File {}  implementation
191 // SAFETY: The type invariants guarantee that `File` is always ref-counted. This implementation
192 // makes `ARef<File>` own a normal refcount.
193 unsafe impl AlwaysRefCounted for File {  implementation
201     unsafe fn dec_ref(obj: ptr::NonNull<File>) {  in dec_ref()  argument
203         // may drop it. The cast is okay since `File` has the same representation as `struct file`.  in dec_ref()
208 /// Wraps the kernel's `struct file`. Not thread safe.
210 /// This type represents a file that is not known to be safe to transfer across thread boundaries.
211 /// To obtain a thread-safe [`File`], use the [`assume_no_fdget_pos`] conversion.
213 /// See the documentation for [`File`] for more information.
219 ///   must be on the same thread as this file.
223     inner: Opaque<bindings::file>,
227 // makes `ARef<File>` own a normal refcount.
238         // may drop it. The cast is okay since `File` has the same representation as `struct file`.  in dec_ref()
244     /// Constructs a new `struct file` wrapper from a file descriptor.
246     /// The file descriptor belongs to the current process, and there might be active local calls
247     /// to `fdget_pos` on the same file.
249     /// To obtain an `ARef<File>`, use the [`assume_no_fdget_pos`] function to convert.
259         // INVARIANT: This file is in the fd table on this thread, so either all `fdget_pos` calls  in fget()
260         // are on this thread, or the file is shared, in which case `fdget_pos` calls took the  in fget()
269     /// * The caller must ensure that `ptr` points at a valid file and that the file's refcount is
274     pub unsafe fn from_raw_file<'a>(ptr: *const bindings::file) -> &'a LocalFile {  in from_raw_file()
276         // duration of 'a. The cast is okay because `File` is `repr(transparent)`.  in from_raw_file()
282     /// Assume that there are no active `fdget_pos` calls that prevent us from sharing this file.
284     /// This makes it safe to transfer this file to other threads. No checks are performed, and
285     /// using it incorrectly may lead to a data race on the file position if the file is shared
290     /// might use it when calling `fget` from an ioctl, since ioctls usually do not touch the file
297     pub unsafe fn assume_no_fdget_pos(me: ARef<LocalFile>) -> ARef<File> {  in assume_no_fdget_pos()  argument
302         // SAFETY: `LocalFile` and `File` have the same layout.  in assume_no_fdget_pos()
308     pub fn as_ptr(&self) -> *mut bindings::file {  in as_ptr()  argument
312     /// Returns the credentials of the task that originally opened the file.
315         // never changed after initialization of the file.  in cred()
319         // returned credential while the file is still valid, and the C side ensures that the  in cred()
320         // credential stays valid at least as long as the file.  in cred()
324     /// Returns the flags associated with the file.
331         // SAFETY: The file is valid because the shared reference guarantees a nonzero refcount.  in flags()
338 impl File {  implementation
339     /// Creates a reference to a [`File`] from a valid pointer.
343     /// * The caller must ensure that `ptr` points at a valid file and that the file's refcount is
345     /// * The caller must ensure that if there are active `fdget_pos` calls on this file, then they
348     pub unsafe fn from_raw_file<'a>(ptr: *const bindings::file) -> &'a File {  in from_raw_file()  argument
350         // duration of 'a. The cast is okay because `File` is `repr(transparent)`.  in from_raw_file()
357 // Make LocalFile methods available on File.
358 impl core::ops::Deref for File {  implementation
362         // SAFETY: The caller provides a `&File`, and since it is a reference, it must point at a  in deref()
363         // valid file for the desired duration.  in deref()
367         unsafe { LocalFile::from_raw_file(self as *const File as *const bindings::file) }  in deref()  constant
371 /// A file descriptor reservation.
373 /// This allows the creation of a file descriptor in two steps: first, we reserve a slot for it,
381 /// The fd stored in this struct must correspond to a reserved file descriptor of the current task.
394     /// Creates a new file descriptor reservation.
407     /// Returns the file descriptor number that was reserved.
414     /// The previously reserved file descriptor is bound to `file`. This method consumes the
416     pub fn fd_install(self, file: ARef<File>) {  in fd_install()  argument
421         // Furthermore, the file pointer is guaranteed to own a refcount by its type invariants,  in fd_install()
423         // Additionally, the file is known to not have any non-shared `fdget_pos` calls, so even if  in fd_install()
424         // this process starts using the file position, this will not result in a data race on the  in fd_install()
425         // file position.  in fd_install()
426         unsafe { bindings::fd_install(self.fd, file.as_ptr()) };  in fd_install()
428         // `fd_install` consumes both the file descriptor and the file reference, so we cannot run  in fd_install()
431         core::mem::forget(file);  in fd_install()