Struct cap_std::fs::File

source ·

pub struct File { /* private fields */ }

Expand description

A reference to an open file on a filesystem.

This corresponds to std::fs::File.

This File has no open or create methods. To open or create a file, first obtain a Dir containing the path, and then call Dir::open or Dir::create.

Implementations§

source §

impl File

source

pub fn from_std(std: File) -> Self

Constructs a new instance of Self from the given std::fs::File.

This grants access the resources the std::fs::File instance already has access to.

Examples found in repository ?

src/fs_utf8/file.rs (line 46)

45
46
47

    pub fn from_std(std: fs::File) -> Self {
        Self::from_cap_std(crate::fs::File::from_std(std))
    }

More examples

Hide additional examples

src/fs/dir_entry.rs (line 30)

    pub fn open(&self) -> io::Result<File> {
        let file = self.inner.open()?;
        Ok(File::from_std(file))
    }

    /// Open the file with the given options.
    #[inline]
    pub fn open_with(&self, options: &OpenOptions) -> io::Result<File> {
        let file = self.inner.open_with(options)?;
        Ok(File::from_std(file))
    }

src/fs/file.rs (line 94)

    pub fn try_clone(&self) -> io::Result<Self> {
        let file = self.std.try_clone()?;
        Ok(Self::from_std(file))
    }

    /// Changes the permissions on the underlying file.
    ///
    /// This corresponds to [`std::fs::File::set_permissions`].
    #[inline]
    pub fn set_permissions(&self, perm: Permissions) -> io::Result<()> {
        self.std
            .set_permissions(permissions_into_std(&self.std, perm)?)
    }

    /// Constructs a new instance of `Self` in read-only mode by opening the
    /// given path as a file using the host process' ambient authority.
    ///
    /// # Ambient Authority
    ///
    /// This function is not sandboxed and may access any path that the host
    /// process has access to.
    #[inline]
    pub fn open_ambient<P: AsRef<Path>>(
        path: P,
        ambient_authority: AmbientAuthority,
    ) -> io::Result<Self> {
        let std = open_ambient(
            path.as_ref(),
            OpenOptions::new().read(true),
            ambient_authority,
        )?;
        Ok(Self::from_std(std))
    }

    /// Constructs a new instance of `Self` with the options specified by
    /// `options` by opening the given path as a file using the host process'
    /// ambient authority.
    ///
    /// # Ambient Authority
    ///
    /// This function is not sandboxed and may access any path that the host
    /// process has access to.
    #[inline]
    pub fn open_ambient_with<P: AsRef<Path>>(
        path: P,
        options: &OpenOptions,
        ambient_authority: AmbientAuthority,
    ) -> io::Result<Self> {
        let std = open_ambient(path.as_ref(), options, ambient_authority)?;
        Ok(Self::from_std(std))
    }

    /// Returns a new `OpenOptions` object.
    ///
    /// This corresponds to [`std::fs::File::options`].
    #[must_use]
    #[inline]
    pub fn options() -> OpenOptions {
        OpenOptions::new()
    }
}

#[inline]
fn metadata_from(file: &fs::File) -> io::Result<Metadata> {
    Metadata::from_file(file)
}

#[inline]
fn permissions_into_std(file: &fs::File, permissions: Permissions) -> io::Result<fs::Permissions> {
    permissions.into_std(file)
}

// Safety: `FilelikeViewType` is implemented for `std::fs::File`.
unsafe impl io_lifetimes::views::FilelikeViewType for File {}

#[cfg(not(windows))]
impl FromRawFd for File {
    #[inline]
    unsafe fn from_raw_fd(fd: RawFd) -> Self {
        Self::from_std(fs::File::from_raw_fd(fd))
    }
}

#[cfg(not(windows))]
impl From<OwnedFd> for File {
    #[inline]
    fn from(fd: OwnedFd) -> Self {
        Self::from_std(fs::File::from(fd))
    }

src/fs/dir.rs (line 94)

    fn _open_with(&self, path: &Path, options: &OpenOptions) -> io::Result<File> {
        let dir = open(&self.std_file, path, options)?;
        Ok(File::from_std(dir))
    }

source

pub fn into_std(self) -> File

Consumes self and returns a std::fs::File.

Examples found in repository ?

src/fs_utf8/file.rs (line 58)

57
58
59

    pub fn into_std(self) -> fs::File {
        self.cap_std.into_std()
    }

source

pub fn sync_all(&self) -> Result<()>

Attempts to sync all OS-internal metadata to disk.

This corresponds to std::fs::File::sync_all.

Examples found in repository ?

src/fs_utf8/file.rs (line 66)

65
66
67

    pub fn sync_all(&self) -> io::Result<()> {
        self.cap_std.sync_all()
    }

source

pub fn sync_data(&self) -> Result<()>

This function is similar to sync_all, except that it may not synchronize file metadata to a filesystem.

This corresponds to std::fs::File::sync_data.

Examples found in repository ?

src/fs_utf8/file.rs (line 75)

74
75
76

    pub fn sync_data(&self) -> io::Result<()> {
        self.cap_std.sync_data()
    }

source

pub fn set_len(&self, size: u64) -> Result<()>

Truncates or extends the underlying file, updating the size of this file to become size.

This corresponds to std::fs::File::set_len.

Examples found in repository ?

src/fs_utf8/file.rs (line 84)

83
84
85

    pub fn set_len(&self, size: u64) -> io::Result<()> {
        self.cap_std.set_len(size)
    }

source

pub fn metadata(&self) -> Result<Metadata>

Queries metadata about the underlying file.

This corresponds to std::fs::File::metadata.

Examples found in repository ?

src/fs_utf8/file.rs (line 92)

91
92
93

    pub fn metadata(&self) -> io::Result<Metadata> {
        self.cap_std.metadata()
    }

More examples

Hide additional examples

src/fs/dir.rs (line 830)

fn initial_buffer_size(file: &File) -> usize {
    // Allocate one extra byte so the buffer doesn't need to grow before the
    // final `read` call at the end of the file. Don't worry about `usize`
    // overflow because reading will fail regardless in that case.
    file.metadata().map(|m| m.len() as usize + 1).unwrap_or(0)
}

source

pub fn try_clone(&self) -> Result<Self>

Creates a new File instance that shares the same underlying file handle as the existing File instance.

This corresponds to std::fs::File::try_clone.

Examples found in repository ?

src/fs_utf8/file.rs (line 101)

100
101
102

    pub fn try_clone(&self) -> io::Result<Self> {
        Ok(Self::from_cap_std(self.cap_std.try_clone()?))
    }

source

pub fn set_permissions(&self, perm: Permissions) -> Result<()>

Changes the permissions on the underlying file.

This corresponds to std::fs::File::set_permissions.

Examples found in repository ?

src/fs_utf8/file.rs (line 109)

108
109
110

    pub fn set_permissions(&self, perm: Permissions) -> io::Result<()> {
        self.cap_std.set_permissions(perm)
    }

source

pub fn open_ambient<P: AsRef<Path>>(
path: P,
ambient_authority: AmbientAuthority
) -> Result<Self>

Constructs a new instance of Self in read-only mode by opening the given path as a file using the host process’ ambient authority.

Ambient Authority

This function is not sandboxed and may access any path that the host process has access to.

Examples found in repository ?

src/fs_utf8/file.rs (lines 125-128)

    pub fn open_ambient<P: AsRef<Utf8Path>>(
        path: P,
        ambient_authority: AmbientAuthority,
    ) -> io::Result<Self> {
        let path = from_utf8(path.as_ref())?;
        Ok(Self::from_cap_std(crate::fs::File::open_ambient(
            path,
            ambient_authority,
        )?))
    }

source

pub fn open_ambient_with<P: AsRef<Path>>(
 path: P,
 options: &OpenOptions,
 ambient_authority: AmbientAuthority
) -> Result<Self>

Constructs a new instance of Self with the options specified by options by opening the given path as a file using the host process’ ambient authority.

Ambient Authority

This function is not sandboxed and may access any path that the host process has access to.

Examples found in repository ?

src/fs_utf8/file.rs (lines 146-150)

    pub fn open_ambient_with<P: AsRef<Utf8Path>>(
        path: P,
        options: &OpenOptions,
        ambient_authority: AmbientAuthority,
    ) -> io::Result<Self> {
        let path = from_utf8(path.as_ref())?;
        Ok(Self::from_cap_std(crate::fs::File::open_ambient_with(
            path,
            options,
            ambient_authority,
        )?))
    }