Struct DynamicFile 

pub struct DynamicFile<Source: SequenceFileSource> { /* private fields */ }

DynamicFile implements FileOps for files whose contents are generated by the kernel dynamically either from a sequence (see SequenceFileSource) or as a single blob of data (see DynamicFileSource). The file may be updated dynamically as it’s normally expected for files in /proc, e.g. when seeking back from the current position.

The following example shows how DynamicFile can be used with a DynamicFileSource:

#[derive(Clone)]
pub struct SimpleFile(u32);
impl SimpleFile {
    pub fn new_node(param: u32) -> impl FsNodeOps {
        DynamicFile::new_node(Self(param))
    }
}
impl DynamicFileSource for SimpleFile {
    fn generate(&self, sink: &mut DynamicFileBuf) -> Result<(), Errno> {
        writeln!(sink, "param: {}", self.0)?
        Ok(())
    }
}

SequenceFileSource should be used to generate file contents from a sequence of objects. SequenceFileSource::next() takes the cursor for the current position, outputs the next chunk of data in the sequence, and returns the the advanced cursor value. At the start of iteration, the cursor is Default::default(). The end of the sequence is indicated by returning None.

The next example generates the contents from a sequence of integer values:

[#derive(Clone)]
struct IntegersFile;
impl SequenceFileSource for IntegersFile {
    type Cursor = usize;
    fn next(&self, cursor: usize, sink: &mut DynamicFileBuf) -> Result<Option<usize>, Errno> {
        // The cursor starts at i32::default(), which is 0.
        writeln!(sink, "{}", cursor)?;
        if cursor > 1000 {
            // End of the sequence.
            return Ok(None);
        }
        Ok(Some(cursor + 1))
    }
}

Writable files should wrap DynamicFile and delegate it read() and seek() using the fileops_impl_delegate_read_and_seek! macro, as shown in the example below:

struct WritableProcFileSource {
  data: usize,
}
impl DynamicFileSource for WritableProcFileSource {
    fn generate(&self, sink: &mut DynamicFileBuf) -> Result<(), Errno> {
        writeln!("{}", self.data);
        Ok(())
    }
}
pub struct WritableProcFile {
  dynamic_file: DynamicFile<WritableProcFileSource>,
  ...
}
impl WritableProcFile {
    fn new() -> Self {
        Self { dynamic_file: DynamicFile::new(WritableProcFileSource { data: 42 }) }
    }
}
impl FileOps for WritableProcFile {
    fileops_impl_delegate_read_and_seek!(self, self.dynamic_file);

    fn write(
        &self,
        _file: &FileObject,
        _current_task: &CurrentTask,
        _offset: usize,
        data: &mut dyn InputBuffer,
    ) -> Result<usize, Errno> {
        ... Process write() ...
    }
}

Implementations

impl<Source: SequenceFileSource> DynamicFile<Source>

pub fn new(source: Source) -> Self

impl<Source: SequenceFileSource + Clone> DynamicFile<Source>

pub fn new_node(source: Source) -> impl FsNodeOps

Trait Implementations

impl<Source: SequenceFileSource> FileOps for DynamicFile<Source>

fn sync( &self, file: &FileObject, _current_task: &CurrentTask, ) -> Result<(), Errno>

Syncs cached state associated with the file descriptor to persistent storage.

fn is_seekable(&self) -> bool

Returns whether the file is seekable.

fn read( &self, locked: &mut Locked<FileOpsCore>, _file: &FileObject, current_task: &CurrentTask, offset: usize, data: &mut dyn OutputBuffer, ) -> Result<usize, Errno>

Read from the file at an offset. If the file does not have persistent offsets (either directly, or because it is not seekable), offset will be 0 and can be ignored. Returns the number of bytes read.

fn write( &self, _locked: &mut Locked<FileOpsCore>, _file: &FileObject, _current_task: &CurrentTask, _offset: usize, _data: &mut dyn InputBuffer, ) -> Result<usize, Errno>

Write to the file with an offset. If the file does not have persistent offsets (either directly, or because it is not seekable), offset will be 0 and can be ignored. Returns the number of bytes written.

fn seek( &self, locked: &mut Locked<FileOpsCore>, _file: &FileObject, current_task: &CurrentTask, current_offset: off_t, target: SeekTarget, ) -> Result<off_t, Errno>

Adjust the current_offset if the file is seekable.

fn open( &self, _locked: &mut Locked<FileOpsCore>, _file: &FileObject, _current_task: &CurrentTask, ) -> Result<(), Errno>

Called when the FileObject is opened/created

fn close( self: Box<Self>, _locked: &mut Locked<FileOpsCore>, _file: &FileObjectState, _current_task: &CurrentTask, )

Called when the FileObject is destroyed.

fn flush( &self, _locked: &mut Locked<FileOpsCore>, _file: &FileObject, _current_task: &CurrentTask, )

Called every time close() is called on this file, even if the file is not ready to be released.

fn has_persistent_offsets(&self) -> bool

Returns whether the file has meaningful seek offsets. Returning false is only optimization and will makes FileObject never hold the offset lock when calling read and write.

fn writes_update_seek_offset(&self) -> bool

Returns true if write() operations on the file will update the seek offset.

fn data_sync( &self, file: &FileObject, current_task: &CurrentTask, ) -> Result<(), Errno>

Syncs cached data, and only enough metadata to retrieve said data, to persistent storage.

fn get_memory( &self, _locked: &mut Locked<FileOpsCore>, _file: &FileObject, _current_task: &CurrentTask, _length: Option<usize>, _prot: ProtectionFlags, ) -> Result<Arc<MemoryObject>, Errno>

Returns a VMO representing this file. At least the requested protection flags must be set on the VMO. Reading or writing the VMO must read or write the file. If this is not possible given the requested protection, an error must be returned. The length is a hint for the desired size of the VMO. The returned VMO may be larger or smaller than the requested length. This method is typically called by Self::mmap.

fn mmap( &self, locked: &mut Locked<FileOpsCore>, file: &FileObject, current_task: &CurrentTask, addr: DesiredAddress, memory_offset: u64, length: usize, prot_flags: ProtectionFlags, options: MappingOptions, filename: NamespaceNode, ) -> Result<UserAddress, Errno>

Responds to an mmap call. The default implementation calls Self::get_memory to get a VMO and then maps it with [crate::mm::MemoryManager::map]. Only implement this trait method if your file needs to control mapping, or record where a VMO gets mapped.

fn readdir( &self, _locked: &mut Locked<FileOpsCore>, _file: &FileObject, _current_task: &CurrentTask, _sink: &mut dyn DirentSink, ) -> Result<(), Errno>

Respond to a getdents or getdents64 calls.

fn wait_async( &self, _locked: &mut Locked<FileOpsCore>, _file: &FileObject, _current_task: &CurrentTask, _waiter: &Waiter, _events: FdEvents, _handler: EventHandler, ) -> Option<WaitCanceler>

Establish a one-shot, edge-triggered, asynchronous wait for the given FdEvents for the given file and task. Returns None if this file does not support blocking waits.

fn query_events( &self, _locked: &mut Locked<FileOpsCore>, _file: &FileObject, _current_task: &CurrentTask, ) -> Result<FdEvents, Errno>

The events currently active on this file.

fn ioctl( &self, locked: &mut Locked<Unlocked>, file: &FileObject, current_task: &CurrentTask, request: u32, arg: SyscallArg, ) -> Result<SyscallResult, Errno>

fn fcntl( &self, _file: &FileObject, _current_task: &CurrentTask, cmd: u32, _arg: u64, ) -> Result<SyscallResult, Errno>

fn to_handle( &self, file: &FileObject, current_task: &CurrentTask, ) -> Result<Option<NullableHandle>, Errno>

Return a handle that allows access to this file descritor through the zxio protocols.

fn as_thread_group_key( &self, _file: &FileObject, ) -> Result<ThreadGroupKey, Errno>

Returns the associated pid_t.

fn readahead( &self, _file: &FileObject, _current_task: &CurrentTask, _offset: usize, _length: usize, ) -> Result<(), Errno>

fn extra_fdinfo( &self, _locked: &mut Locked<FileOpsCore>, _file: &FileHandle, _current_task: &CurrentTask, ) -> Option<FsString>

Extra information that is included in the /proc//fdfino/ entry.