Skip to main content

fuser_ng/async/
types.rs

1//! Asynchronous filesystem interface and its FUSE adapter.
2
3use std::ffi::OsString;
4use std::future::Future;
5use std::path::PathBuf;
6use std::pin::Pin;
7use std::task::{Context, Poll};
8use std::time::SystemTime;
9
10use futures_core::Stream;
11
12use crate::{
13    EntryName, EntryRef, KernelConfig, RequestInfo, ResolvedPath, ResultCreate, ResultData,
14    ResultEmpty, ResultEntry, ResultOpen, ResultReaddirBatch, ResultStatfs, ResultWrite,
15    ResultXattr,
16};
17
18#[cfg(feature = "legacy_readdir")]
19use crate::ResultLegacyReaddirBatch;
20
21#[cfg(target_os = "macos")]
22use crate::ResultXTimes;
23
24/// A stream that yields one value.
25struct Once<T>(Option<T>);
26
27impl<T: Unpin> Stream for Once<T> {
28    type Item = T;
29
30    fn poll_next(mut self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
31        Poll::Ready(self.0.take())
32    }
33}
34
35/// Returns an immediately ready unsupported-operation result.
36fn enosys_future<T>() -> std::future::Ready<std::io::Result<T>> {
37    std::future::ready(Err(std::io::Error::from_raw_os_error(libc::ENOSYS)))
38}
39
40/// Filesystem operations that may complete asynchronously.
41///
42/// Operation arguments are owned so their futures can outlive the FUSE request callback.
43#[allow(unused_variables)]
44pub trait AsyncFilesystem: Send + Sync + 'static {
45    /// Called when the filesystem is mounted, before any other operation.
46    ///
47    /// * req: information about the FUSE request.
48    /// * config: kernel configuration that may be adjusted before mounting.
49    fn init(&self, req: RequestInfo, config: &mut KernelConfig) -> ResultEmpty {
50        Ok(())
51    }
52
53    /// Called when the filesystem is unmounted.
54    fn destroy(&self) {}
55
56    /// Get the attributes of a filesystem entry.
57    ///
58    /// * req: information about the FUSE request.
59    /// * path: path to the entry.
60    /// * fh: a file handle if this is called on an open file.
61    fn getattr(
62        &self,
63        req: RequestInfo,
64        path: EntryRef,
65        fh: Option<u64>,
66    ) -> impl Future<Output = ResultEntry> + Send {
67        enosys_future()
68    }
69
70    /// Change the mode of a filesystem entry.
71    ///
72    /// * req: information about the FUSE request.
73    /// * path: path to the entry.
74    /// * fh: a file handle if this is called on an open file.
75    /// * mode: the mode to change the file to.
76    fn chmod(
77        &self,
78        req: RequestInfo,
79        path: ResolvedPath,
80        fh: Option<u64>,
81        mode: u32,
82    ) -> impl Future<Output = ResultEmpty> + Send {
83        enosys_future()
84    }
85
86    /// Change the owner UID and/or group GID of a filesystem entry.
87    ///
88    /// * req: information about the FUSE request.
89    /// * path: path to the entry.
90    /// * fh: a file handle if this is called on an open file.
91    /// * uid: new user ID for the file owner. If None, leave the UID unchanged.
92    /// * gid: new group ID for the file. If None, leave the GID unchanged.
93    fn chown(
94        &self,
95        req: RequestInfo,
96        path: ResolvedPath,
97        fh: Option<u64>,
98        uid: Option<u32>,
99        gid: Option<u32>,
100    ) -> impl Future<Output = ResultEmpty> + Send {
101        enosys_future()
102    }
103
104    /// Set the length of a file.
105    ///
106    /// * req: information about the FUSE request.
107    /// * path: path to the file.
108    /// * fh: a file handle if this is called on an open file.
109    /// * size: new file length in bytes.
110    fn truncate(
111        &self,
112        req: RequestInfo,
113        path: ResolvedPath,
114        fh: Option<u64>,
115        size: u64,
116    ) -> impl Future<Output = ResultEmpty> + Send {
117        enosys_future()
118    }
119
120    /// Set the timestamps of a filesystem entry.
121    ///
122    /// * req: information about the FUSE request.
123    /// * path: path to the entry.
124    /// * fh: a file handle if this is called on an open file.
125    /// * atime: new access time, or None to leave it unchanged.
126    /// * mtime: new modification time, or None to leave it unchanged.
127    fn utimens(
128        &self,
129        req: RequestInfo,
130        path: ResolvedPath,
131        fh: Option<u64>,
132        atime: Option<SystemTime>,
133        mtime: Option<SystemTime>,
134    ) -> impl Future<Output = ResultEmpty> + Send {
135        enosys_future()
136    }
137
138    /// Set the timestamps of a filesystem entry using the additional macOS options.
139    ///
140    /// * req: information about the FUSE request.
141    /// * path: path to the entry.
142    /// * fh: a file handle if this is called on an open file.
143    /// * crtime: new creation time, or None to leave it unchanged.
144    /// * chgtime: new metadata change time, or None to leave it unchanged.
145    /// * bkuptime: new backup time, or None to leave it unchanged.
146    /// * flags: new macOS file flags, or None to leave them unchanged.
147    #[allow(clippy::too_many_arguments)]
148    fn utimens_macos(
149        &self,
150        req: RequestInfo,
151        path: ResolvedPath,
152        fh: Option<u64>,
153        crtime: Option<SystemTime>,
154        chgtime: Option<SystemTime>,
155        bkuptime: Option<SystemTime>,
156        flags: Option<u32>,
157    ) -> impl Future<Output = ResultEmpty> + Send {
158        enosys_future()
159    }
160
161    /// Read a symbolic link.
162    ///
163    /// * req: information about the FUSE request.
164    /// * path: path to the symbolic link.
165    fn readlink(
166        &self,
167        req: RequestInfo,
168        path: ResolvedPath,
169    ) -> impl Future<Output = ResultData> + Send {
170        enosys_future()
171    }
172
173    /// Create a special file.
174    ///
175    /// * req: information about the FUSE request.
176    /// * entry: entry name resolved relative to its parent directory.
177    /// * mode: mode for the new entry.
178    /// * rdev: device number when mode contains S_IFCHR or S_IFBLK; ignored otherwise.
179    fn mknod(
180        &self,
181        req: RequestInfo,
182        entry: EntryName,
183        mode: u32,
184        rdev: u32,
185    ) -> impl Future<Output = ResultEntry> + Send {
186        enosys_future()
187    }
188
189    /// Create a directory.
190    ///
191    /// * req: information about the FUSE request.
192    /// * entry: directory name resolved relative to its parent directory.
193    /// * mode: permissions for the new directory.
194    fn mkdir(
195        &self,
196        req: RequestInfo,
197        entry: EntryName,
198        mode: u32,
199    ) -> impl Future<Output = ResultEntry> + Send {
200        enosys_future()
201    }
202
203    /// Remove a file.
204    ///
205    /// * req: information about the FUSE request.
206    /// * entry: file name resolved relative to its parent directory.
207    fn unlink(
208        &self,
209        req: RequestInfo,
210        entry: EntryName,
211    ) -> impl Future<Output = ResultEmpty> + Send {
212        enosys_future()
213    }
214
215    /// Remove a directory.
216    ///
217    /// * req: information about the FUSE request.
218    /// * entry: directory name resolved relative to its parent directory.
219    fn rmdir(
220        &self,
221        req: RequestInfo,
222        entry: EntryName,
223    ) -> impl Future<Output = ResultEmpty> + Send {
224        enosys_future()
225    }
226
227    /// Create a symbolic link.
228    ///
229    /// * req: information about the FUSE request.
230    /// * entry: symbolic link name resolved relative to its parent directory.
231    /// * target: path (may be relative or absolute) to the target of the link.
232    fn symlink(
233        &self,
234        req: RequestInfo,
235        entry: EntryName,
236        target: PathBuf,
237    ) -> impl Future<Output = ResultEntry> + Send {
238        enosys_future()
239    }
240
241    /// Rename a filesystem entry.
242    ///
243    /// * req: information about the FUSE request.
244    /// * entry: current entry name resolved relative to its parent directory.
245    /// * new_entry: new entry name resolved relative to its parent directory.
246    fn rename(
247        &self,
248        req: RequestInfo,
249        entry: EntryName,
250        new_entry: EntryName,
251    ) -> impl Future<Output = ResultEmpty> + Send {
252        enosys_future()
253    }
254
255    /// Create a hard link.
256    ///
257    /// * req: information about the FUSE request.
258    /// * path: path to an existing file.
259    /// * new_entry: new link name resolved relative to its parent directory.
260    fn link(
261        &self,
262        req: RequestInfo,
263        path: ResolvedPath,
264        new_entry: EntryName,
265    ) -> impl Future<Output = ResultEntry> + Send {
266        enosys_future()
267    }
268
269    /// Open a file.
270    ///
271    /// * req: information about the FUSE request.
272    /// * path: path to the file.
273    /// * flags: one of O_RDONLY, O_WRONLY, or O_RDWR, plus any additional flags.
274    ///
275    /// Return a tuple of (file handle, flags). The file handle will be passed to any subsequent
276    /// calls that operate on the file, and can be any value you choose, though it should allow
277    /// your filesystem to identify the open file even without path information.
278    fn open(
279        &self,
280        req: RequestInfo,
281        path: ResolvedPath,
282        flags: u32,
283    ) -> impl Future<Output = ResultOpen> + Send {
284        enosys_future()
285    }
286
287    /// Read from a file.
288    ///
289    /// Reading past the end of the file is not an error. Return only the available data up to the
290    /// end of the file, which may be fewer bytes than requested or even zero bytes. Do not extend
291    /// the file in this case.
292    ///
293    /// * req: information about the FUSE request.
294    /// * path: path to the file.
295    /// * fh: file handle returned from the open call.
296    /// * offset: offset into the file to start reading.
297    /// * size: number of bytes to read.
298    fn read(
299        &self,
300        req: RequestInfo,
301        path: ResolvedPath,
302        fh: u64,
303        offset: u64,
304        size: u32,
305    ) -> impl Future<Output = ResultData> + Send {
306        enosys_future()
307    }
308
309    /// Write to a file.
310    ///
311    /// * req: information about the FUSE request.
312    /// * path: path to the file.
313    /// * fh: file handle returned from the open call.
314    /// * offset: offset into the file to start writing.
315    /// * data: data to write.
316    /// * flags: file open flags.
317    ///
318    /// Return the number of bytes written.
319    fn write(
320        &self,
321        req: RequestInfo,
322        path: ResolvedPath,
323        fh: u64,
324        offset: u64,
325        data: Vec<u8>,
326        flags: u32,
327    ) -> impl Future<Output = ResultWrite> + Send {
328        enosys_future()
329    }
330
331    /// Called each time a program calls close on an open file.
332    ///
333    /// Note that because file descriptors can be duplicated (by dup, dup2, fork) this may be
334    /// called multiple times for a given file handle. The main use of this function is if the
335    /// filesystem would like to return an error to the close call. Note that most programs
336    /// ignore the return value of close, though.
337    ///
338    /// * req: information about the FUSE request.
339    /// * path: path to the file.
340    /// * fh: file handle returned from the open call.
341    /// * lock_owner: if the filesystem supports locking (setlk, getlk), remove all locks
342    ///   belonging to this lock owner.
343    fn flush(
344        &self,
345        req: RequestInfo,
346        path: ResolvedPath,
347        fh: u64,
348        lock_owner: u64,
349    ) -> impl Future<Output = ResultEmpty> + Send {
350        enosys_future()
351    }
352
353    /// Called when an open file is closed.
354    ///
355    /// There will be one of these for each open call. After release, no more calls will be
356    /// made with the given file handle.
357    ///
358    /// * req: information about the FUSE request.
359    /// * path: path to the file.
360    /// * fh: file handle returned from the open call.
361    /// * flags: the flags passed when the file was opened.
362    /// * lock_owner: if the filesystem supports locking (setlk, getlk), remove all locks
363    ///   belonging to this lock owner.
364    /// * flush: whether pending data must be flushed or not.
365    #[allow(clippy::too_many_arguments)]
366    fn release(
367        &self,
368        req: RequestInfo,
369        path: ResolvedPath,
370        fh: u64,
371        flags: u32,
372        lock_owner: u64,
373        flush: bool,
374    ) -> impl Future<Output = ResultEmpty> + Send {
375        enosys_future()
376    }
377
378    /// Write out any pending changes to a file.
379    ///
380    /// When this returns, data should be written to persistent storage.
381    ///
382    /// * req: information about the FUSE request.
383    /// * path: path to the file.
384    /// * fh: file handle returned from the open call.
385    /// * datasync: if false, also write metadata; otherwise, write only file data.
386    fn fsync(
387        &self,
388        req: RequestInfo,
389        path: ResolvedPath,
390        fh: u64,
391        datasync: bool,
392    ) -> impl Future<Output = ResultEmpty> + Send {
393        enosys_future()
394    }
395
396    /// Open a directory.
397    ///
398    /// Analogous to the opendir call.
399    ///
400    /// * req: information about the FUSE request.
401    /// * path: path to the directory.
402    /// * flags: file access flags. Will contain O_DIRECTORY at least.
403    ///
404    /// Return a tuple of (file handle, flags). The file handle will be passed to any subsequent
405    /// calls that operate on the directory, and can be any value you choose, though it should
406    /// allow your filesystem to identify the open directory even without path information.
407    fn opendir(
408        &self,
409        req: RequestInfo,
410        path: ResolvedPath,
411        flags: u32,
412    ) -> impl Future<Output = ResultOpen> + Send {
413        enosys_future()
414    }
415
416    /// Gets directory entries together with their attributes.
417    ///
418    /// * req: information about the FUSE request.
419    /// * path: path to the directory.
420    /// * fh: file handle returned from the opendir call.
421    ///
422    /// Batching allows initial results to be returned before directory enumeration completes.
423    /// FuserNG deliberately retains consumed entries until releasedir so earlier offsets can be
424    /// replayed without restarting enumeration or repeating backend requests. This history
425    /// trades memory for fast replay; batching is intended to reduce result delivery latency.
426    fn readdir(
427        &self,
428        req: RequestInfo,
429        path: ResolvedPath,
430        fh: u64,
431    ) -> impl Stream<Item = ResultReaddirBatch> + Send + 'static {
432        Once(Some(Err(std::io::Error::from_raw_os_error(libc::ENOSYS))))
433    }
434
435    /// Gets directory entries without attributes for the legacy FUSE readdir operation.
436    ///
437    /// * req: information about the FUSE request.
438    /// * path: path to the directory.
439    /// * fh: file handle returned from the opendir call.
440    ///
441    /// Batching allows initial results to be returned before directory enumeration completes.
442    /// FuserNG deliberately retains consumed entries until releasedir so earlier offsets can be
443    /// replayed without restarting enumeration or repeating backend requests. This history
444    /// trades memory for fast replay; batching is intended to reduce result delivery latency.
445    #[cfg(feature = "legacy_readdir")]
446    fn legacy_readdir(
447        &self,
448        req: RequestInfo,
449        path: ResolvedPath,
450        fh: u64,
451    ) -> impl Stream<Item = ResultLegacyReaddirBatch> + Send + 'static {
452        Once(Some(Err(std::io::Error::from_raw_os_error(libc::ENOSYS))))
453    }
454
455    /// Close an open directory.
456    ///
457    /// This will be called exactly once for each opendir call.
458    ///
459    /// * req: information about the FUSE request.
460    /// * path: path to the directory.
461    /// * fh: file handle returned from the opendir call.
462    /// * flags: the file access flags passed to the opendir call.
463    fn releasedir(
464        &self,
465        req: RequestInfo,
466        path: ResolvedPath,
467        fh: u64,
468        flags: u32,
469    ) -> impl Future<Output = ResultEmpty> + Send {
470        enosys_future()
471    }
472
473    /// Write out any pending changes to a directory.
474    ///
475    /// Analogous to the fsync call.
476    ///
477    /// * req: information about the FUSE request.
478    /// * path: path to the directory.
479    /// * fh: file handle returned from the opendir call.
480    /// * datasync: if false, also write metadata; otherwise, write only directory data.
481    fn fsyncdir(
482        &self,
483        req: RequestInfo,
484        path: ResolvedPath,
485        fh: u64,
486        datasync: bool,
487    ) -> impl Future<Output = ResultEmpty> + Send {
488        enosys_future()
489    }
490
491    /// Get filesystem statistics.
492    ///
493    /// * req: information about the FUSE request.
494    /// * path: path to a directory in the filesystem.
495    ///
496    /// See the Statfs struct for more details.
497    fn statfs(
498        &self,
499        req: RequestInfo,
500        path: ResolvedPath,
501    ) -> impl Future<Output = ResultStatfs> + Send {
502        enosys_future()
503    }
504
505    /// Set an extended attribute on a file.
506    ///
507    /// * req: information about the FUSE request.
508    /// * path: path to the file.
509    /// * name: attribute name.
510    /// * value: the data to set the value to.
511    /// * flags: can be either XATTR_CREATE or XATTR_REPLACE.
512    /// * position: offset into the attribute value to write data.
513    #[allow(clippy::too_many_arguments)]
514    fn setxattr(
515        &self,
516        req: RequestInfo,
517        path: ResolvedPath,
518        name: OsString,
519        value: Vec<u8>,
520        flags: u32,
521        position: u32,
522    ) -> impl Future<Output = ResultEmpty> + Send {
523        enosys_future()
524    }
525
526    /// Get an extended attribute from a file.
527    ///
528    /// * req: information about the FUSE request.
529    /// * path: path to the file.
530    /// * name: attribute name.
531    /// * size: the maximum number of bytes to read.
532    ///
533    /// If size is 0, return Xattr::Size(n) where n is the size of the attribute data.
534    /// Otherwise, return Xattr::Data(data) with the requested data.
535    fn getxattr(
536        &self,
537        req: RequestInfo,
538        path: ResolvedPath,
539        name: OsString,
540        size: u32,
541    ) -> impl Future<Output = ResultXattr> + Send {
542        enosys_future()
543    }
544
545    /// List extended attributes for a file.
546    ///
547    /// * req: information about the FUSE request.
548    /// * path: path to the file.
549    /// * size: maximum number of bytes to return.
550    ///
551    /// If size is 0, return Xattr::Size(n) where n is the size required for the list of attribute
552    /// names. Otherwise, return Xattr::Data(data) where data is all the null-terminated attribute
553    /// names.
554    fn listxattr(
555        &self,
556        req: RequestInfo,
557        path: ResolvedPath,
558        size: u32,
559    ) -> impl Future<Output = ResultXattr> + Send {
560        enosys_future()
561    }
562
563    /// Remove an extended attribute from a file.
564    ///
565    /// * req: information about the FUSE request.
566    /// * path: path to the file.
567    /// * name: name of the attribute to remove.
568    fn removexattr(
569        &self,
570        req: RequestInfo,
571        path: ResolvedPath,
572        name: OsString,
573    ) -> impl Future<Output = ResultEmpty> + Send {
574        enosys_future()
575    }
576
577    /// Check for access to a file.
578    ///
579    /// * req: information about the FUSE request.
580    /// * path: path to the file.
581    /// * mask: mode bits to check for access to.
582    ///
583    /// Return Ok(()) if all requested permissions are allowed, otherwise return Err(EACCES)
584    /// or another appropriate error code (e.g. ENOENT if the file doesn't exist).
585    fn access(
586        &self,
587        req: RequestInfo,
588        path: ResolvedPath,
589        mask: u32,
590    ) -> impl Future<Output = ResultEmpty> + Send {
591        enosys_future()
592    }
593
594    /// Create and open a new file.
595    ///
596    /// * req: information about the FUSE request.
597    /// * path: path to the new file.
598    /// * mode: the mode to set on the new file.
599    /// * flags: flags that would be passed to open.
600    ///
601    /// Return a CreatedEntry containing the new file's attributes and a file handle. See the
602    /// documentation for open for more information about file handles.
603    fn create(
604        &self,
605        req: RequestInfo,
606        path: ResolvedPath,
607        mode: u32,
608        flags: u32,
609    ) -> impl Future<Output = ResultCreate> + Send {
610        enosys_future()
611    }
612
613    /// macOS only: Rename the volume.
614    ///
615    /// * req: information about the FUSE request.
616    /// * name: new name for the volume.
617    #[cfg(target_os = "macos")]
618    fn setvolname(
619        &self,
620        req: RequestInfo,
621        name: OsString,
622    ) -> impl Future<Output = ResultEmpty> + Send {
623        enosys_future()
624    }
625
626    /// macOS only: Query extended times (bkuptime and crtime).
627    ///
628    /// * req: information about the FUSE request.
629    /// * path: path to the file to get the times for.
630    ///
631    /// Return an XTimes struct containing the times, or an appropriate error.
632    #[cfg(target_os = "macos")]
633    fn getxtimes(
634        &self,
635        req: RequestInfo,
636        path: ResolvedPath,
637    ) -> impl Future<Output = ResultXTimes> + Send {
638        enosys_future()
639    }
640}