kernel/fs/
file.rs

1// SPDX-License-Identifier: GPL-2.0
2
3// Copyright (C) 2024 Google LLC.
4
5//! Files and file descriptors.
6//!
7//! C headers: [`include/linux/fs.h`](srctree/include/linux/fs.h) and
8//! [`include/linux/file.h`](srctree/include/linux/file.h)
9
10use crate::{
11    bindings,
12    cred::Credential,
13    error::{code::*, to_result, Error, Result},
14    fmt,
15    sync::aref::{ARef, AlwaysRefCounted},
16    types::{NotThreadSafe, Opaque},
17};
18use core::ptr;
19
20/// Flags associated with a [`File`].
21pub mod flags {
22    /// File is opened in append mode.
23    pub const O_APPEND: u32 = bindings::O_APPEND;
24
25    /// Signal-driven I/O is enabled.
26    pub const O_ASYNC: u32 = bindings::FASYNC;
27
28    /// Close-on-exec flag is set.
29    pub const O_CLOEXEC: u32 = bindings::O_CLOEXEC;
30
31    /// File was created if it didn't already exist.
32    pub const O_CREAT: u32 = bindings::O_CREAT;
33
34    /// Direct I/O is enabled for this file.
35    pub const O_DIRECT: u32 = bindings::O_DIRECT;
36
37    /// File must be a directory.
38    pub const O_DIRECTORY: u32 = bindings::O_DIRECTORY;
39
40    /// Like [`O_SYNC`] except metadata is not synced.
41    pub const O_DSYNC: u32 = bindings::O_DSYNC;
42
43    /// Ensure that this file is created with the `open(2)` call.
44    pub const O_EXCL: u32 = bindings::O_EXCL;
45
46    /// Large file size enabled (`off64_t` over `off_t`).
47    pub const O_LARGEFILE: u32 = bindings::O_LARGEFILE;
48
49    /// Do not update the file last access time.
50    pub const O_NOATIME: u32 = bindings::O_NOATIME;
51
52    /// File should not be used as process's controlling terminal.
53    pub const O_NOCTTY: u32 = bindings::O_NOCTTY;
54
55    /// If basename of path is a symbolic link, fail open.
56    pub const O_NOFOLLOW: u32 = bindings::O_NOFOLLOW;
57
58    /// File is using nonblocking I/O.
59    pub const O_NONBLOCK: u32 = bindings::O_NONBLOCK;
60
61    /// File is using nonblocking I/O.
62    ///
63    /// This is effectively the same flag as [`O_NONBLOCK`] on all architectures
64    /// except SPARC64.
65    pub const O_NDELAY: u32 = bindings::O_NDELAY;
66
67    /// Used to obtain a path file descriptor.
68    pub const O_PATH: u32 = bindings::O_PATH;
69
70    /// Write operations on this file will flush data and metadata.
71    pub const O_SYNC: u32 = bindings::O_SYNC;
72
73    /// This file is an unnamed temporary regular file.
74    pub const O_TMPFILE: u32 = bindings::O_TMPFILE;
75
76    /// File should be truncated to length 0.
77    pub const O_TRUNC: u32 = bindings::O_TRUNC;
78
79    /// Bitmask for access mode flags.
80    ///
81    /// # Examples
82    ///
83    /// ```
84    /// use kernel::fs::file;
85    /// # fn do_something() {}
86    /// # let flags = 0;
87    /// if (flags & file::flags::O_ACCMODE) == file::flags::O_RDONLY {
88    ///     do_something();
89    /// }
90    /// ```
91    pub const O_ACCMODE: u32 = bindings::O_ACCMODE;
92
93    /// File is read only.
94    pub const O_RDONLY: u32 = bindings::O_RDONLY;
95
96    /// File is write only.
97    pub const O_WRONLY: u32 = bindings::O_WRONLY;
98
99    /// File can be both read and written.
100    pub const O_RDWR: u32 = bindings::O_RDWR;
101}
102
103/// Wraps the kernel's `struct file`. Thread safe.
104///
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.
109///
110/// # Refcounting
111///
112/// Instances of this type are reference-counted. The reference count is incremented by the
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.
115///
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.
120///
121/// ## Light refcounts
122///
123/// Whenever a process has an fd to a file, it may use something called a "light refcount" as a
124/// performance optimization. Light refcounts are acquired by calling `fdget` and released with
125/// `fdput`. The idea behind light refcounts is that if the fd is not closed between the calls to
126/// `fdget` and `fdput`, then the refcount cannot hit zero during that time, as the `struct
127/// files_struct` holds a reference until the fd is closed. This means that it's safe to access the
128/// file even if `fdget` does not increment the refcount.
129///
130/// The requirement that the fd is not closed during a light refcount applies globally across all
131/// threads - not just on the thread using the light refcount. For this reason, light refcounts are
132/// only used when the `struct files_struct` is not shared with other threads, since this ensures
133/// that other unrelated threads cannot suddenly start using the fd and close it. Therefore,
134/// calling `fdget` on a shared `struct files_struct` creates a normal refcount instead of a light
135/// refcount.
136///
137/// Light reference counts must be released with `fdput` before the system call returns to
138/// userspace. This means that if you wait until the current system call returns to userspace, then
139/// all light refcounts that existed at the time have gone away.
140///
141/// ### The file position
142///
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
145/// performance optimization.
146///
147/// The condition for avoiding the `f_pos_lock` mutex is different from the condition for using
148/// `fdget`. With `fdget`, you may avoid incrementing the refcount as long as the current fd table
149/// is not shared; it is okay if there are other fd tables that also reference the same `struct
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
152/// position.
153///
154/// To represent files that are not thread safe due to this optimization, the [`LocalFile`] type is
155/// used.
156///
157/// ## Rust references
158///
159/// The reference type `&File` is similar to light refcounts:
160///
161/// * `&File` references don't own a reference count. They can only exist as long as the reference
162///   count stays positive, and can only be created when there is some mechanism in place to ensure
163///   this.
164///
165/// * The Rust borrow-checker normally ensures this by enforcing that the `ARef<File>` from which
166///   a `&File` is created outlives the `&File`.
167///
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.
170///
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`".
174///
175/// # Invariants
176///
177/// * All instances of this type are refcounted using the `f_count` field.
178/// * There must not be any active calls to `fdget_pos` on this file that did not take the
179///   `f_pos_lock` mutex.
180#[repr(transparent)]
181pub struct File {
182    inner: Opaque<bindings::file>,
183}
184
185// SAFETY: This file is known to not have any active `fdget_pos` calls that did not take the
186// `f_pos_lock` mutex, so it is safe to transfer it between threads.
187unsafe impl Send for File {}
188
189// SAFETY: This file is known to not have any active `fdget_pos` calls that did not take the
190// `f_pos_lock` mutex, so it is safe to access its methods from several threads in parallel.
191unsafe impl Sync for File {}
192
193// SAFETY: The type invariants guarantee that `File` is always ref-counted. This implementation
194// makes `ARef<File>` own a normal refcount.
195unsafe impl AlwaysRefCounted for File {
196    #[inline]
197    fn inc_ref(&self) {
198        // SAFETY: The existence of a shared reference means that the refcount is nonzero.
199        unsafe { bindings::get_file(self.as_ptr()) };
200    }
201
202    #[inline]
203    unsafe fn dec_ref(obj: ptr::NonNull<File>) {
204        // SAFETY: To call this method, the caller passes us ownership of a normal refcount, so we
205        // may drop it. The cast is okay since `File` has the same representation as `struct file`.
206        unsafe { bindings::fput(obj.cast().as_ptr()) }
207    }
208}
209
210/// Wraps the kernel's `struct file`. Not thread safe.
211///
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.
214///
215/// See the documentation for [`File`] for more information.
216///
217/// # Invariants
218///
219/// * All instances of this type are refcounted using the `f_count` field.
220/// * If there is an active call to `fdget_pos` that did not take the `f_pos_lock` mutex, then it
221///   must be on the same thread as this file.
222///
223/// [`assume_no_fdget_pos`]: LocalFile::assume_no_fdget_pos
224#[repr(transparent)]
225pub struct LocalFile {
226    inner: Opaque<bindings::file>,
227}
228
229// SAFETY: The type invariants guarantee that `LocalFile` is always ref-counted. This implementation
230// makes `ARef<LocalFile>` own a normal refcount.
231unsafe impl AlwaysRefCounted for LocalFile {
232    #[inline]
233    fn inc_ref(&self) {
234        // SAFETY: The existence of a shared reference means that the refcount is nonzero.
235        unsafe { bindings::get_file(self.as_ptr()) };
236    }
237
238    #[inline]
239    unsafe fn dec_ref(obj: ptr::NonNull<LocalFile>) {
240        // SAFETY: To call this method, the caller passes us ownership of a normal refcount, so we
241        // may drop it. The cast is okay since `LocalFile` has the same representation as
242        // `struct file`.
243        unsafe { bindings::fput(obj.cast().as_ptr()) }
244    }
245}
246
247impl LocalFile {
248    /// Constructs a new `struct file` wrapper from a file descriptor.
249    ///
250    /// The file descriptor belongs to the current process, and there might be active local calls
251    /// to `fdget_pos` on the same file.
252    ///
253    /// To obtain an `ARef<File>`, use the [`assume_no_fdget_pos`] function to convert.
254    ///
255    /// [`assume_no_fdget_pos`]: LocalFile::assume_no_fdget_pos
256    #[inline]
257    pub fn fget(fd: u32) -> Result<ARef<LocalFile>, BadFdError> {
258        // SAFETY: FFI call, there are no requirements on `fd`.
259        let ptr = ptr::NonNull::new(unsafe { bindings::fget(fd) }).ok_or(BadFdError)?;
260
261        // SAFETY: `bindings::fget` created a refcount, and we pass ownership of it to the `ARef`.
262        //
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
265        // `f_pos_lock` mutex.
266        Ok(unsafe { ARef::from_raw(ptr.cast()) })
267    }
268
269    /// Creates a reference to a [`LocalFile`] from a valid pointer.
270    ///
271    /// # Safety
272    ///
273    /// * The caller must ensure that `ptr` points at a valid file and that the file's refcount is
274    ///   positive for the duration of `'a`.
275    /// * The caller must ensure that if there is an active call to `fdget_pos` that did not take
276    ///   the `f_pos_lock` mutex, then that call is on the current thread.
277    #[inline]
278    pub unsafe fn from_raw_file<'a>(ptr: *const bindings::file) -> &'a LocalFile {
279        // SAFETY: The caller guarantees that the pointer is not dangling and stays valid for the
280        // duration of `'a`. The cast is okay because `LocalFile` is `repr(transparent)`.
281        //
282        // INVARIANT: The caller guarantees that there are no problematic `fdget_pos` calls.
283        unsafe { &*ptr.cast() }
284    }
285
286    /// Assume that there are no active `fdget_pos` calls that prevent us from sharing this file.
287    ///
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
290    /// with another thread.
291    ///
292    /// This method is intended to be used together with [`LocalFile::fget`] when the caller knows
293    /// statically that there are no `fdget_pos` calls on the current thread. For example, you
294    /// might use it when calling `fget` from an ioctl, since ioctls usually do not touch the file
295    /// position.
296    ///
297    /// # Safety
298    ///
299    /// There must not be any active `fdget_pos` calls on the current thread.
300    #[inline]
301    pub unsafe fn assume_no_fdget_pos(me: ARef<LocalFile>) -> ARef<File> {
302        // INVARIANT: There are no `fdget_pos` calls on the current thread, and by the type
303        // invariants, if there is a `fdget_pos` call on another thread, then it took the
304        // `f_pos_lock` mutex.
305        //
306        // SAFETY: `LocalFile` and `File` have the same layout.
307        unsafe { ARef::from_raw(ARef::into_raw(me).cast()) }
308    }
309
310    /// Returns a raw pointer to the inner C struct.
311    #[inline]
312    pub fn as_ptr(&self) -> *mut bindings::file {
313        self.inner.get()
314    }
315
316    /// Returns the credentials of the task that originally opened the file.
317    pub fn cred(&self) -> &Credential {
318        // SAFETY: It's okay to read the `f_cred` field without synchronization because `f_cred` is
319        // never changed after initialization of the file.
320        let ptr = unsafe { (*self.as_ptr()).f_cred };
321
322        // SAFETY: The signature of this function ensures that the caller will only access the
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.
325        unsafe { Credential::from_ptr(ptr) }
326    }
327
328    /// Returns the flags associated with the file.
329    ///
330    /// The flags are a combination of the constants in [`flags`].
331    #[inline]
332    pub fn flags(&self) -> u32 {
333        // This `read_volatile` is intended to correspond to a READ_ONCE call.
334        //
335        // SAFETY: The file is valid because the shared reference guarantees a nonzero refcount.
336        //
337        // FIXME(read_once): Replace with `read_once` when available on the Rust side.
338        unsafe { core::ptr::addr_of!((*self.as_ptr()).f_flags).read_volatile() }
339    }
340}
341
342impl File {
343    /// Creates a reference to a [`File`] from a valid pointer.
344    ///
345    /// # Safety
346    ///
347    /// * The caller must ensure that `ptr` points at a valid file and that the file's refcount is
348    ///   positive for the duration of `'a`.
349    /// * The caller must ensure that if there are active `fdget_pos` calls on this file, then they
350    ///   took the `f_pos_lock` mutex.
351    #[inline]
352    pub unsafe fn from_raw_file<'a>(ptr: *const bindings::file) -> &'a File {
353        // SAFETY: The caller guarantees that the pointer is not dangling and stays valid for the
354        // duration of `'a`. The cast is okay because `File` is `repr(transparent)`.
355        //
356        // INVARIANT: The caller guarantees that there are no problematic `fdget_pos` calls.
357        unsafe { &*ptr.cast() }
358    }
359}
360
361// Make LocalFile methods available on File.
362impl core::ops::Deref for File {
363    type Target = LocalFile;
364    #[inline]
365    fn deref(&self) -> &LocalFile {
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.
368        //
369        // By the type invariants, there are no `fdget_pos` calls that did not take the
370        // `f_pos_lock` mutex.
371        unsafe { LocalFile::from_raw_file(core::ptr::from_ref(self).cast()) }
372    }
373}
374
375/// A file descriptor reservation.
376///
377/// This allows the creation of a file descriptor in two steps: first, we reserve a slot for it,
378/// then we commit or drop the reservation. The first step may fail (e.g., the current process ran
379/// out of available slots), but commit and drop never fail (and are mutually exclusive).
380///
381/// Dropping the reservation happens in the destructor of this type.
382///
383/// # Invariants
384///
385/// The fd stored in this struct must correspond to a reserved file descriptor of the current task.
386pub struct FileDescriptorReservation {
387    fd: u32,
388    /// Prevent values of this type from being moved to a different task.
389    ///
390    /// The `fd_install` and `put_unused_fd` functions assume that the value of `current` is
391    /// unchanged since the call to `get_unused_fd_flags`. By adding this marker to this type, we
392    /// prevent it from being moved across task boundaries, which ensures that `current` does not
393    /// change while this value exists.
394    _not_send: NotThreadSafe,
395}
396
397impl FileDescriptorReservation {
398    /// Creates a new file descriptor reservation.
399    #[inline]
400    pub fn get_unused_fd_flags(flags: u32) -> Result<Self> {
401        // SAFETY: FFI call, there are no safety requirements on `flags`.
402        let fd: i32 = unsafe { bindings::get_unused_fd_flags(flags) };
403        to_result(fd)?;
404
405        Ok(Self {
406            fd: fd as u32,
407            _not_send: NotThreadSafe,
408        })
409    }
410
411    /// Returns the file descriptor number that was reserved.
412    #[inline]
413    pub fn reserved_fd(&self) -> u32 {
414        self.fd
415    }
416
417    /// Commits the reservation.
418    ///
419    /// The previously reserved file descriptor is bound to `file`. This method consumes the
420    /// [`FileDescriptorReservation`], so it will not be usable after this call.
421    #[inline]
422    pub fn fd_install(self, file: ARef<File>) {
423        // SAFETY: `self.fd` was previously returned by `get_unused_fd_flags`. We have not yet used
424        // the fd, so it is still valid, and `current` still refers to the same task, as this type
425        // cannot be moved across task boundaries.
426        //
427        // Furthermore, the file pointer is guaranteed to own a refcount by its type invariants,
428        // and we take ownership of that refcount by not running the destructor below.
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()) };
433
434        // `fd_install` consumes both the file descriptor and the file reference, so we cannot run
435        // the destructors.
436        core::mem::forget(self);
437        core::mem::forget(file);
438    }
439}
440
441impl Drop for FileDescriptorReservation {
442    #[inline]
443    fn drop(&mut self) {
444        // SAFETY: By the type invariants of this type, `self.fd` was previously returned by
445        // `get_unused_fd_flags`. We have not yet used the fd, so it is still valid, and `current`
446        // still refers to the same task, as this type cannot be moved across task boundaries.
447        unsafe { bindings::put_unused_fd(self.fd) };
448    }
449}
450
451/// Represents the [`EBADF`] error code.
452///
453/// Used for methods that can only fail with [`EBADF`].
454#[derive(Copy, Clone, Eq, PartialEq)]
455pub struct BadFdError;
456
457impl From<BadFdError> for Error {
458    #[inline]
459    fn from(_: BadFdError) -> Error {
460        EBADF
461    }
462}
463
464impl fmt::Debug for BadFdError {
465    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
466        f.pad("EBADF")
467    }
468}