Struct File

pub struct File { /* private fields */ }

Wraps the kernel’s struct file. Thread safe.

This represents an open file rather than a file on a filesystem. Processes generally reference open files using file descriptors. However, file descriptors are not the same as files. A file descriptor is just an integer that corresponds to a file, and a single file may be referenced by multiple file descriptors.

Refcounting

Instances of this type are reference-counted. The reference count is incremented by the fget/get_file functions and decremented by fput. The Rust type ARef<File> represents a pointer that owns a reference count on the file.

Whenever a process opens a file descriptor (fd), it stores a pointer to the file in its fd table (struct files_struct). This pointer owns a reference count to the file, ensuring the file isn’t prematurely deleted while the file descriptor is open. In Rust terminology, the pointers in struct files_struct are ARef<File> pointers.

Light refcounts

Whenever a process has an fd to a file, it may use something called a “light refcount” as a performance optimization. Light refcounts are acquired by calling fdget and released with fdput. The idea behind light refcounts is that if the fd is not closed between the calls to fdget and fdput, then the refcount cannot hit zero during that time, as the struct files_struct holds a reference until the fd is closed. This means that it’s safe to access the file even if fdget does not increment the refcount.

The requirement that the fd is not closed during a light refcount applies globally across all threads - not just on the thread using the light refcount. For this reason, light refcounts are only used when the struct files_struct is not shared with other threads, since this ensures that other unrelated threads cannot suddenly start using the fd and close it. Therefore, calling fdget on a shared struct files_struct creates a normal refcount instead of a light refcount.

Light reference counts must be released with fdput before the system call returns to userspace. This means that if you wait until the current system call returns to userspace, then all light refcounts that existed at the time have gone away.

The file position

Each struct file has a position integer, which is protected by the f_pos_lock mutex. However, if the struct file is not shared, then the kernel may avoid taking the lock as a performance optimization.

The condition for avoiding the f_pos_lock mutex is different from the condition for using fdget. With fdget, you may avoid incrementing the refcount as long as the current fd table is not shared; it is okay if there are other fd tables that also reference the same struct file. However, fdget_pos can only avoid taking the f_pos_lock if the entire struct file is not shared, as different processes with an fd to the same struct file share the same position.

To represent files that are not thread safe due to this optimization, the LocalFile type is used.

Rust references

The reference type &File is similar to light refcounts:

• &File references don’t own a reference count. They can only exist as long as the reference count stays positive, and can only be created when there is some mechanism in place to ensure this.

• The Rust borrow-checker normally ensures this by enforcing that the ARef<File> from which a &File is created outlives the &File.

• Using the unsafe File::from_raw_file means that it is up to the caller to ensure that the &File only exists while the reference count is positive.

• You can think of fdget as using an fd to look up an ARef<File> in the struct files_struct and create an &File from it. The “fd cannot be closed” rule is like the Rust rule “the ARef<File> must outlive the &File”.

Invariants

• All instances of this type are refcounted using the f_count field.
• There must not be any active calls to fdget_pos on this file that did not take the f_pos_lock mutex.

Implementations

impl File

pub unsafe fn from_raw_file<'a>(ptr: *const file) -> &'a File

Creates a reference to a File from a valid pointer.

Safety

• The caller must ensure that ptr points at a valid file and that the file’s refcount is positive for the duration of ’a.
• The caller must ensure that if there are active fdget_pos calls on this file, then they took the f_pos_lock mutex.

Methods from Deref<Target = LocalFile>

pub fn as_ptr(&self) -> *mut file

Returns a raw pointer to the inner C struct.

pub fn cred(&self) -> &Credential

Returns the credentials of the task that originally opened the file.

pub fn flags(&self) -> u32

Returns the flags associated with the file.

The flags are a combination of the constants in flags.

Trait Implementations

impl AlwaysRefCounted for File

fn inc_ref(&self)

Increments the reference count on the object.

unsafe fn dec_ref(obj: NonNull<File>)

Decrements the reference count on the object.

impl Deref for File

type Target = LocalFile

The resulting type after dereferencing.

fn deref(&self) -> &LocalFile

Dereferences the value.

impl Send for File

impl Sync for File