Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Expand the scope of std::fs #939

Open
alexcrichton opened this issue Mar 5, 2015 · 25 comments
Open

Expand the scope of std::fs #939

alexcrichton opened this issue Mar 5, 2015 · 25 comments
Labels
T-libs-api Relevant to the library API team, which will review and decide on the RFC.

Comments

@alexcrichton
Copy link
Member

Right now the API of std::fs is fairly conservative. In some places it may even be a little bit too conservative. After re-scrutinizing the API and looking at some others I've come to think that we may wish to act on expanding the surface area before 1.0. For now I'm opening this issue as a tracking issue for all known expansions to the std::fs API that are desired. I'll update the list below over time.

  • Metadata is a bit too opaque. There's lots of other information from the OS that we're getting, especially on unix. For example we're only providing a few fields of libc::stat and there should in theory be a method of accessing all of the internal fields.
  • Permissions is also quite opaque. Although there are platform-specific accessors, the accessed type may wish to change. Additionally, there should also be at least one cross-platform constructor of a Permissions structure.
  • File types are currently limited to is_file and is_dir accessors. There are many more file types on unix (and possibly on windows) which are not being exposed.
  • On unix one can create a directory with a specified mode, and on windows one can create a directory with a set of security attributes. Neither is currently possible with the create_dir APIs that we have. It would be nice to have something like CreateDirOptions as we have OpenOptions which is then extensible with platform-specific traits. Another example option, which C++ has, is to specify a "template directory" to draw permissions from.
  • DirEntry is quite conservative in only exposing a path accessor. For example on windows we could probably provide a metadata accessor at essentially no cost. There's also a bit of more free information we could expose on unix but it may be nice to have more cross-platform functionality as well. Another example of something we don't expose is just the filename itself Add get_entry_name function #927 (not the full pathname as joined from the initial call to read_dir).
  • copy is fairly simplistic and doesn't necessarily fit the bill for all use cases. It would be nice to have a CopyOptions structure to customize how a copy is done as well as supporting other operations like a recursive copy, copy-via-hard_link, copy-via-soft_link, etc.
  • With a lack of normalization on paths by default, it would be nice to have an analog of C++'s equivalent function which tests if two paths point to the same file.
  • Soft link (symlink) support is pretty lacking today. There is no method to get the metadata about a soft link (as opposed to the file that it points to) for example. It is also not currently possible to test whether a file is a soft link.
  • walk is not necessarily suitable for all cases and may desire a WalkOptions structure to configure how a walk is performed as well.
  • Binding realpath would be nice to have (resolving all soft links in a path) - #11857
  • Temporary files and directories are currently not implemented, and this space should at the very least be explored. Right now we have a tempdir crate on crates.io, but maybe it should be in std::fs? The possibilities of temporary files is also quite intriguing as well, especially on linux with O_TMPFILE for example.

To be clear I don't think that this red-hot-second is the time to pursue these changes. There are still many more APIs in the standard library which have a more pressing need for attention. I want to ensure that all this functionality is not forgotten, however.

@alexcrichton
Copy link
Member Author

cc @aturon

@alexcrichton
Copy link
Member Author

I should also be clear that I plan to write an RFC for this in the future, just not at this time :)

@blaenk
Copy link
Contributor

blaenk commented Mar 5, 2015

sounds great

@ghost
Copy link

ghost commented Mar 5, 2015

👍 Thanks for covering this.

@GuillaumeGomez
Copy link
Member

I'm looking forward to it ! It sounds very promising.

@codyps
Copy link

codyps commented Mar 5, 2015

DirEntry reminded me that posix has functionality allowing for file operations relative to a directory handle, which are sometimes required for safe file system access.

To support that type of thing (even externally) it'd be useful if DirEntry exposed a method to obtain the actual value of the DirEntry (ie: the name of the file relative to the directory) rather than just the full path.

@GuillaumeGomez
Copy link
Member

@jmesmon: I wrote a PR for that actually but it was "merged" with this one. That's said somewhere in here too. Don't worry, you're not the only one who wants to have it ! I already wrote a code for that. Just waiting for this RFC to be accepted before submitting it.

alexcrichton added a commit to alexcrichton/rust that referenced this issue Mar 6, 2015
This commit performs a stabilization pass over the `std::fs` module now that
it's had some time to bake. The change was largely just adding `#[stable]` tags,
but there are a few APIs that remain `#[unstable]`.

The following apis are now marked `#[stable]`:

* `std::fs` (the name)
* `File`
* `Metadata`
* `ReadDir`
* `DirEntry`
* `OpenOptions`
* `Permissions`
* `File::{open, create}`
* `File::{sync_all, sync_data}`
* `File::set_len`
* `File::metadata`
* Trait implementations for `File` and `&File`
* `OpenOptions::new`
* `OpenOptions::{read, write, append, truncate, create}`
* `OpenOptions::open` - this function was modified, however, to not attempt to
  reject cross-platform openings of directories. This means that some platforms
  will succeed in opening a directory and others will fail.
* `Metadata::{is_dir, is_file, len, permissions}`
* `Permissions::{readonly, set_readonly}`
* `Iterator for ReadDir`
* `DirEntry::path`
* `remove_file` - like with `OpenOptions::open`, the extra windows code to
  remove a readonly file has been removed. This means that removing a readonly
  file will succeed on some platforms but fail on others.
* `metadata`
* `rename`
* `copy`
* `hard_link`
* `soft_link`
* `read_link`
* `create_dir`
* `create_dir_all`
* `remove_dir`
* `remove_dir_all`
* `read_dir`

The following apis remain `#[unstable]`.

* `WalkDir` and `walk` - there are many methods by which a directory walk can be
  constructed, and it's unclear whether the current semantics are the right
  ones. For example symlinks are not handled super well currently. This is now
  behind a new `fs_walk` feature.
* `File::path` - this is an extra abstraction which the standard library
  provides on top of what the system offers and it's unclear whether we should
  be doing so. This is now behind a new `file_path` feature.
* `Metadata::{accessed, modified}` - we do not currently have a good
  abstraction for a moment in time which is what these APIs should likely be
  returning, so these remain `#[unstable]` for now. These are now behind a new
  `fs_time` feature
* `set_file_times` - like with `Metadata::accessed`, we do not currently have
  the appropriate abstraction for the arguments here so this API remains
  unstable behind the `fs_time` feature gate.
* `PathExt` - the precise set of methods on this trait may change over time and
  some methods may be removed. This API remains unstable behind the `path_ext`
  feature gate.
* `set_permissions` - we may wish to expose a more granular ability to set the
  permissions on a file instead of just a blanket "set all permissions" method.
  This function remains behind the `fs` feature.

The following apis are now `#[deprecated]`

* The `TempDir` type is now entirely deprecated and is [located on
  crates.io][tempdir] as the `tempdir` crate with [its source][github] at
  rust-lang/tempdir.

[tempdir]: https://crates.io/crates/tempdir
[github]: https://github.com/rust-lang/tempdir

The stability of some of these APIs has been questioned over the past few weeks
in using these APIs, and it is intentional that the majority of APIs here are
marked `#[stable]`. The `std::fs` module has a lot of room to grow and the
material is [being tracked in a RFC issue][rfc-issue].

[rfc-issue]: rust-lang/rfcs#939

[breaking-change]
Manishearth added a commit to Manishearth/rust that referenced this issue Mar 6, 2015
 This commit performs a stabilization pass over the `std::fs` module now that
it's had some time to bake. The change was largely just adding `#[stable]` tags,
but there are a few APIs that remain `#[unstable]`.

The following apis are now marked `#[stable]`:

* `std::fs` (the name)
* `File`
* `Metadata`
* `ReadDir`
* `DirEntry`
* `OpenOptions`
* `Permissions`
* `File::{open, create}`
* `File::{sync_all, sync_data}`
* `File::set_len`
* `File::metadata`
* Trait implementations for `File` and `&File`
* `OpenOptions::new`
* `OpenOptions::{read, write, append, truncate, create}`
* `OpenOptions::open` - this function was modified, however, to not attempt to
  reject cross-platform openings of directories. This means that some platforms
  will succeed in opening a directory and others will fail.
* `Metadata::{is_dir, is_file, len, permissions}`
* `Permissions::{readonly, set_readonly}`
* `Iterator for ReadDir`
* `DirEntry::path`
* `remove_file` - like with `OpenOptions::open`, the extra windows code to
  remove a readonly file has been removed. This means that removing a readonly
  file will succeed on some platforms but fail on others.
* `metadata`
* `rename`
* `copy`
* `hard_link`
* `soft_link`
* `read_link`
* `create_dir`
* `create_dir_all`
* `remove_dir`
* `remove_dir_all`
* `read_dir`

The following apis remain `#[unstable]`.

* `WalkDir` and `walk` - there are many methods by which a directory walk can be
  constructed, and it's unclear whether the current semantics are the right
  ones. For example symlinks are not handled super well currently. This is now
  behind a new `fs_walk` feature.
* `File::path` - this is an extra abstraction which the standard library
  provides on top of what the system offers and it's unclear whether we should
  be doing so. This is now behind a new `file_path` feature.
* `Metadata::{accessed, modified}` - we do not currently have a good
  abstraction for a moment in time which is what these APIs should likely be
  returning, so these remain `#[unstable]` for now. These are now behind a new
  `fs_time` feature
* `set_file_times` - like with `Metadata::accessed`, we do not currently have
  the appropriate abstraction for the arguments here so this API remains
  unstable behind the `fs_time` feature gate.
* `PathExt` - the precise set of methods on this trait may change over time and
  some methods may be removed. This API remains unstable behind the `path_ext`
  feature gate.
* `set_permissions` - we may wish to expose a more granular ability to set the
  permissions on a file instead of just a blanket \"set all permissions\" method.
  This function remains behind the `fs` feature.

The following apis are now `#[deprecated]`

* The `TempDir` type is now entirely deprecated and is [located on
  crates.io][tempdir] as the `tempdir` crate with [its source][github] at
  rust-lang/tempdir.

[tempdir]: https://crates.io/crates/tempdir
[github]: https://github.com/rust-lang/tempdir

The stability of some of these APIs has been questioned over the past few weeks
in using these APIs, and it is intentional that the majority of APIs here are
marked `#[stable]`. The `std::fs` module has a lot of room to grow and the
material is [being tracked in a RFC issue][rfc-issue].

[rfc-issue]: rust-lang/rfcs#939

Closes rust-lang#22879

[breaking-change]
@l0kod
Copy link

l0kod commented Mar 6, 2015

std::fs should also provide a way to a create temporary file (different from temporary directory).

Such a temporary file will be deleted from the filesystem just after creation, while keeping it open, or could be created with the O_TMPFILE flag when available. A call to path() will then return None.

@alexcrichton
Copy link
Member Author

@l0kod good point! I've added a bullet above

@nagisa
Copy link
Member

nagisa commented Mar 9, 2015

Another example of something we don't expose is just the filename itself #927 (not the full pathname as joined from the initial call to read_dir).

Note that the linked RFC and the issue that RFC was trying to solve don’t request for ability to retrieve filename per se, but rather path relative to the directory iteration began at. This distinction matters in context of std::fs::walk_dir.

@retep998
Copy link
Member

If there is any Windows functionality you desire, tell me and I'll implement it in wio, and then you can land that stuff into the standard library as needed.

@alexcrichton
Copy link
Member Author

A link from @retep998 when considering symlinks and windows: https://msdn.microsoft.com/en-us/library/windows/desktop/aa365682%28v=vs.85%29.aspx

@retep998
Copy link
Member

For temporary files on Windows, use the combination of these two flags:

  • FILE_ATTRIBUTE_TEMPORARY signifies that the OS should avoid writing the file to disk because it is temporary.
  • FILE_FLAG_DELETE_ON_CLOSE tells the OS to delete the file the handle closes. Note that while more handles to the file can be opened while the first handle is still open, once the original handle closes no more handles can be opened, and once all handles are closed, then the file is deleted.

@GuillaumeGomez
Copy link
Member

Discussed earlier on this rust issue. File metadata's timestamp needs a timestamp type instead of u64.

@codyps
Copy link

codyps commented Mar 25, 2015

I'd also note that the use of O_TMPFILE becomes even more useful when used in combination with renameat2(), which allows a file to be safely & atomically linked into place.

Which brings up the potentially for having certain operations avaliable that work with directory & file "handles" rather than plain paths (openat, renameat2, linkat, dir listing (essentially direct access to readdir instead of having a wrapper that opens the directory and fidles with the returned paths)).

@l0kod
Copy link

l0kod commented Mar 25, 2015

About the file handle functions, here are some thoughts: rust-lang/rust#21936 (comment)

@alexcrichton
Copy link
Member Author

I've now posted an RFC for much of the functionality, but not all, outlined in this issue.

@ogham
Copy link

ogham commented Sep 15, 2015

Recently I've been running into times when I'd like the Metadata struct to be Clone or even Copy, when currently it doesn't implement any traits other than MetadataExt. Is there any cross-platform reason as to why it's so sparsely-traited? The structure's fields on both Unix and Windows are all value types, rather than containing references to other parts of memory, which is why I thought it would be Clone.

@alexcrichton
Copy link
Member Author

@ogham I believe it was just done to be conservative. I would prefer to not implement Copy, but implementing Clone should be fine, feel free to send a PR!

bors added a commit to rust-lang/rust that referenced this issue Oct 15, 2015
This commit adds `#[derive(Clone)]` to `std::fs::Metadata`, making that struct cloneable. Although the exact contents of that struct differ between OSes, they all have it contain only value types, meaning that the data can be re-used without repercussions.

It also adds `#[derive(Clone)]` to every type used by that struct across all OSes, including the various Unix `stat` structs and Windows's `WIN32_FILE_ATTRIBUTE_DATA`.

This stems from my comment here: rust-lang/rfcs#939 (comment)
@steveklabnik
Copy link
Member

I had someone drop by IRC and ask for chown today; seems funny that we have chmod but not chown.

@retep998
Copy link
Member

retep998 commented Jan 6, 2017

Probably because chmod has no direct Windows equivalent so a unix specific trait is obvious, but chown does have a Windows equivalent, it's just really complicated to actually do.

@strega-nil
Copy link

strega-nil commented Jan 6, 2017

@retep998 Windows does seem to have chmod (at least in the crt)? I'm assuming we could duplicate the implementation.

https://msdn.microsoft.com/en-us/library/1z319a54.aspx

edit: explained on IRC.

@retep998
Copy link
Member

retep998 commented Jan 6, 2017

chown can be done by calling SetSecurityInfo with OWNER_SECURITY_INFORMATION and some other arguments.

@petrochenkov petrochenkov added T-libs-api Relevant to the library API team, which will review and decide on the RFC. and removed A-libs labels Jan 28, 2018
djrenren pushed a commit to djrenren/libtest that referenced this issue Jan 22, 2019
This commit performs a stabilization pass over the `std::fs` module now that
it's had some time to bake. The change was largely just adding `#[stable]` tags,
but there are a few APIs that remain `#[unstable]`.

The following apis are now marked `#[stable]`:

* `std::fs` (the name)
* `File`
* `Metadata`
* `ReadDir`
* `DirEntry`
* `OpenOptions`
* `Permissions`
* `File::{open, create}`
* `File::{sync_all, sync_data}`
* `File::set_len`
* `File::metadata`
* Trait implementations for `File` and `&File`
* `OpenOptions::new`
* `OpenOptions::{read, write, append, truncate, create}`
* `OpenOptions::open` - this function was modified, however, to not attempt to
  reject cross-platform openings of directories. This means that some platforms
  will succeed in opening a directory and others will fail.
* `Metadata::{is_dir, is_file, len, permissions}`
* `Permissions::{readonly, set_readonly}`
* `Iterator for ReadDir`
* `DirEntry::path`
* `remove_file` - like with `OpenOptions::open`, the extra windows code to
  remove a readonly file has been removed. This means that removing a readonly
  file will succeed on some platforms but fail on others.
* `metadata`
* `rename`
* `copy`
* `hard_link`
* `soft_link`
* `read_link`
* `create_dir`
* `create_dir_all`
* `remove_dir`
* `remove_dir_all`
* `read_dir`

The following apis remain `#[unstable]`.

* `WalkDir` and `walk` - there are many methods by which a directory walk can be
  constructed, and it's unclear whether the current semantics are the right
  ones. For example symlinks are not handled super well currently. This is now
  behind a new `fs_walk` feature.
* `File::path` - this is an extra abstraction which the standard library
  provides on top of what the system offers and it's unclear whether we should
  be doing so. This is now behind a new `file_path` feature.
* `Metadata::{accessed, modified}` - we do not currently have a good
  abstraction for a moment in time which is what these APIs should likely be
  returning, so these remain `#[unstable]` for now. These are now behind a new
  `fs_time` feature
* `set_file_times` - like with `Metadata::accessed`, we do not currently have
  the appropriate abstraction for the arguments here so this API remains
  unstable behind the `fs_time` feature gate.
* `PathExt` - the precise set of methods on this trait may change over time and
  some methods may be removed. This API remains unstable behind the `path_ext`
  feature gate.
* `set_permissions` - we may wish to expose a more granular ability to set the
  permissions on a file instead of just a blanket "set all permissions" method.
  This function remains behind the `fs` feature.

The following apis are now `#[deprecated]`

* The `TempDir` type is now entirely deprecated and is [located on
  crates.io][tempdir] as the `tempdir` crate with [its source][github] at
  rust-lang/tempdir.

[tempdir]: https://crates.io/crates/tempdir
[github]: https://github.com/rust-lang/tempdir

The stability of some of these APIs has been questioned over the past few weeks
in using these APIs, and it is intentional that the majority of APIs here are
marked `#[stable]`. The `std::fs` module has a lot of room to grow and the
material is [being tracked in a RFC issue][rfc-issue].

[rfc-issue]: rust-lang/rfcs#939

[breaking-change]
djrenren pushed a commit to djrenren/libtest that referenced this issue Jan 22, 2019
 This commit performs a stabilization pass over the `std::fs` module now that
it's had some time to bake. The change was largely just adding `#[stable]` tags,
but there are a few APIs that remain `#[unstable]`.

The following apis are now marked `#[stable]`:

* `std::fs` (the name)
* `File`
* `Metadata`
* `ReadDir`
* `DirEntry`
* `OpenOptions`
* `Permissions`
* `File::{open, create}`
* `File::{sync_all, sync_data}`
* `File::set_len`
* `File::metadata`
* Trait implementations for `File` and `&File`
* `OpenOptions::new`
* `OpenOptions::{read, write, append, truncate, create}`
* `OpenOptions::open` - this function was modified, however, to not attempt to
  reject cross-platform openings of directories. This means that some platforms
  will succeed in opening a directory and others will fail.
* `Metadata::{is_dir, is_file, len, permissions}`
* `Permissions::{readonly, set_readonly}`
* `Iterator for ReadDir`
* `DirEntry::path`
* `remove_file` - like with `OpenOptions::open`, the extra windows code to
  remove a readonly file has been removed. This means that removing a readonly
  file will succeed on some platforms but fail on others.
* `metadata`
* `rename`
* `copy`
* `hard_link`
* `soft_link`
* `read_link`
* `create_dir`
* `create_dir_all`
* `remove_dir`
* `remove_dir_all`
* `read_dir`

The following apis remain `#[unstable]`.

* `WalkDir` and `walk` - there are many methods by which a directory walk can be
  constructed, and it's unclear whether the current semantics are the right
  ones. For example symlinks are not handled super well currently. This is now
  behind a new `fs_walk` feature.
* `File::path` - this is an extra abstraction which the standard library
  provides on top of what the system offers and it's unclear whether we should
  be doing so. This is now behind a new `file_path` feature.
* `Metadata::{accessed, modified}` - we do not currently have a good
  abstraction for a moment in time which is what these APIs should likely be
  returning, so these remain `#[unstable]` for now. These are now behind a new
  `fs_time` feature
* `set_file_times` - like with `Metadata::accessed`, we do not currently have
  the appropriate abstraction for the arguments here so this API remains
  unstable behind the `fs_time` feature gate.
* `PathExt` - the precise set of methods on this trait may change over time and
  some methods may be removed. This API remains unstable behind the `path_ext`
  feature gate.
* `set_permissions` - we may wish to expose a more granular ability to set the
  permissions on a file instead of just a blanket \"set all permissions\" method.
  This function remains behind the `fs` feature.

The following apis are now `#[deprecated]`

* The `TempDir` type is now entirely deprecated and is [located on
  crates.io][tempdir] as the `tempdir` crate with [its source][github] at
  rust-lang/tempdir.

[tempdir]: https://crates.io/crates/tempdir
[github]: https://github.com/rust-lang/tempdir

The stability of some of these APIs has been questioned over the past few weeks
in using these APIs, and it is intentional that the majority of APIs here are
marked `#[stable]`. The `std::fs` module has a lot of room to grow and the
material is [being tracked in a RFC issue][rfc-issue].

[rfc-issue]: rust-lang/rfcs#939

Closes #22879

[breaking-change]
gnzlbg pushed a commit to rust-lang/libtest that referenced this issue Mar 2, 2019
This commit performs a stabilization pass over the `std::fs` module now that
it's had some time to bake. The change was largely just adding `#[stable]` tags,
but there are a few APIs that remain `#[unstable]`.

The following apis are now marked `#[stable]`:

* `std::fs` (the name)
* `File`
* `Metadata`
* `ReadDir`
* `DirEntry`
* `OpenOptions`
* `Permissions`
* `File::{open, create}`
* `File::{sync_all, sync_data}`
* `File::set_len`
* `File::metadata`
* Trait implementations for `File` and `&File`
* `OpenOptions::new`
* `OpenOptions::{read, write, append, truncate, create}`
* `OpenOptions::open` - this function was modified, however, to not attempt to
  reject cross-platform openings of directories. This means that some platforms
  will succeed in opening a directory and others will fail.
* `Metadata::{is_dir, is_file, len, permissions}`
* `Permissions::{readonly, set_readonly}`
* `Iterator for ReadDir`
* `DirEntry::path`
* `remove_file` - like with `OpenOptions::open`, the extra windows code to
  remove a readonly file has been removed. This means that removing a readonly
  file will succeed on some platforms but fail on others.
* `metadata`
* `rename`
* `copy`
* `hard_link`
* `soft_link`
* `read_link`
* `create_dir`
* `create_dir_all`
* `remove_dir`
* `remove_dir_all`
* `read_dir`

The following apis remain `#[unstable]`.

* `WalkDir` and `walk` - there are many methods by which a directory walk can be
  constructed, and it's unclear whether the current semantics are the right
  ones. For example symlinks are not handled super well currently. This is now
  behind a new `fs_walk` feature.
* `File::path` - this is an extra abstraction which the standard library
  provides on top of what the system offers and it's unclear whether we should
  be doing so. This is now behind a new `file_path` feature.
* `Metadata::{accessed, modified}` - we do not currently have a good
  abstraction for a moment in time which is what these APIs should likely be
  returning, so these remain `#[unstable]` for now. These are now behind a new
  `fs_time` feature
* `set_file_times` - like with `Metadata::accessed`, we do not currently have
  the appropriate abstraction for the arguments here so this API remains
  unstable behind the `fs_time` feature gate.
* `PathExt` - the precise set of methods on this trait may change over time and
  some methods may be removed. This API remains unstable behind the `path_ext`
  feature gate.
* `set_permissions` - we may wish to expose a more granular ability to set the
  permissions on a file instead of just a blanket "set all permissions" method.
  This function remains behind the `fs` feature.

The following apis are now `#[deprecated]`

* The `TempDir` type is now entirely deprecated and is [located on
  crates.io][tempdir] as the `tempdir` crate with [its source][github] at
  rust-lang/tempdir.

[tempdir]: https://crates.io/crates/tempdir
[github]: https://github.com/rust-lang/tempdir

The stability of some of these APIs has been questioned over the past few weeks
in using these APIs, and it is intentional that the majority of APIs here are
marked `#[stable]`. The `std::fs` module has a lot of room to grow and the
material is [being tracked in a RFC issue][rfc-issue].

[rfc-issue]: rust-lang/rfcs#939

[breaking-change]
gnzlbg pushed a commit to rust-lang/libtest that referenced this issue Mar 2, 2019
 This commit performs a stabilization pass over the `std::fs` module now that
it's had some time to bake. The change was largely just adding `#[stable]` tags,
but there are a few APIs that remain `#[unstable]`.

The following apis are now marked `#[stable]`:

* `std::fs` (the name)
* `File`
* `Metadata`
* `ReadDir`
* `DirEntry`
* `OpenOptions`
* `Permissions`
* `File::{open, create}`
* `File::{sync_all, sync_data}`
* `File::set_len`
* `File::metadata`
* Trait implementations for `File` and `&File`
* `OpenOptions::new`
* `OpenOptions::{read, write, append, truncate, create}`
* `OpenOptions::open` - this function was modified, however, to not attempt to
  reject cross-platform openings of directories. This means that some platforms
  will succeed in opening a directory and others will fail.
* `Metadata::{is_dir, is_file, len, permissions}`
* `Permissions::{readonly, set_readonly}`
* `Iterator for ReadDir`
* `DirEntry::path`
* `remove_file` - like with `OpenOptions::open`, the extra windows code to
  remove a readonly file has been removed. This means that removing a readonly
  file will succeed on some platforms but fail on others.
* `metadata`
* `rename`
* `copy`
* `hard_link`
* `soft_link`
* `read_link`
* `create_dir`
* `create_dir_all`
* `remove_dir`
* `remove_dir_all`
* `read_dir`

The following apis remain `#[unstable]`.

* `WalkDir` and `walk` - there are many methods by which a directory walk can be
  constructed, and it's unclear whether the current semantics are the right
  ones. For example symlinks are not handled super well currently. This is now
  behind a new `fs_walk` feature.
* `File::path` - this is an extra abstraction which the standard library
  provides on top of what the system offers and it's unclear whether we should
  be doing so. This is now behind a new `file_path` feature.
* `Metadata::{accessed, modified}` - we do not currently have a good
  abstraction for a moment in time which is what these APIs should likely be
  returning, so these remain `#[unstable]` for now. These are now behind a new
  `fs_time` feature
* `set_file_times` - like with `Metadata::accessed`, we do not currently have
  the appropriate abstraction for the arguments here so this API remains
  unstable behind the `fs_time` feature gate.
* `PathExt` - the precise set of methods on this trait may change over time and
  some methods may be removed. This API remains unstable behind the `path_ext`
  feature gate.
* `set_permissions` - we may wish to expose a more granular ability to set the
  permissions on a file instead of just a blanket \"set all permissions\" method.
  This function remains behind the `fs` feature.

The following apis are now `#[deprecated]`

* The `TempDir` type is now entirely deprecated and is [located on
  crates.io][tempdir] as the `tempdir` crate with [its source][github] at
  rust-lang/tempdir.

[tempdir]: https://crates.io/crates/tempdir
[github]: https://github.com/rust-lang/tempdir

The stability of some of these APIs has been questioned over the past few weeks
in using these APIs, and it is intentional that the majority of APIs here are
marked `#[stable]`. The `std::fs` module has a lot of room to grow and the
material is [being tracked in a RFC issue][rfc-issue].

[rfc-issue]: rust-lang/rfcs#939

Closes #22879

[breaking-change]
@ardeaf
Copy link

ardeaf commented Jan 21, 2020

@retep998 I don't see that chown is implemented in std::fs yet. Currently, is the only way to set file ownership through the Windows api (which I could use with your crate https://github.com/retep998/winapi-rs)?

@retep998
Copy link
Member

@ardeaf Yes, although there may be some third party crates that already wrap that for you. I don't foresee it getting into std any time soon though.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
T-libs-api Relevant to the library API team, which will review and decide on the RFC.
Projects
None yet
Development

No branches or pull requests