vfs/file.rs
1// Copyright 2019 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5//! Module holding different kinds of files and their building blocks.
6
7use crate::execution_scope::ExecutionScope;
8use crate::node::Node;
9use crate::object_request::{ObjectRequestRef, ToObjectRequest as _};
10use crate::protocols::ProtocolsExt;
11use fidl_fuchsia_io as fio;
12use std::future::{ready, Future};
13use std::sync::Arc;
14use zx_status::Status;
15
16/// File nodes backed by VMOs.
17#[cfg(target_os = "fuchsia")]
18pub mod vmo;
19
20#[cfg(not(target_os = "fuchsia"))]
21pub mod simple;
22
23mod common;
24
25pub mod connection;
26
27pub use connection::{FidlIoConnection, RawIoConnection};
28
29#[cfg(target_os = "fuchsia")]
30pub use connection::{GetVmo, StreamIoConnection};
31
32/// Creates a new read-only `SimpleFile` with the specified `content`.
33///
34/// ## Examples
35/// ```
36/// // Using static data:
37/// let from_str = read_only("str");
38/// let from_bytes = read_only(b"bytes");
39/// // Using owned data:
40/// let from_string = read_only(String::from("owned"));
41/// let from_vec = read_only(vec![0u8; 2]);
42/// ```
43#[cfg(not(target_os = "fuchsia"))]
44pub fn read_only(content: impl AsRef<[u8]>) -> Arc<simple::SimpleFile> {
45 simple::SimpleFile::read_only(content)
46}
47
48#[cfg(target_os = "fuchsia")]
49pub use vmo::read_only;
50
51/// FileOptions include options that are relevant after the file has been opened. Flags like
52/// `TRUNCATE`, which only applies during open time, are not included.
53#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
54pub struct FileOptions {
55 pub rights: fio::Operations,
56 pub is_append: bool,
57 #[cfg(fuchsia_api_level_at_least = "HEAD")]
58 pub is_linkable: bool,
59}
60
61impl FileOptions {
62 /// Converts to `StreamOptions`.
63 #[cfg(target_os = "fuchsia")]
64 pub fn to_stream_options(&self) -> zx::StreamOptions {
65 let mut options = zx::StreamOptions::empty();
66 if self.rights.contains(fio::Operations::READ_BYTES) {
67 options |= zx::StreamOptions::MODE_READ;
68 }
69 if self.rights.contains(fio::Operations::WRITE_BYTES) {
70 options |= zx::StreamOptions::MODE_WRITE;
71 }
72 if self.is_append {
73 options |= zx::StreamOptions::MODE_APPEND;
74 }
75 options
76 }
77
78 pub(crate) fn to_io1(&self) -> fio::OpenFlags {
79 let mut flags = fio::OpenFlags::empty();
80 if self.rights.contains(fio::Operations::READ_BYTES) {
81 flags |= fio::OpenFlags::RIGHT_READABLE;
82 }
83 if self.rights.contains(fio::Operations::WRITE_BYTES) {
84 flags |= fio::OpenFlags::RIGHT_WRITABLE;
85 }
86 if self.rights.contains(fio::Operations::EXECUTE) {
87 flags |= fio::OpenFlags::RIGHT_EXECUTABLE;
88 }
89 if self.is_append {
90 flags |= fio::OpenFlags::APPEND;
91 }
92 flags
93 }
94}
95
96impl From<&FileOptions> for fio::Flags {
97 fn from(options: &FileOptions) -> Self {
98 // There is 1:1 mapping between `fio::Operations` and `fio::Flags`.
99 let mut flags = fio::Flags::from_bits_truncate(options.rights.bits());
100 if options.is_append {
101 flags |= fio::Flags::FILE_APPEND;
102 }
103 flags | fio::Flags::PROTOCOL_FILE
104 }
105}
106
107#[derive(Default, PartialEq)]
108pub enum SyncMode {
109 /// Used when the Sync fuchsia.io method is used.
110 #[default]
111 Normal,
112
113 /// Used when the connection is about to be closed. Typically this will involve flushing data
114 /// from caches, but performance is a consideration, so it should only perform what might be
115 /// necessary for closing the file. If anything *must* happen when a file is closed, it must be
116 /// implemented in the `Node::close` function, not here; a call to sync with this mode is not
117 /// guaranteed and not implementing/supporting it should have no effect on correctness. If
118 /// `Node::close` needs to flush data in an async context, it has to spawn a task. Supporting
119 /// this mode means that in most cases there's no need to spawn a task because there should be
120 /// nothing that needs to be flushed (but it must check). This will only be called if the
121 /// connection has write permissions; a connection that only has read permissions should not
122 /// have made any changes that need flushing.
123 PreClose,
124}
125
126/// Trait used for all files.
127pub trait File: Node {
128 /// Capabilities:
129 fn readable(&self) -> bool {
130 true
131 }
132 fn writable(&self) -> bool {
133 false
134 }
135 fn executable(&self) -> bool {
136 false
137 }
138
139 /// Called when the file is going to be accessed, typically by a new connection.
140 /// Flags is the same as the flags passed to `fidl_fuchsia_io.Node/Open`.
141 /// The following flags are handled by the connection and do not need to be handled inside
142 /// open():
143 /// * OPEN_FLAG_TRUNCATE - A call to truncate() will be made immediately after open().
144 /// * OPEN_FLAG_DESCRIBE - The OnOpen event is sent before any other requests are received from
145 /// the file's client.
146 fn open_file(&self, options: &FileOptions) -> impl Future<Output = Result<(), Status>> + Send;
147
148 /// Truncate the file to `length`.
149 /// If there are pending attributes to update (see `update_attributes`), they should also be
150 /// flushed at this time. Otherwise, no attributes should be updated, other than size as needed.
151 fn truncate(&self, length: u64) -> impl Future<Output = Result<(), Status>> + Send;
152
153 /// Get a VMO representing this file.
154 /// If not supported by the underlying filesystem, should return Err(NOT_SUPPORTED).
155 #[cfg(target_os = "fuchsia")]
156 fn get_backing_memory(
157 &self,
158 _flags: fio::VmoFlags,
159 ) -> impl Future<Output = Result<zx::Vmo, Status>> + Send {
160 ready(Err(Status::NOT_SUPPORTED))
161 }
162
163 /// Get the size of this file.
164 /// This is used to calculate seek offset relative to the end.
165 fn get_size(&self) -> impl Future<Output = Result<u64, Status>> + Send;
166
167 /// Set the mutable attributes of this file based on the values in `attributes`. If the file
168 /// does not support updating *all* of the specified attributes, implementations should fail
169 /// with `ZX_ERR_NOT_SUPPORTED`.
170 fn update_attributes(
171 &self,
172 attributes: fio::MutableNodeAttributes,
173 ) -> impl Future<Output = Result<(), Status>> + Send;
174
175 /// List this files extended attributes.
176 fn list_extended_attributes(
177 &self,
178 ) -> impl Future<Output = Result<Vec<Vec<u8>>, Status>> + Send {
179 ready(Err(Status::NOT_SUPPORTED))
180 }
181
182 /// Get the value for an extended attribute.
183 fn get_extended_attribute(
184 &self,
185 _name: Vec<u8>,
186 ) -> impl Future<Output = Result<Vec<u8>, Status>> + Send {
187 ready(Err(Status::NOT_SUPPORTED))
188 }
189
190 /// Set the value for an extended attribute.
191 fn set_extended_attribute(
192 &self,
193 _name: Vec<u8>,
194 _value: Vec<u8>,
195 _mode: fio::SetExtendedAttributeMode,
196 ) -> impl Future<Output = Result<(), Status>> + Send {
197 ready(Err(Status::NOT_SUPPORTED))
198 }
199
200 /// Remove the value for an extended attribute.
201 fn remove_extended_attribute(
202 &self,
203 _name: Vec<u8>,
204 ) -> impl Future<Output = Result<(), Status>> + Send {
205 ready(Err(Status::NOT_SUPPORTED))
206 }
207
208 /// Preallocate disk space for this range.
209 #[cfg(fuchsia_api_level_at_least = "HEAD")]
210 fn allocate(
211 &self,
212 _offset: u64,
213 _length: u64,
214 _mode: fio::AllocateMode,
215 ) -> impl Future<Output = Result<(), Status>> + Send {
216 ready(Err(Status::NOT_SUPPORTED))
217 }
218
219 /// Set the merkle tree and the descriptor for this file and mark the file as fsverity-enabled.
220 #[cfg(fuchsia_api_level_at_least = "HEAD")]
221 fn enable_verity(
222 &self,
223 _options: fio::VerificationOptions,
224 ) -> impl Future<Output = Result<(), Status>> + Send {
225 ready(Err(Status::NOT_SUPPORTED))
226 }
227
228 /// Sync this file's contents to the storage medium (probably disk).
229 /// This does not necessarily guarantee that the file will be completely written to disk once
230 /// the call returns. It merely guarantees that any changes to the file have been propagated
231 /// to the next layer in the storage stack.
232 fn sync(&self, mode: SyncMode) -> impl Future<Output = Result<(), Status>> + Send;
233}
234
235// Trait for handling reads and writes to a file. Files that support Streams should handle reads and
236// writes via a Pager instead of implementing this trait.
237pub trait FileIo: Send + Sync {
238 /// Read at most |buffer.len()| bytes starting at |offset| into |buffer|. The function may read
239 /// less than |count| bytes and still return success, in which case read_at returns the number
240 /// of bytes read into |buffer|.
241 fn read_at(
242 &self,
243 offset: u64,
244 buffer: &mut [u8],
245 ) -> impl Future<Output = Result<u64, Status>> + Send;
246
247 /// Write |content| starting at |offset|, returning the number of bytes that were successfully
248 /// written.
249 ///
250
251 /// If there are pending attributes to update (see `update_attributes`), they should also be
252 /// flushed at this time. Otherwise, no attributes should be updated, other than size as needed.
253 fn write_at(
254 &self,
255 offset: u64,
256 content: &[u8],
257 ) -> impl Future<Output = Result<u64, Status>> + Send;
258
259 /// Appends |content| returning, if successful, the number of bytes written, and the file offset
260 /// after writing. Implementations should make the writes atomic, so in the event that multiple
261 /// requests to append are in-flight, it should appear that the two writes are applied in
262 /// sequence.
263 ///
264 /// If there are pending attributes to update (see `update_attributes`), they should also be
265 /// flushed at this time. Otherwise, no attributes should be updated, other than size as needed.
266 fn append(&self, content: &[u8]) -> impl Future<Output = Result<(u64, u64), Status>> + Send;
267}
268
269/// Trait for dispatching read, write, and seek FIDL requests for a given connection. The
270/// implementer of this trait is responsible for maintaining the per connection state.
271///
272/// Files that support Streams should handle reads and writes via a Pager instead of implementing
273/// this trait.
274pub trait RawFileIoConnection: Send + Sync {
275 /// Reads at most `count` bytes from the file starting at the connection's seek offset and
276 /// advances the seek offset.
277 fn read(&self, count: u64) -> impl Future<Output = Result<Vec<u8>, Status>> + Send;
278
279 /// Reads `count` bytes from the file starting at `offset`.
280 fn read_at(
281 &self,
282 offset: u64,
283 count: u64,
284 ) -> impl Future<Output = Result<Vec<u8>, Status>> + Send;
285
286 /// Writes `data` to the file starting at the connect's seek offset and advances the seek
287 /// offset. If the connection is in append mode then the seek offset is moved to the end of the
288 /// file before writing. Returns the number of bytes written.
289 fn write(&self, data: &[u8]) -> impl Future<Output = Result<u64, Status>> + Send;
290
291 /// Writes `data` to the file starting at `offset`. Returns the number of bytes written.
292 fn write_at(
293 &self,
294 offset: u64,
295 data: &[u8],
296 ) -> impl Future<Output = Result<u64, Status>> + Send;
297
298 /// Modifies the connection's seek offset. Returns the connections new seek offset.
299 fn seek(
300 &self,
301 offset: i64,
302 origin: fio::SeekOrigin,
303 ) -> impl Future<Output = Result<u64, Status>> + Send;
304
305 /// Notifies the `IoOpHandler` that the flags of the connection have changed.
306 fn set_flags(&self, flags: fio::Flags) -> Result<(), Status>;
307}
308
309pub trait FileLike: Node {
310 fn open(
311 self: Arc<Self>,
312 scope: ExecutionScope,
313 options: FileOptions,
314 object_request: ObjectRequestRef<'_>,
315 ) -> Result<(), Status>;
316}
317
318/// Helper to open a file or node as required.
319pub fn serve(
320 file: Arc<impl FileLike>,
321 scope: ExecutionScope,
322 protocols: &impl ProtocolsExt,
323 object_request: ObjectRequestRef<'_>,
324) -> Result<(), Status> {
325 if protocols.is_node() {
326 let options = protocols.to_node_options(file.entry_info().type_())?;
327 file.open_as_node(scope, options, object_request)
328 } else {
329 file.open(scope, protocols.to_file_options()?, object_request)
330 }
331}
332
333/// Serve the provided file object on a new execution scope with `flags`.
334pub fn serve_proxy(file: Arc<impl FileLike>, flags: fio::Flags) -> fio::FileProxy {
335 let (proxy, server) = fidl::endpoints::create_proxy::<fio::FileMarker>();
336 let request = flags.to_object_request(server);
337 request.handle(|request| serve(file, ExecutionScope::new(), &flags, request));
338 proxy
339}