1 //! WASI-specific extensions to primitives in the `std::fs` module.
3 #![deny(unsafe_op_in_unsafe_fn)]
4 #![unstable(feature = "wasi_ext", issue = "none")]
7 use crate::fs::{self, File, Metadata, OpenOptions};
8 use crate::io::{self, IoSlice, IoSliceMut};
9 use crate::path::{Path, PathBuf};
10 use crate::sys_common::{AsInner, AsInnerMut, FromInner};
11 // Used for `File::read` on intra-doc links
12 #[allow(unused_imports)]
13 use io::{Read, Write};
15 /// WASI-specific extensions to [`File`].
17 /// Reads a number of bytes starting from a given offset.
19 /// Returns the number of bytes read.
21 /// The offset is relative to the start of the file and thus independent
22 /// from the current cursor.
24 /// The current file cursor is not affected by this function.
26 /// Note that similar to [`File::read`], it is not an error to return with a
28 fn read_at(&self, buf: &mut [u8], offset: u64) -> io::Result<usize> {
29 let bufs = &mut [IoSliceMut::new(buf)];
30 self.read_vectored_at(bufs, offset)
33 /// Reads a number of bytes starting from a given offset.
35 /// Returns the number of bytes read.
37 /// The offset is relative to the start of the file and thus independent
38 /// from the current cursor.
40 /// The current file cursor is not affected by this function.
42 /// Note that similar to [`File::read_vectored`], it is not an error to
43 /// return with a short read.
44 fn read_vectored_at(&self, bufs: &mut [IoSliceMut<'_>], offset: u64) -> io::Result<usize>;
46 /// Reads the exact number of byte required to fill `buf` from the given offset.
48 /// The offset is relative to the start of the file and thus independent
49 /// from the current cursor.
51 /// The current file cursor is not affected by this function.
53 /// Similar to [`Read::read_exact`] but uses [`read_at`] instead of `read`.
55 /// [`read_at`]: FileExt::read_at
59 /// If this function encounters an error of the kind
60 /// [`io::ErrorKind::Interrupted`] then the error is ignored and the operation
63 /// If this function encounters an "end of file" before completely filling
64 /// the buffer, it returns an error of the kind [`io::ErrorKind::UnexpectedEof`].
65 /// The contents of `buf` are unspecified in this case.
67 /// If any other read error is encountered then this function immediately
68 /// returns. The contents of `buf` are unspecified in this case.
70 /// If this function returns an error, it is unspecified how many bytes it
71 /// has read, but it will never read more than would be necessary to
72 /// completely fill the buffer.
73 #[stable(feature = "rw_exact_all_at", since = "1.33.0")]
74 fn read_exact_at(&self, mut buf: &mut [u8], mut offset: u64) -> io::Result<()> {
75 while !buf.is_empty() {
76 match self.read_at(buf, offset) {
83 Err(ref e) if e.kind() == io::ErrorKind::Interrupted => {}
84 Err(e) => return Err(e),
88 Err(io::Error::new_const(io::ErrorKind::UnexpectedEof, &"failed to fill whole buffer"))
94 /// Writes a number of bytes starting from a given offset.
96 /// Returns the number of bytes written.
98 /// The offset is relative to the start of the file and thus independent
99 /// from the current cursor.
101 /// The current file cursor is not affected by this function.
103 /// When writing beyond the end of the file, the file is appropriately
104 /// extended and the intermediate bytes are initialized with the value 0.
106 /// Note that similar to [`File::write`], it is not an error to return a
108 fn write_at(&self, buf: &[u8], offset: u64) -> io::Result<usize> {
109 let bufs = &[IoSlice::new(buf)];
110 self.write_vectored_at(bufs, offset)
113 /// Writes a number of bytes starting from a given offset.
115 /// Returns the number of bytes written.
117 /// The offset is relative to the start of the file and thus independent
118 /// from the current cursor.
120 /// The current file cursor is not affected by this function.
122 /// When writing beyond the end of the file, the file is appropriately
123 /// extended and the intermediate bytes are initialized with the value 0.
125 /// Note that similar to [`File::write_vectored`], it is not an error to return a
127 fn write_vectored_at(&self, bufs: &[IoSlice<'_>], offset: u64) -> io::Result<usize>;
129 /// Attempts to write an entire buffer starting from a given offset.
131 /// The offset is relative to the start of the file and thus independent
132 /// from the current cursor.
134 /// The current file cursor is not affected by this function.
136 /// This method will continuously call [`write_at`] until there is no more data
137 /// to be written or an error of non-[`io::ErrorKind::Interrupted`] kind is
138 /// returned. This method will not return until the entire buffer has been
139 /// successfully written or such an error occurs. The first error that is
140 /// not of [`io::ErrorKind::Interrupted`] kind generated from this method will be
145 /// This function will return the first error of
146 /// non-[`io::ErrorKind::Interrupted`] kind that [`write_at`] returns.
148 /// [`write_at`]: FileExt::write_at
149 #[stable(feature = "rw_exact_all_at", since = "1.33.0")]
150 fn write_all_at(&self, mut buf: &[u8], mut offset: u64) -> io::Result<()> {
151 while !buf.is_empty() {
152 match self.write_at(buf, offset) {
154 return Err(io::Error::new_const(
155 io::ErrorKind::WriteZero,
156 &"failed to write whole buffer",
163 Err(ref e) if e.kind() == io::ErrorKind::Interrupted => {}
164 Err(e) => return Err(e),
170 /// Returns the current position within the file.
172 /// This corresponds to the `fd_tell` syscall and is similar to
173 /// `seek` where you offset 0 bytes from the current position.
174 fn tell(&self) -> io::Result<u64>;
176 /// Adjust the flags associated with this file.
178 /// This corresponds to the `fd_fdstat_set_flags` syscall.
179 fn fdstat_set_flags(&self, flags: u16) -> io::Result<()>;
181 /// Adjust the rights associated with this file.
183 /// This corresponds to the `fd_fdstat_set_rights` syscall.
184 fn fdstat_set_rights(&self, rights: u64, inheriting: u64) -> io::Result<()>;
186 /// Provide file advisory information on a file descriptor.
188 /// This corresponds to the `fd_advise` syscall.
189 fn advise(&self, offset: u64, len: u64, advice: u8) -> io::Result<()>;
191 /// Force the allocation of space in a file.
193 /// This corresponds to the `fd_allocate` syscall.
194 fn allocate(&self, offset: u64, len: u64) -> io::Result<()>;
196 /// Create a directory.
198 /// This corresponds to the `path_create_directory` syscall.
199 fn create_directory<P: AsRef<Path>>(&self, dir: P) -> io::Result<()>;
201 /// Read the contents of a symbolic link.
203 /// This corresponds to the `path_readlink` syscall.
204 fn read_link<P: AsRef<Path>>(&self, path: P) -> io::Result<PathBuf>;
206 /// Return the attributes of a file or directory.
208 /// This corresponds to the `path_filestat_get` syscall.
209 fn metadata_at<P: AsRef<Path>>(&self, lookup_flags: u32, path: P) -> io::Result<Metadata>;
213 /// This corresponds to the `path_unlink_file` syscall.
214 fn remove_file<P: AsRef<Path>>(&self, path: P) -> io::Result<()>;
216 /// Remove a directory.
218 /// This corresponds to the `path_remove_directory` syscall.
219 fn remove_directory<P: AsRef<Path>>(&self, path: P) -> io::Result<()>;
222 // FIXME: bind fd_fdstat_get - need to define a custom return type
223 // FIXME: bind fd_readdir - can't return `ReadDir` since we only have entry name
224 // FIXME: bind fd_filestat_set_times maybe? - on crates.io for unix
225 // FIXME: bind path_filestat_set_times maybe? - on crates.io for unix
226 // FIXME: bind poll_oneoff maybe? - probably should wait for I/O to settle
227 // FIXME: bind random_get maybe? - on crates.io for unix
229 impl FileExt for fs::File {
230 fn read_vectored_at(&self, bufs: &mut [IoSliceMut<'_>], offset: u64) -> io::Result<usize> {
231 self.as_inner().fd().pread(bufs, offset)
234 fn write_vectored_at(&self, bufs: &[IoSlice<'_>], offset: u64) -> io::Result<usize> {
235 self.as_inner().fd().pwrite(bufs, offset)
238 fn tell(&self) -> io::Result<u64> {
239 self.as_inner().fd().tell()
242 fn fdstat_set_flags(&self, flags: u16) -> io::Result<()> {
243 self.as_inner().fd().set_flags(flags)
246 fn fdstat_set_rights(&self, rights: u64, inheriting: u64) -> io::Result<()> {
247 self.as_inner().fd().set_rights(rights, inheriting)
250 fn advise(&self, offset: u64, len: u64, advice: u8) -> io::Result<()> {
251 self.as_inner().fd().advise(offset, len, advice)
254 fn allocate(&self, offset: u64, len: u64) -> io::Result<()> {
255 self.as_inner().fd().allocate(offset, len)
258 fn create_directory<P: AsRef<Path>>(&self, dir: P) -> io::Result<()> {
259 self.as_inner().fd().create_directory(osstr2str(dir.as_ref().as_ref())?)
262 fn read_link<P: AsRef<Path>>(&self, path: P) -> io::Result<PathBuf> {
263 self.as_inner().read_link(path.as_ref())
266 fn metadata_at<P: AsRef<Path>>(&self, lookup_flags: u32, path: P) -> io::Result<Metadata> {
267 let m = self.as_inner().metadata_at(lookup_flags, path.as_ref())?;
268 Ok(FromInner::from_inner(m))
271 fn remove_file<P: AsRef<Path>>(&self, path: P) -> io::Result<()> {
272 self.as_inner().fd().unlink_file(osstr2str(path.as_ref().as_ref())?)
275 fn remove_directory<P: AsRef<Path>>(&self, path: P) -> io::Result<()> {
276 self.as_inner().fd().remove_directory(osstr2str(path.as_ref().as_ref())?)
280 /// WASI-specific extensions to [`fs::OpenOptions`].
281 pub trait OpenOptionsExt {
282 /// Pass custom `dirflags` argument to `path_open`.
284 /// This option configures the `dirflags` argument to the
285 /// `path_open` syscall which `OpenOptions` will eventually call. The
286 /// `dirflags` argument configures how the file is looked up, currently
287 /// primarily affecting whether symlinks are followed or not.
289 /// By default this value is `__WASI_LOOKUP_SYMLINK_FOLLOW`, or symlinks are
290 /// followed. You can call this method with 0 to disable following symlinks
291 fn lookup_flags(&mut self, flags: u32) -> &mut Self;
293 /// Indicates whether `OpenOptions` must open a directory or not.
295 /// This method will configure whether the `__WASI_O_DIRECTORY` flag is
296 /// passed when opening a file. When passed it will require that the opened
297 /// path is a directory.
299 /// This option is by default `false`
300 fn directory(&mut self, dir: bool) -> &mut Self;
302 /// Indicates whether `__WASI_FDFLAG_DSYNC` is passed in the `fs_flags`
303 /// field of `path_open`.
305 /// This option is by default `false`
306 fn dsync(&mut self, dsync: bool) -> &mut Self;
308 /// Indicates whether `__WASI_FDFLAG_NONBLOCK` is passed in the `fs_flags`
309 /// field of `path_open`.
311 /// This option is by default `false`
312 fn nonblock(&mut self, nonblock: bool) -> &mut Self;
314 /// Indicates whether `__WASI_FDFLAG_RSYNC` is passed in the `fs_flags`
315 /// field of `path_open`.
317 /// This option is by default `false`
318 fn rsync(&mut self, rsync: bool) -> &mut Self;
320 /// Indicates whether `__WASI_FDFLAG_SYNC` is passed in the `fs_flags`
321 /// field of `path_open`.
323 /// This option is by default `false`
324 fn sync(&mut self, sync: bool) -> &mut Self;
326 /// Indicates the value that should be passed in for the `fs_rights_base`
327 /// parameter of `path_open`.
329 /// This option defaults based on the `read` and `write` configuration of
330 /// this `OpenOptions` builder. If this method is called, however, the
331 /// exact mask passed in will be used instead.
332 fn fs_rights_base(&mut self, rights: u64) -> &mut Self;
334 /// Indicates the value that should be passed in for the
335 /// `fs_rights_inheriting` parameter of `path_open`.
337 /// The default for this option is the same value as what will be passed
338 /// for the `fs_rights_base` parameter but if this method is called then
339 /// the specified value will be used instead.
340 fn fs_rights_inheriting(&mut self, rights: u64) -> &mut Self;
342 /// Open a file or directory.
344 /// This corresponds to the `path_open` syscall.
345 fn open_at<P: AsRef<Path>>(&self, file: &File, path: P) -> io::Result<File>;
348 impl OpenOptionsExt for OpenOptions {
349 fn lookup_flags(&mut self, flags: u32) -> &mut OpenOptions {
350 self.as_inner_mut().lookup_flags(flags);
354 fn directory(&mut self, dir: bool) -> &mut OpenOptions {
355 self.as_inner_mut().directory(dir);
359 fn dsync(&mut self, enabled: bool) -> &mut OpenOptions {
360 self.as_inner_mut().dsync(enabled);
364 fn nonblock(&mut self, enabled: bool) -> &mut OpenOptions {
365 self.as_inner_mut().nonblock(enabled);
369 fn rsync(&mut self, enabled: bool) -> &mut OpenOptions {
370 self.as_inner_mut().rsync(enabled);
374 fn sync(&mut self, enabled: bool) -> &mut OpenOptions {
375 self.as_inner_mut().sync(enabled);
379 fn fs_rights_base(&mut self, rights: u64) -> &mut OpenOptions {
380 self.as_inner_mut().fs_rights_base(rights);
384 fn fs_rights_inheriting(&mut self, rights: u64) -> &mut OpenOptions {
385 self.as_inner_mut().fs_rights_inheriting(rights);
389 fn open_at<P: AsRef<Path>>(&self, file: &File, path: P) -> io::Result<File> {
390 let inner = file.as_inner().open_at(path.as_ref(), self.as_inner())?;
391 Ok(File::from_inner(inner))
395 /// WASI-specific extensions to [`fs::Metadata`].
396 pub trait MetadataExt {
397 /// Returns the `st_dev` field of the internal `filestat_t`
398 fn dev(&self) -> u64;
399 /// Returns the `st_ino` field of the internal `filestat_t`
400 fn ino(&self) -> u64;
401 /// Returns the `st_nlink` field of the internal `filestat_t`
402 fn nlink(&self) -> u64;
403 /// Returns the `st_size` field of the internal `filestat_t`
404 fn size(&self) -> u64;
405 /// Returns the `st_atim` field of the internal `filestat_t`
406 fn atim(&self) -> u64;
407 /// Returns the `st_mtim` field of the internal `filestat_t`
408 fn mtim(&self) -> u64;
409 /// Returns the `st_ctim` field of the internal `filestat_t`
410 fn ctim(&self) -> u64;
413 impl MetadataExt for fs::Metadata {
414 fn dev(&self) -> u64 {
415 self.as_inner().as_wasi().dev
417 fn ino(&self) -> u64 {
418 self.as_inner().as_wasi().ino
420 fn nlink(&self) -> u64 {
421 self.as_inner().as_wasi().nlink
423 fn size(&self) -> u64 {
424 self.as_inner().as_wasi().size
426 fn atim(&self) -> u64 {
427 self.as_inner().as_wasi().atim
429 fn mtim(&self) -> u64 {
430 self.as_inner().as_wasi().mtim
432 fn ctim(&self) -> u64 {
433 self.as_inner().as_wasi().ctim
437 /// WASI-specific extensions for [`fs::FileType`].
439 /// Adds support for special WASI file types such as block/character devices,
440 /// pipes, and sockets.
441 pub trait FileTypeExt {
442 /// Returns `true` if this file type is a block device.
443 fn is_block_device(&self) -> bool;
444 /// Returns `true` if this file type is a character device.
445 fn is_character_device(&self) -> bool;
446 /// Returns `true` if this file type is a socket datagram.
447 fn is_socket_dgram(&self) -> bool;
448 /// Returns `true` if this file type is a socket stream.
449 fn is_socket_stream(&self) -> bool;
452 impl FileTypeExt for fs::FileType {
453 fn is_block_device(&self) -> bool {
454 self.as_inner().bits() == wasi::FILETYPE_BLOCK_DEVICE
456 fn is_character_device(&self) -> bool {
457 self.as_inner().bits() == wasi::FILETYPE_CHARACTER_DEVICE
459 fn is_socket_dgram(&self) -> bool {
460 self.as_inner().bits() == wasi::FILETYPE_SOCKET_DGRAM
462 fn is_socket_stream(&self) -> bool {
463 self.as_inner().bits() == wasi::FILETYPE_SOCKET_STREAM
467 /// WASI-specific extension methods for [`fs::DirEntry`].
468 pub trait DirEntryExt {
469 /// Returns the underlying `d_ino` field of the `dirent_t`
470 fn ino(&self) -> u64;
473 impl DirEntryExt for fs::DirEntry {
474 fn ino(&self) -> u64 {
475 self.as_inner().ino()
479 /// Create a hard link.
481 /// This corresponds to the `path_link` syscall.
482 pub fn link<P: AsRef<Path>, U: AsRef<Path>>(
488 ) -> io::Result<()> {
489 old_fd.as_inner().fd().link(
491 osstr2str(old_path.as_ref().as_ref())?,
492 new_fd.as_inner().fd(),
493 osstr2str(new_path.as_ref().as_ref())?,
497 /// Rename a file or directory.
499 /// This corresponds to the `path_rename` syscall.
500 pub fn rename<P: AsRef<Path>, U: AsRef<Path>>(
505 ) -> io::Result<()> {
506 old_fd.as_inner().fd().rename(
507 osstr2str(old_path.as_ref().as_ref())?,
508 new_fd.as_inner().fd(),
509 osstr2str(new_path.as_ref().as_ref())?,
513 /// Create a symbolic link.
515 /// This corresponds to the `path_symlink` syscall.
516 pub fn symlink<P: AsRef<Path>, U: AsRef<Path>>(
520 ) -> io::Result<()> {
523 .symlink(osstr2str(old_path.as_ref().as_ref())?, osstr2str(new_path.as_ref().as_ref())?)
526 /// Create a symbolic link.
528 /// This is a convenience API similar to `std::os::unix::fs::symlink` and
529 /// `std::os::windows::fs::symlink_file` and `std::os::windows::fs::symlink_dir`.
530 pub fn symlink_path<P: AsRef<Path>, U: AsRef<Path>>(old_path: P, new_path: U) -> io::Result<()> {
531 crate::sys::fs::symlink(old_path.as_ref(), new_path.as_ref())
534 fn osstr2str(f: &OsStr) -> io::Result<&str> {
536 .ok_or_else(|| io::Error::new_const(io::ErrorKind::Uncategorized, &"input must be utf-8"))