Lines Matching full:file
5 //! Files and file descriptors.
8 //! [`include/linux/file.h`](srctree/include/linux/file.h)
20 /// Flags associated with a [`File`].
22 /// File is opened in append mode.
31 /// File was created if it didn't already exist.
34 /// Direct I/O is enabled for this file.
37 /// File must be a directory.
43 /// Ensure that this file is created with the `open(2)` call.
46 /// Large file size enabled (`off64_t` over `off_t`).
49 /// Do not update the file last access time.
52 /// File should not be used as process's controlling terminal.
58 /// File is using nonblocking I/O.
61 /// File is using nonblocking I/O.
67 /// Used to obtain a path file descriptor.
70 /// Write operations on this file will flush data and metadata.
73 /// This file is an unnamed temporary regular file.
76 /// File should be truncated to length 0.
84 /// use kernel::fs::file;
87 /// if (flags & file::flags::O_ACCMODE) == file::flags::O_RDONLY {
93 /// File is read only.
96 /// File is write only.
99 /// File can be both read and written.
103 /// Wraps the kernel's `struct file`. Thread safe.
105 /// This represents an open file rather than a file on a filesystem. Processes generally reference
106 /// open files using file descriptors. However, file descriptors are not the same as files. A file
107 /// descriptor is just an integer that corresponds to a file, and a single file may be referenced
108 /// by multiple file descriptors.
113 /// `fget`/`get_file` functions and decremented by `fput`. The Rust type `ARef<File>` represents a
114 /// pointer that owns a reference count on the file.
116 /// Whenever a process opens a file descriptor (fd), it stores a pointer to the file in its fd
117 /// table (`struct files_struct`). This pointer owns a reference count to the file, ensuring the
118 /// file isn't prematurely deleted while the file descriptor is open. In Rust terminology, the
119 /// pointers in `struct files_struct` are `ARef<File>` pointers.
123 /// Whenever a process has an fd to a file, it may use something called a "light refcount" as a
128 /// file even if `fdget` does not increment the refcount.
141 /// ### The file position
143 /// Each `struct file` has a position integer, which is protected by the `f_pos_lock` mutex.
144 /// However, if the `struct file` is not shared, then the kernel may avoid taking the lock as a
150 /// file`. However, `fdget_pos` can only avoid taking the `f_pos_lock` if the entire `struct file`
151 /// is not shared, as different processes with an fd to the same `struct file` share the same
159 /// The reference type `&File` is similar to light refcounts:
161 /// * `&File` references don't own a reference count. They can only exist as long as the reference
165 /// * The Rust borrow-checker normally ensures this by enforcing that the `ARef<File>` from which
166 /// a `&File` is created outlives the `&File`.
168 /// * Using the unsafe [`File::from_raw_file`] means that it is up to the caller to ensure that the
169 /// `&File` only exists while the reference count is positive.
171 /// * You can think of `fdget` as using an fd to look up an `ARef<File>` in the `struct
172 /// files_struct` and create an `&File` from it. The "fd cannot be closed" rule is like the Rust
173 /// rule "the `ARef<File>` must outlive the `&File`".
178 /// * There must not be any active calls to `fdget_pos` on this file that did not take the
181 pub struct File {
182 inner: Opaque<bindings::file>,
185 // SAFETY: This file is known to not have any active `fdget_pos` calls that did not take the
187 unsafe impl Send for File {}
189 // SAFETY: This file is known to not have any active `fdget_pos` calls that did not take the
191 unsafe impl Sync for File {}
193 // SAFETY: The type invariants guarantee that `File` is always ref-counted. This implementation
194 // makes `ARef<File>` own a normal refcount.
195 unsafe impl AlwaysRefCounted for File {
203 unsafe fn dec_ref(obj: ptr::NonNull<File>) {
205 // may drop it. The cast is okay since `File` has the same representation as `struct file`.
210 /// Wraps the kernel's `struct file`. Not thread safe.
212 /// This type represents a file that is not known to be safe to transfer across thread boundaries.
213 /// To obtain a thread-safe [`File`], use the [`assume_no_fdget_pos`] conversion.
215 /// See the documentation for [`File`] for more information.
221 /// must be on the same thread as this file.
226 inner: Opaque<bindings::file>,
242 // `struct file`.
248 /// Constructs a new `struct file` wrapper from a file descriptor.
250 /// The file descriptor belongs to the current process, and there might be active local calls
251 /// to `fdget_pos` on the same file.
253 /// To obtain an `ARef<File>`, use the [`assume_no_fdget_pos`] function to convert.
263 // INVARIANT: This file is in the fd table on this thread, so either all `fdget_pos` calls
264 // are on this thread, or the file is shared, in which case `fdget_pos` calls took the
273 /// * The caller must ensure that `ptr` points at a valid file and that the file's refcount is
278 pub unsafe fn from_raw_file<'a>(ptr: *const bindings::file) -> &'a LocalFile {
286 /// Assume that there are no active `fdget_pos` calls that prevent us from sharing this file.
288 /// This makes it safe to transfer this file to other threads. No checks are performed, and
289 /// using it incorrectly may lead to a data race on the file position if the file is shared
294 /// might use it when calling `fget` from an ioctl, since ioctls usually do not touch the file
301 pub unsafe fn assume_no_fdget_pos(me: ARef<LocalFile>) -> ARef<File> {
306 // SAFETY: `LocalFile` and `File` have the same layout.
312 pub fn as_ptr(&self) -> *mut bindings::file {
316 /// Returns the credentials of the task that originally opened the file.
319 // never changed after initialization of the file.
323 // returned credential while the file is still valid, and the C side ensures that the
324 // credential stays valid at least as long as the file.
328 /// Returns the flags associated with the file.
335 // SAFETY: The file is valid because the shared reference guarantees a nonzero refcount.
342 impl File {
343 /// Creates a reference to a [`File`] from a valid pointer.
347 /// * The caller must ensure that `ptr` points at a valid file and that the file's refcount is
349 /// * The caller must ensure that if there are active `fdget_pos` calls on this file, then they
352 pub unsafe fn from_raw_file<'a>(ptr: *const bindings::file) -> &'a File {
354 // duration of `'a`. The cast is okay because `File` is `repr(transparent)`.
361 // Make LocalFile methods available on File.
362 impl core::ops::Deref for File {
366 // SAFETY: The caller provides a `&File`, and since it is a reference, it must point at a
367 // valid file for the desired duration.
375 /// A file descriptor reservation.
377 /// This allows the creation of a file descriptor in two steps: first, we reserve a slot for it,
385 /// The fd stored in this struct must correspond to a reserved file descriptor of the current task.
398 /// Creates a new file descriptor reservation.
411 /// Returns the file descriptor number that was reserved.
419 /// The previously reserved file descriptor is bound to `file`. This method consumes the
422 pub fn fd_install(self, file: ARef<File>) {
427 // Furthermore, the file pointer is guaranteed to own a refcount by its type invariants,
429 // Additionally, the file is known to not have any non-shared `fdget_pos` calls, so even if
430 // this process starts using the file position, this will not result in a data race on the
431 // file position.
432 unsafe { bindings::fd_install(self.fd, file.as_ptr()) };
434 // `fd_install` consumes both the file descriptor and the file reference, so we cannot run
437 core::mem::forget(file);