diff --git a/.github/workflows/generate-preview-links.yml b/.github/workflows/generate-preview-links.yml deleted file mode 100644 index 784d2be5b6..0000000000 --- a/.github/workflows/generate-preview-links.yml +++ /dev/null @@ -1,25 +0,0 @@ -name: 'Preview link generator' - -on: - pull_request_target: - types: [opened, synchronize, reopened] - -permissions: - contents: read - -jobs: - preview_link_generator_job: - name: Generate preview link table - runs-on: ubuntu-latest - permissions: - statuses: read - pull-requests: write - steps: - - name: Harden Runner - uses: step-security/harden-runner@b09bb98e06d4d774595224525879c09bc6e98c40 # v2.20.1 - with: - egress-policy: audit - - - uses: dotnet/docs-tools/actions/preview-link-generator@main - with: - repo_token: ${{ secrets.GITHUB_TOKEN }} \ No newline at end of file diff --git a/docs/mfc/how-to-update-user-interface-objects.md b/docs/mfc/how-to-update-user-interface-objects.md index 11d935d65c..66899aff53 100644 --- a/docs/mfc/how-to-update-user-interface-objects.md +++ b/docs/mfc/how-to-update-user-interface-objects.md @@ -11,7 +11,7 @@ helpviewer_keywords: ["menus [MFC], updating as context changes", "user interfac Typically, menu items and toolbar buttons have more than one state. For example, a menu item is grayed (dimmed) if it is unavailable in the present context. Menu items can also be checked or unchecked. A toolbar button can also be disabled if unavailable, or it can be checked. -Who updates the state of these items as program conditions change? Logically, if a menu item generates a command that is handled by, say, a document, it makes sense to have the document update the menu item. The document probably contains the information on which the update is based. +Who updates the state of these items as program conditions change? Logically, if a menu item generates a command that a document handles, it makes sense to have the document update the menu item. The document probably contains the information on which the update is based. If a command has multiple user-interface objects (perhaps a menu item and a toolbar button), both are routed to the same handler function. This encapsulates your user-interface update code for all of the equivalent user-interface objects in a single place. diff --git a/docs/standard-library/directory-entry-class.md b/docs/standard-library/directory-entry-class.md index 872cabb4b9..3aca916761 100644 --- a/docs/standard-library/directory-entry-class.md +++ b/docs/standard-library/directory-entry-class.md @@ -1,16 +1,15 @@ --- description: "Learn more about: directory_entry Class" title: "directory_entry Class" -ms.date: 06/10/2022 -f1_keywords: ["filesystem/std::experimental::filesystem::directory_entry", "filesystem/std::experimental::filesystem::directory_entry::operator const std::experimental::filesystem::path &", "filesystem/std::experimental::filesystem::directory_entry::directory_entry", "filesystem/std::experimental::filesystem::directory_entry::operator=", "filesystem/std::experimental::filesystem::directory_entry::assign", "filesystem/std::experimental::filesystem::directory_entry::replace_filename", "filesystem/std::experimental::filesystem::directory_entry::path", "filesystem/std::experimental::filesystem::directory_entry::status", "filesystem/std::experimental::filesystem::directory_entry::symlink_status", "filesystem/std::experimental::filesystem::directory_entry::operator<", "filesystem/std::experimental::filesystem::directory_entry::operator==", "filesystem/std::experimental::filesystem::directory_entry::operator!=", "filesystem/std::experimental::filesystem::directory_entry::operator<=", "filesystem/std::experimental::filesystem::directory_entry::operator>", "filesystem/std::experimental::filesystem::directory_entry::operator>="] -ms.assetid: 1827c67b-4137-4548-adb0-f955f7acaf08 -helpviewer_keywords: ["std::experimental::filesystem::directory_entry", "std::experimental::filesystem::directory_entry::operator const std::experimental::filesystem::path &", "std::experimental::filesystem::directory_entry::directory_entry", "std::experimental::filesystem::directory_entry::operator=", "std::experimental::filesystem::directory_entry::assign", "std::experimental::filesystem::directory_entry::replace_filename", "std::experimental::filesystem::directory_entry::path", "std::experimental::filesystem::directory_entry::status", "std::experimental::filesystem::directory_entry::symlink_status", "std::experimental::filesystem::directory_entry::operator<", "std::experimental::filesystem::directory_entry::operator==", "std::experimental::filesystem::directory_entry::operator!=", "std::experimental::filesystem::directory_entry::operator<=", "std::experimental::filesystem::directory_entry::operator>", "std::experimental::filesystem::directory_entry::operator>="] +ms.date: 08/28/2026 +f1_keywords: ["filesystem/std::filesystem::directory_entry", "filesystem/std::filesystem::directory_entry::directory_entry", "filesystem/std::filesystem::directory_entry::operator=", "filesystem/std::filesystem::directory_entry::assign", "filesystem/std::filesystem::directory_entry::replace_filename", "filesystem/std::filesystem::directory_entry::refresh", "filesystem/std::filesystem::directory_entry::path", "filesystem/std::filesystem::directory_entry::operator const std::filesystem::path &", "filesystem/std::filesystem::directory_entry::exists", "filesystem/std::filesystem::directory_entry::is_block_file", "filesystem/std::filesystem::directory_entry::is_character_file", "filesystem/std::filesystem::directory_entry::is_directory", "filesystem/std::filesystem::directory_entry::is_fifo", "filesystem/std::filesystem::directory_entry::is_other", "filesystem/std::filesystem::directory_entry::is_regular_file", "filesystem/std::filesystem::directory_entry::is_socket", "filesystem/std::filesystem::directory_entry::is_symlink", "filesystem/std::filesystem::directory_entry::file_size", "filesystem/std::filesystem::directory_entry::hard_link_count", "filesystem/std::filesystem::directory_entry::last_write_time", "filesystem/std::filesystem::directory_entry::status", "filesystem/std::filesystem::directory_entry::symlink_status", "filesystem/std::filesystem::directory_entry::operator==", "filesystem/std::filesystem::directory_entry::operator<=>"] +helpviewer_keywords: ["std::filesystem::directory_entry", "std::filesystem::directory_entry::directory_entry", "std::filesystem::directory_entry::operator=", "std::filesystem::directory_entry::assign", "std::filesystem::directory_entry::replace_filename", "std::filesystem::directory_entry::refresh", "std::filesystem::directory_entry::path", "std::filesystem::directory_entry::operator const std::filesystem::path &", "std::filesystem::directory_entry::exists", "std::filesystem::directory_entry::is_block_file", "std::filesystem::directory_entry::is_character_file", "std::filesystem::directory_entry::is_directory", "std::filesystem::directory_entry::is_fifo", "std::filesystem::directory_entry::is_other", "std::filesystem::directory_entry::is_regular_file", "std::filesystem::directory_entry::is_socket", "std::filesystem::directory_entry::is_symlink", "std::filesystem::directory_entry::file_size", "std::filesystem::directory_entry::hard_link_count", "std::filesystem::directory_entry::last_write_time", "std::filesystem::directory_entry::status", "std::filesystem::directory_entry::symlink_status", "std::filesystem::directory_entry::operator==", "std::filesystem::directory_entry::operator<=>"] ms.custom: devdivchpfy22 --- -# directory_entry Class +# `directory_entry` class -Describes an object that is returned by `*X`, where *X* is a [directory_iterator](../standard-library/directory-iterator-class.md) or a [recursive_directory_iterator](../standard-library/recursive-directory-iterator-class.md). +Describes an object that's returned by dereferencing a [`directory_iterator`](../standard-library/directory-iterator-class.md) or a [`recursive_directory_iterator`](../standard-library/recursive-directory-iterator-class.md). A `directory_entry` wraps a [`path`](../standard-library/path-class.md) and, as an optimization, can cache file attributes that are obtained while iterating a directory. ## Syntax @@ -20,253 +19,577 @@ class directory_entry; ## Remarks -The class stores an object of type [path](../standard-library/path-class.md). The stored `path` can be an instance of the [path Class](../standard-library/path-class.md) or of a type that is derived from `path`. It also stores two [file_type](../standard-library/filesystem-enumerations.md#file_type) values. One value represents the status of the stored file name. The other represents the symbolic link status of the file name. +A `directory_entry` object stores a [`path`](../standard-library/path-class.md). As an optimization, it can also cache the attributes and status of the file that the path refers to. The cached data is populated when the entry is created by a directory iterator, or when you call [`refresh`](#refresh). Observers such as [`file_size`](#file_size), [`last_write_time`](#last_write_time), [`status`](#status), and the various `is_*` predicates return the cached data when it's available; otherwise, they query the file system. For more information and code examples, see [File System Navigation (C++)](../standard-library/file-system-navigation.md). ### Constructors -|Constructor|Description| +| Constructor | Description | |-|-| -|[directory_entry](#directory_entry)|The defaulted constructors behave as expected. The fourth constructor initializes `mypath` to *pval*, `mystat` to *stat_arg*, and `mysymstat` to *symstat_arg*.| +| [`directory_entry`](#directory_entry) | Constructs a `directory_entry`. | ### Member functions -|Member function|Description| +| Member function | Description | |-|-| -|[assign](#assign)|The member function assigns *pval* to `mypath`, *stat* to `mystat`, and *symstat* to `mysymstat`.| -|[path](#path)|The member function returns `mypath`.| -|[replace_filename](#replace_filename)|The member function replaces `mypath` with `mypath.parent_path()` / *pval*, `mystat` with *stat_arg*, and `mysymstat` with *symstat_arg*| -|[status](#status)|Both member functions return `mystat` possibly first altered.| -|[symlink_status](#symlink_status)|Both member functions return `mysymstat` possibly first altered.| +| [`assign`](#assign) | Replaces the stored path and refreshes the cached attributes. | +| [`exists`](#exists) | Checks whether the entry refers to an existing file. | +| [`file_size`](#file_size) | Gets the size, in bytes, of the referenced file. | +| [`hard_link_count`](#hard_link_count) | Gets the number of hard links to the referenced file. | +| [`is_block_file`](#is_block_file) | Checks whether the referenced file is a block special file. | +| [`is_character_file`](#is_character_file) | Checks whether the referenced file is a character special file. | +| [`is_directory`](#is_directory) | Checks whether the referenced file is a directory. | +| [`is_fifo`](#is_fifo) | Checks whether the referenced file is a named pipe (FIFO). | +| [`is_other`](#is_other) | Checks whether the referenced file is an other file. | +| [`is_regular_file`](#is_regular_file) | Checks whether the referenced file is a regular file. | +| [`is_socket`](#is_socket) | Checks whether the referenced file is a socket. | +| [`is_symlink`](#is_symlink) | Checks whether the referenced file is a symbolic link. | +| [`last_write_time`](#last_write_time) | Gets the time of the last data modification of the referenced file. | +| [`path`](#path) | Returns the stored path. | +| [`refresh`](#refresh) | Refreshes the cached file attributes. | +| [`replace_filename`](#replace_filename) | Replaces the filename of the stored path and refreshes the cached attributes. | +| [`status`](#status) | Gets the status of the referenced file, following symbolic links. | +| [`symlink_status`](#symlink_status) | Gets the status of the referenced file, without following symbolic links. | ### Operators -|Operator|Description| +| Operator | Description | |-|-| -|[operator!=](#op_neq)|Replaces the elements of the list with a copy of another list.| -|[operator=](#op_as)|The defaulted member assignment operators behave as expected.| -|[operator==](#op_eq)|Returns `mypath == right.mypath`.| -|[operator<](#op_lt)|Returns `mypath < right.mypath`.| -|[operator<=](#op_lteq)|Returns `!(right < *this)`.| -|[operator>](#op_gt)|Returns `right < *this`.| -|[operator>=](#op_gteq)|Returns `!(*this < right)`.| -|[operator const path_type&](#path_type)|Returns `mypath`.| +| [`operator=`](#op_as) | Assigns to the `directory_entry`. | +| [`operator const path&`](#path_type) | Returns the stored path. | +| [`operator==`](#op_eq) | Checks whether two `directory_entry` objects are equal. | +| [`operator<=>`](#op_spaceship) | Performs a three-way comparison of two `directory_entry` objects. (C++20) | +| [`operator!=`](#op_neq) | Checks whether two `directory_entry` objects are unequal. An explicit member in C++17; supported through rewritten comparisons in C++20 and later. | +| [`operator<`](#op_lt) | Checks whether the `directory_entry` sorts before another `directory_entry`. An explicit member in C++17; supported through rewritten comparisons in C++20 and later. | +| [`operator<=`](#op_lteq) | Checks whether the `directory_entry` sorts before or equal to another `directory_entry`. An explicit member in C++17; supported through rewritten comparisons in C++20 and later. | +| [`operator>`](#op_gt) | Checks whether the `directory_entry` sorts after another `directory_entry`. An explicit member in C++17; supported through rewritten comparisons in C++20 and later. | +| [`operator>=`](#op_gteq) | Checks whether the `directory_entry` sorts after or equal to another `directory_entry`. An explicit member in C++17; supported through rewritten comparisons in C++20 and later. | ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std::experimental::filesystem +**Namespace:** `std::filesystem` + +## directory_entry + +Constructs a `directory_entry`. + +```cpp +directory_entry() noexcept = default; +directory_entry(const directory_entry&) = default; +directory_entry(directory_entry&&) noexcept = default; + +explicit directory_entry(const std::filesystem::path& p); +directory_entry(const std::filesystem::path& p, std::error_code& ec); + +~directory_entry(); +``` + +### Parameters + +*p*\ +The path to the file that the entry refers to. + +*ec*\ +The output error code for the operation. + +### Remarks + +The default, copy, and move constructors behave as expected. The constructors that take a `path` store *p* and then call [`refresh`](#refresh) to populate the cached attributes. The overload that takes an `error_code` reports errors in *ec* instead of throwing, and clears the stored path if the refresh fails. + +## operator= + +Assigns to the `directory_entry`. + +```cpp +directory_entry& operator=(const directory_entry&) = default; +directory_entry& operator=(directory_entry&&) noexcept = default; +``` + +### Parameters + +*right*\ +The `directory_entry` to copy or move into this `directory_entry`. + +### Remarks + +The defaulted assignment operators behave as expected. ## assign -The member function assigns *pval* to `mypath`, *stat_arg* to `mystat`, and *symstat_arg* to `mysymstat`. +Replaces the stored path and refreshes the cached attributes. ```cpp -void assign(const std::experimental::filesystem::path& pval, - file_status stat_arg = file_status(), - file_status symstat_arg = file_status()); +void assign(const std::filesystem::path& p); +void assign(const std::filesystem::path& p, std::error_code& ec); ``` ### Parameters -*pval*\ -The stored file name path. +*p*\ +The new path to store. + +*ec*\ +The output error code for the operation. -*stat_arg*\ -The status of the stored file name. +### Remarks -*symstat_arg*\ -The symbolic link status of the stored file name. +Replaces the stored path with *p*, then calls [`refresh`](#refresh) to update the cached attributes. The overload that takes an `error_code` reports errors in *ec* instead of throwing. -## directory_entry +## replace_filename -The defaulted constructors behave as expected. The fourth constructor initializes `mypath` to *pval*, `mystat` to *stat_arg*, and `mysymstat` to *symstat_arg*. +Replaces the filename of the stored path and refreshes the cached attributes. ```cpp -directory_entry() = default; -directory_entry(const directory_entry&) = default; -directory_entry(directory_entry&&) noexcept = default; -explicit directory_entry(const std::experimental::filesystem::path& pval, - file_status stat_arg = file_status(), - file_status symstat_arg = file_status()); +void replace_filename(const std::filesystem::path& p); +void replace_filename(const std::filesystem::path& p, std::error_code& ec); ``` ### Parameters -*pval*\ -The stored file name path. +*p*\ +The replacement filename. -*stat_arg*\ -The status of the stored file name. +*ec*\ +The output error code for the operation. -*symstat_arg*\ -The symbolic link status of the stored file name. +### Remarks -## operator!= +Replaces the filename component of the stored path with *p*, as if by `path().replace_filename(p)`, then calls [`refresh`](#refresh). The overload that takes an `error_code` reports errors in *ec* instead of throwing. + +## refresh -The member function returns `!(*this == right)`. +Refreshes the cached file attributes. ```cpp -bool operator!=(const directory_entry& right) const noexcept; +void refresh(); +void refresh(std::error_code& ec) noexcept; ``` ### Parameters -*right*\ -The [directory_entry](../standard-library/directory-entry-class.md) being compared to the `directory_entry`. +*ec*\ +The output error code for the operation. -## operator= +### Remarks + +Reads the attributes of the file that the stored path refers to and caches them in the `directory_entry`. Call `refresh` to update the cached data after the referenced file changes. The overload that takes an `error_code` reports errors in *ec* instead of throwing. -The defaulted member assignment operators behave as expected. +## path + +Returns the stored path. ```cpp -directory_entry& operator=(const directory_entry&) = default; -directory_entry& operator=(directory_entry&&) noexcept = default; +const std::filesystem::path& path() const noexcept; +``` + +## operator const path& + +Returns the stored path. + +```cpp +operator const std::filesystem::path&() const noexcept; +``` + +## exists + +Checks whether the entry refers to an existing file. + +```cpp +bool exists() const; +bool exists(std::error_code& ec) const noexcept; ``` ### Parameters -*right*\ -The [directory_entry](../standard-library/directory-entry-class.md) being copied into the `directory_entry`. +*ec*\ +The output error code for the operation. -## operator== +### Return value + +`true` if the stored path refers to an existing file; otherwise, `false`. Equivalent to calling `filesystem::exists(status())`. + +## is_block_file -The member function returns `mypath == right.mypath`. +Checks whether the referenced file is a block special file. ```cpp -bool operator==(const directory_entry& right) const noexcept; +bool is_block_file() const; +bool is_block_file(std::error_code& ec) const noexcept; ``` ### Parameters -*right*\ -The [directory_entry](../standard-library/directory-entry-class.md) being compared to the `directory_entry`. +*ec*\ +The output error code for the operation. -## `operator<` +### Return value -The member function returns `mypath < right.mypath`. +`true` if the referenced file is a block special file; otherwise, `false`. This function always returns `false` on Windows. + +## is_character_file + +Checks whether the referenced file is a character special file. ```cpp -bool operator<(const directory_entry& right) const noexcept; +bool is_character_file() const; +bool is_character_file(std::error_code& ec) const noexcept; ``` ### Parameters -*right*\ -The [directory_entry](../standard-library/directory-entry-class.md) being compared to the `directory_entry`. +*ec*\ +The output error code for the operation. -## `operator<=` +### Return value + +`true` if the referenced file is a character special file; otherwise, `false`. This function always returns `false` on Windows. + +## is_directory -The member function returns `!(right < *this)`. +Checks whether the referenced file is a directory. ```cpp -bool operator<=(const directory_entry& right) const noexcept; +bool is_directory() const; +bool is_directory(std::error_code& ec) const noexcept; ``` ### Parameters -*right*\ -The [directory_entry](../standard-library/directory-entry-class.md) being compared to the `directory_entry`. +*ec*\ +The output error code for the operation. -## `operator>` +### Return value + +`true` if the referenced file is a directory; otherwise, `false`. Equivalent to calling `filesystem::is_directory(status())`. -The member function returns `right < *this`. +## is_fifo + +Checks whether the referenced file is a named pipe (FIFO). ```cpp -bool operator>(const directory_entry& right) const noexcept; +bool is_fifo() const; +bool is_fifo(std::error_code& ec) const noexcept; ``` ### Parameters -*right*\ -The [directory_entry](../standard-library/directory-entry-class.md) being compared to the `directory_entry`. +*ec*\ +The output error code for the operation. -## `operator>=` +### Return value -The member function returns `!(*this < right)`. +`true` if the referenced file is a FIFO; otherwise, `false`. This function always returns `false` on Windows. + +## is_other + +Checks whether the referenced file is an other file. ```cpp -bool operator>=(const directory_entry& right) const noexcept; +bool is_other() const; +bool is_other(std::error_code& ec) const noexcept; ``` ### Parameters -*right*\ -The [directory_entry](../standard-library/directory-entry-class.md) being compared to the `directory_entry`. +*ec*\ +The output error code for the operation. -## operator const path_type& +### Return value -The member operator returns `mypath`. +`true` if the referenced file exists but isn't a regular file, directory, or symbolic link; otherwise, `false`. Equivalent to calling `filesystem::is_other(status())`. + +## is_regular_file + +Checks whether the referenced file is a regular file. ```cpp -operator const std::experimental::filesystem::path&() const; +bool is_regular_file() const; +bool is_regular_file(std::error_code& ec) const noexcept; ``` -## path +### Parameters + +*ec*\ +The output error code for the operation. + +### Return value -The member function returns `mypath`. +`true` if the referenced file is a regular file; otherwise, `false`. Equivalent to calling `filesystem::is_regular_file(status())`. + +## is_socket + +Checks whether the referenced file is a socket. ```cpp -const std::experimental::filesystem::path& path() const noexcept; +bool is_socket() const; +bool is_socket(std::error_code& ec) const noexcept; ``` -## replace_filename +### Parameters -The member function replaces `mypath` with `mypath.parent_path()` / *pval*, `mystat` with *stat_arg*, and `mysymstat` with *symstat_arg* +*ec*\ +The output error code for the operation. + +### Return value + +`true` if the referenced file is a socket; otherwise, `false`. This function always returns `false` on Windows. + +## is_symlink + +Checks whether the referenced file is a symbolic link. ```cpp -void replace_filename( - const std::experimental::filesystem::path& pval, - file_status stat_arg = file_status(), - file_status symstat_arg = file_status()); +bool is_symlink() const; +bool is_symlink(std::error_code& ec) const noexcept; ``` ### Parameters -*pval*\ -The stored file name path. +*ec*\ +The output error code for the operation. -*stat_arg*\ -The status of the stored file name. +### Return value -*symstat_arg*\ -The symbolic link status of the stored file name. +`true` if the referenced file is a symbolic link; otherwise, `false`. Equivalent to calling `filesystem::is_symlink(symlink_status())`. -## status +## file_size + +Gets the size, in bytes, of the referenced file. + +```cpp +uintmax_t file_size() const; +uintmax_t file_size(std::error_code& ec) const noexcept; +``` + +### Parameters + +*ec*\ +The output error code for the operation. + +### Return value + +The size, in bytes, of the referenced file, as if by `filesystem::file_size(path())`. Uses cached data when it's available. + +## hard_link_count + +Gets the number of hard links to the referenced file. + +```cpp +uintmax_t hard_link_count() const; +uintmax_t hard_link_count(std::error_code& ec) const noexcept; +``` + +### Parameters + +*ec*\ +The output error code for the operation. + +### Return value + +The number of hard links to the referenced file, as if by `filesystem::hard_link_count(path())`. Uses cached data when it's available. + +## last_write_time + +Gets the time of the last data modification of the referenced file. + +```cpp +file_time_type last_write_time() const; +file_time_type last_write_time(std::error_code& ec) const noexcept; +``` + +### Parameters + +*ec*\ +The output error code for the operation. + +### Return value -Both member functions return `mystat` possibly first altered as follows: +The time of the last data modification of the referenced file, as if by `filesystem::last_write_time(path())`. Uses cached data when it's available. -1. If `status_known(mystat)` then do nothing. +## status -1. Otherwise, if `!status_known(mysymstat) && !is_symlink(mysymstat)` then `mystat = mysymstat`. +Gets the status of the referenced file, following symbolic links. ```cpp file_status status() const; -file_status status(error_code& ec) const noexcept; +file_status status(std::error_code& ec) const noexcept; ``` ### Parameters *ec*\ -The status error code. +The output error code for the operation. + +### Return value + +The status of the referenced file, as if by `filesystem::status(path())`. Uses cached data when it's available. ## symlink_status -Both member functions return `mysymstat` possibly first altered as follows: If `status_known(mysymstat)` then do nothing. Otherwise, `mysymstat = symlink_status(mypval)`. +Gets the status of the referenced file, without following symbolic links. ```cpp file_status symlink_status() const; -file_status symlink_status(error_code& ec) const noexcept; +file_status symlink_status(std::error_code& ec) const noexcept; ``` ### Parameters *ec*\ -The status error code. +The output error code for the operation. + +### Return value + +The symlink status of the referenced file, as if by `filesystem::symlink_status(path())`. Uses cached data when it's available. + +## operator== + +Checks whether two `directory_entry` objects are equal. + +```cpp +bool operator==(const directory_entry& right) const noexcept; +``` + +### Parameters + +*right*\ +The `directory_entry` to compare against. + +### Return value + +Returns `path() == right.path()`. + +## `operator<=>` + +Performs a three-way comparison of two `directory_entry` objects. + +```cpp +std::strong_ordering operator<=>(const directory_entry& right) const noexcept; // C++20 +``` + +### Parameters + +*right*\ +The `directory_entry` to compare against. + +### Return value + +Returns `path() <=> right.path()`. + +### Remarks + +Available in C++20 and later. The compiler rewrites comparisons that use `operator<`, `operator<=`, `operator>`, or `operator>=` to use this operator. It rewrites comparisons that use `operator!=` to use [`operator==`](#op_eq). + +## operator!= + +Checks whether two `directory_entry` objects are unequal. + +```cpp +bool operator!=(const directory_entry& right) const noexcept; // C++17 +``` + +### Parameters + +*right*\ +The `directory_entry` to compare against. + +### Return value + +Returns `!(*this == right)`. + +### Remarks + +In C++17, this operator is an explicitly declared member function. In C++20 and later, an expression that uses `operator!=` is rewritten to use [`operator==`](#op_eq). + +## `operator<` + +Checks whether the `directory_entry` sorts before another `directory_entry`. + +```cpp +bool operator<(const directory_entry& right) const noexcept; // C++17 +``` + +### Parameters + +*right*\ +The `directory_entry` to compare against. + +### Return value + +Returns `path() < right.path()`. + +### Remarks + +In C++17, this operator is an explicitly declared member function. In C++20 and later, an expression that uses `operator<` is rewritten to use [`operator<=>`](#op_spaceship). + +## `operator<=` + +Checks whether the `directory_entry` sorts before or equal to another `directory_entry`. + +```cpp +bool operator<=(const directory_entry& right) const noexcept; // C++17 +``` + +### Parameters + +*right*\ +The `directory_entry` to compare against. + +### Return value + +Returns `!(right < *this)`. + +### Remarks + +In C++17, this operator is an explicitly declared member function. In C++20 and later, an expression that uses `operator<=` is rewritten to use [`operator<=>`](#op_spaceship). + +## `operator>` + +Checks whether the `directory_entry` sorts after another `directory_entry`. + +```cpp +bool operator>(const directory_entry& right) const noexcept; // C++17 +``` + +### Parameters + +*right*\ +The `directory_entry` to compare against. + +### Return value + +Returns `right < *this`. + +### Remarks + +In C++17, this operator is an explicitly declared member function. In C++20 and later, an expression that uses `operator>` is rewritten to use [`operator<=>`](#op_spaceship). + +## `operator>=` + +Checks whether the `directory_entry` sorts after or equal to another `directory_entry`. + +```cpp +bool operator>=(const directory_entry& right) const noexcept; // C++17 +``` + +### Parameters + +*right*\ +The `directory_entry` to compare against. + +### Return value + +Returns `!(*this < right)`. + +### Remarks + +In C++17, this operator is an explicitly declared member function. In C++20 and later, an expression that uses `operator>=` is rewritten to use [`operator<=>`](#op_spaceship). ## See also [Header Files Reference](../standard-library/cpp-standard-library-header-files.md)\ -[``](../standard-library/filesystem.md) +[``](../standard-library/filesystem.md)\ +[File System Navigation (C++)](../standard-library/file-system-navigation.md) diff --git a/docs/standard-library/directory-iterator-class.md b/docs/standard-library/directory-iterator-class.md index b377693eee..59ace31494 100644 --- a/docs/standard-library/directory-iterator-class.md +++ b/docs/standard-library/directory-iterator-class.md @@ -1,10 +1,9 @@ --- description: "Learn more about: directory_iterator Class" title: "directory_iterator Class" -ms.date: 04/28/2023 +ms.date: 08/27/2026 f1_keywords: ["filesystem/std::filesystem::directory_iterator", "filesystem/std::filesystem::_Directory_iterator::_Directory_iterator", "filesystem/std::filesystem::directory_iterator::directory_iterator", "filesystem/std::filesystem::directory_iterator::increment", "filesystem/std::filesystem::directory_iterator::operator=", "filesystem/std::filesystem::directory_iterator::operator==", "filesystem/std::filesystem::directory_iterator::operator!=", "filesystem/std::filesystem::directory_iterator::operator*", "filesystem/std::filesystem::directory_iterator::operator->", "filesystem/std::filesystem::directory_iterator::operator++"] -ms.assetid: dca2ecf8-3e69-4644-a83d-705061e10cc8 -helpviewer_keywords: ["std::filesystem::directory_iterator", "std::filesystem::_Directory_iterator::_Directory_iterator", "std::filesystem::directory_iterator", "std::filesystem::directory_iterator::directory_iterator", "std::filesystem::directory_iterator::increment", "std::filesystem::directory_iterator::operator=", "std::filesystem::directory_iterator::operator==", "std::filesystem::directory_iterator::operator!=", "std::filesystem::directory_iterator::operator*", "std::filesystem::directory_iterator::operator->", "std::filesystem::directory_iterator::operator++"] +helpviewer_keywords: ["std::filesystem::directory_iterator", "std::filesystem::_Directory_iterator::_Directory_iterator", "std::filesystem::directory_iterator::directory_iterator", "std::filesystem::directory_iterator::increment", "std::filesystem::directory_iterator::operator=", "std::filesystem::directory_iterator::operator==", "std::filesystem::directory_iterator::operator!=", "std::filesystem::directory_iterator::operator*", "std::filesystem::directory_iterator::operator->", "std::filesystem::directory_iterator::operator++"] ms.custom: devdivchpfy22 --- @@ -59,15 +58,14 @@ class directory_iterator; ## `directory_iterator::directory_iterator` -The first constructor produces an end-of-sequence iterator. The second and third constructors store *`pval`* in `mydir`, then attempt to open and read `mydir` as a directory. If successful, they store the first filename in the directory in `myentry`; otherwise they produce an end-of-sequence iterator. - -The default constructor behaves as expected. +The first constructor produces an end-of-sequence iterator. The constructors that take a *`pval`* argument store it in `mydir`, then attempt to open and read `mydir` as a directory. If successful, they store the first filename in the directory in `myentry`; otherwise they produce an end-of-sequence iterator. The overloads that take an *`options`* argument control how the directory is enumerated. The overloads that take an *`ec`* argument report errors in *`ec`* instead of throwing an exception. The copy and move constructors behave as expected. ```cpp directory_iterator() noexcept; explicit directory_iterator(const path& pval); - +directory_iterator(const path& pval, directory_options options); directory_iterator(const path& pval, error_code& ec) noexcept; +directory_iterator(const path& pval, directory_options options, error_code& ec) noexcept; directory_iterator(const directory_iterator&) = default; directory_iterator(directory_iterator&&) noexcept = default; ``` @@ -77,6 +75,9 @@ directory_iterator(directory_iterator&&) noexcept = default; *`pval`*\ The stored file name path. +*`options`*\ +The `directory_options` value that controls how the directory is enumerated. The default is `directory_options::none`. + *`ec`*\ The status error code. @@ -88,9 +89,14 @@ The stored object. The function attempts to advance to the next filename in the directory. If successful, it stores that filename in `myentry`; otherwise it produces an end-of-sequence iterator. ```cpp -directory_iterator& increment(error_code& ec) noexcept; +directory_iterator& increment(error_code& ec); ``` +### Parameters + +*`ec`*\ +The status error code. + ## `directory_iterator::operator!=` The member operator returns `!(*this == right)`. @@ -153,13 +159,13 @@ The first member function calls `increment()`, then returns **`*this`**. The sec ```cpp directory_iterator& operator++(); -directory_iterator& operator++(int); +directory_iterator operator++(int); ``` ### Parameters *`int`*\ -The number of increments. +Dummy argument. It's a C++ convention used only to distinguish the postfix increment operator from the prefix increment operator. The C++ standard requires the postfix form to take a dummy int parameter. ## See also diff --git a/docs/standard-library/experimental-filesystem-directory-entry-class.md b/docs/standard-library/experimental-filesystem-directory-entry-class.md new file mode 100644 index 0000000000..2b9227a4b4 --- /dev/null +++ b/docs/standard-library/experimental-filesystem-directory-entry-class.md @@ -0,0 +1,272 @@ +--- +description: "Learn more about: directory_entry class" +title: " directory_entry class" +ms.date: 08/27/2026 +f1_keywords: ["filesystem/std::experimental::filesystem::directory_entry", "filesystem/std::experimental::filesystem::directory_entry::operator const std::experimental::filesystem::path &", "filesystem/std::experimental::filesystem::directory_entry::directory_entry", "filesystem/std::experimental::filesystem::directory_entry::operator=", "filesystem/std::experimental::filesystem::directory_entry::assign", "filesystem/std::experimental::filesystem::directory_entry::replace_filename", "filesystem/std::experimental::filesystem::directory_entry::path", "filesystem/std::experimental::filesystem::directory_entry::status", "filesystem/std::experimental::filesystem::directory_entry::symlink_status", "filesystem/std::experimental::filesystem::directory_entry::operator<", "filesystem/std::experimental::filesystem::directory_entry::operator==", "filesystem/std::experimental::filesystem::directory_entry::operator!=", "filesystem/std::experimental::filesystem::directory_entry::operator<=", "filesystem/std::experimental::filesystem::directory_entry::operator>", "filesystem/std::experimental::filesystem::directory_entry::operator>="] +helpviewer_keywords: ["std::experimental::filesystem::directory_entry", "std::experimental::filesystem::directory_entry::operator const std::experimental::filesystem::path &", "std::experimental::filesystem::directory_entry::directory_entry", "std::experimental::filesystem::directory_entry::operator=", "std::experimental::filesystem::directory_entry::assign", "std::experimental::filesystem::directory_entry::replace_filename", "std::experimental::filesystem::directory_entry::path", "std::experimental::filesystem::directory_entry::status", "std::experimental::filesystem::directory_entry::symlink_status", "std::experimental::filesystem::directory_entry::operator<", "std::experimental::filesystem::directory_entry::operator==", "std::experimental::filesystem::directory_entry::operator!=", "std::experimental::filesystem::directory_entry::operator<=", "std::experimental::filesystem::directory_entry::operator>", "std::experimental::filesystem::directory_entry::operator>="] +ms.custom: devdivchpfy22 +--- + +# `` `directory_entry` class + +> [!IMPORTANT] +> This article describes the prestandard `std::experimental::filesystem` implementation of `directory_entry`. This implementation is based on the File System Technical Specification, found in [ISO/IEC JTC 1/SC 22/WG 21 N4100](https://wg21.link/n4100). It isn't `std::filesystem`, and it isn't compatible with the C++17 `std::filesystem` implementation. The experimental implementation was removed starting in MSVC toolset version 14.51. For the current C++17 `std::filesystem` version, see [`directory_entry` class](../standard-library/directory-entry-class.md). + +Describes an object that is returned by `*X`, where *X* is a [`directory_iterator`](../standard-library/experimental-filesystem-directory-iterator-class.md) or a [`recursive_directory_iterator`](../standard-library/experimental-filesystem-recursive-directory-iterator-class.md). + +## Syntax + +```cpp +class directory_entry; +``` + +## Remarks + +The class stores an object of type [`path`](../standard-library/experimental-filesystem-path-class.md). The stored `path` can be an instance of the `path` class or of a type that is derived from `path`. It also stores two [`file_type`](../standard-library/experimental-filesystem-enumerations.md#file_type) values. One value represents the status of the stored file name. The other represents the symbolic link status of the file name. + +### Constructors + +|Constructor|Description| +|-|-| +|[`directory_entry`](#directory_entry)|The defaulted constructors behave as expected. The fourth constructor initializes `mypath` to *pval*, `mystat` to *stat_arg*, and `mysymstat` to *symstat_arg*.| + +### Member functions + +|Member function|Description| +|-|-| +|[`assign`](#assign)|The member function assigns *pval* to `mypath`, *stat* to `mystat`, and *symstat* to `mysymstat`.| +|[`path`](#path)|The member function returns `mypath`.| +|[`replace_filename`](#replace_filename)|The member function replaces `mypath` with `mypath.parent_path()` / *pval*, `mystat` with *stat_arg*, and `mysymstat` with *symstat_arg*| +|[`status`](#status)|Both member functions return `mystat` possibly first altered.| +|[`symlink_status`](#symlink_status)|Both member functions return `mysymstat` possibly first altered.| + +### Operators + +|Operator|Description| +|-|-| +|[`operator!=`](#op_neq)|Returns `!(*this == right)`.| +|[`operator=`](#op_as)|The defaulted member assignment operators behave as expected.| +|[`operator==`](#op_eq)|Returns `mypath == right.mypath`.| +|[`operator<`](#op_lt)|Returns `mypath < right.mypath`.| +|[`operator<=`](#op_lteq)|Returns `!(right < *this)`.| +|[`operator>`](#op_gt)|Returns `right < *this`.| +|[`operator>=`](#op_gteq)|Returns `!(*this < right)`.| +|[`operator const path_type&`](#path_type)|Returns `mypath`.| + +## Requirements + +**Header:** `` + +**Namespace:** `std::experimental::filesystem` + +## assign + +The member function assigns *pval* to `mypath`, *stat_arg* to `mystat`, and *symstat_arg* to `mysymstat`. + +```cpp +void assign(const std::experimental::filesystem::path& pval, + file_status stat_arg = file_status(), + file_status symstat_arg = file_status()); +``` + +### Parameters + +*pval*\ +The stored file name path. + +*stat_arg*\ +The status of the stored file name. + +*symstat_arg*\ +The symbolic link status of the stored file name. + +## directory_entry + +The defaulted constructors behave as expected. The fourth constructor initializes `mypath` to *pval*, `mystat` to *stat_arg*, and `mysymstat` to *symstat_arg*. + +```cpp +directory_entry() = default; +directory_entry(const directory_entry&) = default; +directory_entry(directory_entry&&) noexcept = default; +explicit directory_entry(const std::experimental::filesystem::path& pval, + file_status stat_arg = file_status(), + file_status symstat_arg = file_status()); +``` + +### Parameters + +*pval*\ +The stored file name path. + +*stat_arg*\ +The status of the stored file name. + +*symstat_arg*\ +The symbolic link status of the stored file name. + +## operator!= + +The member function returns `!(*this == right)`. + +```cpp +bool operator!=(const directory_entry& right) const noexcept; +``` + +### Parameters + +*right*\ +The [directory_entry](../standard-library/experimental-filesystem-directory-entry-class.md) being compared to the `directory_entry`. + +## operator= + +The defaulted member assignment operators behave as expected. + +```cpp +directory_entry& operator=(const directory_entry&) = default; +directory_entry& operator=(directory_entry&&) noexcept = default; +``` + +### Parameters + +*right*\ +The [directory_entry](../standard-library/experimental-filesystem-directory-entry-class.md) being copied into the `directory_entry`. + +## operator== + +The member function returns `mypath == right.mypath`. + +```cpp +bool operator==(const directory_entry& right) const noexcept; +``` + +### Parameters + +*right*\ +The [directory_entry](../standard-library/experimental-filesystem-directory-entry-class.md) being compared to the `directory_entry`. + +## `operator<` + +The member function returns `mypath < right.mypath`. + +```cpp +bool operator<(const directory_entry& right) const noexcept; +``` + +### Parameters + +*right*\ +The [directory_entry](../standard-library/experimental-filesystem-directory-entry-class.md) being compared to the `directory_entry`. + +## `operator<=` + +The member function returns `!(right < *this)`. + +```cpp +bool operator<=(const directory_entry& right) const noexcept; +``` + +### Parameters + +*right*\ +The [directory_entry](../standard-library/experimental-filesystem-directory-entry-class.md) being compared to the `directory_entry`. + +## `operator>` + +The member function returns `right < *this`. + +```cpp +bool operator>(const directory_entry& right) const noexcept; +``` + +### Parameters + +*right*\ +The [directory_entry](../standard-library/experimental-filesystem-directory-entry-class.md) being compared to the `directory_entry`. + +## `operator>=` + +The member function returns `!(*this < right)`. + +```cpp +bool operator>=(const directory_entry& right) const noexcept; +``` + +### Parameters + +*right*\ +The [directory_entry](../standard-library/experimental-filesystem-directory-entry-class.md) being compared to the `directory_entry`. + +## operator const path_type& + +The member operator returns `mypath`. + +```cpp +operator const std::experimental::filesystem::path&() const; +``` + +## path + +The member function returns `mypath`. + +```cpp +const std::experimental::filesystem::path& path() const noexcept; +``` + +## replace_filename + +The member function replaces `mypath` with `mypath.parent_path()` / *pval*, `mystat` with *stat_arg*, and `mysymstat` with *symstat_arg* + +```cpp +void replace_filename( + const std::experimental::filesystem::path& pval, + file_status stat_arg = file_status(), + file_status symstat_arg = file_status()); +``` + +### Parameters + +*pval*\ +The stored file name path. + +*stat_arg*\ +The status of the stored file name. + +*symstat_arg*\ +The symbolic link status of the stored file name. + +## status + +Both member functions return `mystat` possibly first altered as follows: + +1. If `status_known(mystat)` then do nothing. + +1. Otherwise, if `!status_known(mysymstat) && !is_symlink(mysymstat)` then `mystat = mysymstat`. + +```cpp +file_status status() const; +file_status status(error_code& ec) const noexcept; +``` + +### Parameters + +*ec*\ +The status error code. + +## symlink_status + +Both member functions return `mysymstat` possibly first altered as follows: If `status_known(mysymstat)` then do nothing. Otherwise, `mysymstat = symlink_status(mypval)`. + +```cpp +file_status symlink_status() const; +file_status symlink_status(error_code& ec) const noexcept; +``` + +### Parameters + +*ec*\ +The status error code. + +## See also + +[``](../standard-library/experimental-filesystem.md)\ +[`path` class](../standard-library/experimental-filesystem-path-class.md) diff --git a/docs/standard-library/experimental-filesystem-directory-iterator-class.md b/docs/standard-library/experimental-filesystem-directory-iterator-class.md new file mode 100644 index 0000000000..e957505d84 --- /dev/null +++ b/docs/standard-library/experimental-filesystem-directory-iterator-class.md @@ -0,0 +1,169 @@ +--- +description: "Learn more about: directory_iterator class" +title: " directory_iterator class" +ms.date: 08/27/2026 +f1_keywords: ["filesystem/std::experimental::filesystem::directory_iterator", "filesystem/std::experimental::filesystem::directory_iterator::directory_iterator", "filesystem/std::experimental::filesystem::directory_iterator::increment", "filesystem/std::experimental::filesystem::directory_iterator::operator=", "filesystem/std::experimental::filesystem::directory_iterator::operator==", "filesystem/std::experimental::filesystem::directory_iterator::operator!=", "filesystem/std::experimental::filesystem::directory_iterator::operator*", "filesystem/std::experimental::filesystem::directory_iterator::operator->", "filesystem/std::experimental::filesystem::directory_iterator::operator++"] +helpviewer_keywords: ["std::experimental::filesystem::directory_iterator", "std::experimental::filesystem::directory_iterator::directory_iterator", "std::experimental::filesystem::directory_iterator::increment", "std::experimental::filesystem::directory_iterator::operator=", "std::experimental::filesystem::directory_iterator::operator==", "std::experimental::filesystem::directory_iterator::operator!=", "std::experimental::filesystem::directory_iterator::operator*", "std::experimental::filesystem::directory_iterator::operator->", "std::experimental::filesystem::directory_iterator::operator++"] +--- + +# `` `directory_iterator` class + +> [!IMPORTANT] +> This page describes the `directory_iterator` class from the prestandard `` implementation of the ISO C++ Filesystem Technical Specification (N4100). This API isn't the same as the C++17 [`directory_iterator`](directory-iterator-class.md) class in ``. It uses different signatures, including a narrower set of constructors that has no `directory_options` overload. The experimental implementation was removed starting with the Microsoft Visual C++ (MSVC) 14.51 toolset. New code should use the C++17 [`directory_iterator`](directory-iterator-class.md) class instead. + +Describes an input iterator that sequences through the filenames in a directory. For an iterator `X`, the expression `*X` evaluates to an object of class `directory_entry` that wraps the filename and anything known about its status. + +The class stores an object of type `path`, called `mydir` here for the purposes of exposition, which represents the name of the directory to be sequenced, and an object of type `directory_entry` called `myentry` here, which represents the current filename in the directory sequence. A default constructed object of type `directory_entry` has an empty `mydir` pathname and represents the end-of-sequence iterator. + +For example, given the directory `abc` with entries `def` and `ghi`, the code: + +`for (directory_iterator next(path("abc")), end; next != end; ++next) visit(next->path());` + +calls `visit` with the arguments `path("abc/def")` and `path("abc/ghi")`. + +## Syntax + +```cpp +class directory_iterator; +``` + +### Constructors + +|Constructor|Description| +|-|-| +|[`directory_iterator`](#directory_iterator)|Constructs an input iterator that sequences through the filenames in a directory.| + +### Member functions + +|Member function|Description| +|-|-| +|[`increment`](#increment)|Attempts to advance to the next filename in the directory.| + +### Operators + +|Operator|Description| +|-|-| +|[`operator!=`](#op_neq)|Returns `!(*this == right)`.| +|[`operator=`](#op_as)|The defaulted member assignment operators behave as expected.| +|[`operator==`](#op_eq)|Returns **`true`** only if both **`*this`** and *`right`* are end-of-sequence iterators or both aren't end-of-sequence-iterators.| +|[`operator*`](#op_star)|Returns `myentry`.| +|[`operator->`](#op_cast)|Returns `&**this`.| +|[`operator++`](#op_increment)|Calls `increment()`, then returns **`*this`**, or makes a copy of the object, calls `increment()`, then returns the copy.| + +## Requirements + +**Header:** `` + +**Namespace:** `std::experimental::filesystem` + +## `directory_iterator::directory_iterator` + +The first constructor produces an end-of-sequence iterator. The constructors that take a *`pval`* argument store it in `mydir`, then attempt to open and read `mydir` as a directory. If successful, they store the first filename in the directory in `myentry`; otherwise they produce an end-of-sequence iterator. The overload that takes an *`ec`* argument reports errors in *`ec`* instead of throwing an exception. The copy and move constructors behave as expected. + +```cpp +directory_iterator() noexcept; +explicit directory_iterator(const path& pval); + +directory_iterator(const path& pval, error_code& ec) noexcept; +directory_iterator(const directory_iterator&) = default; +directory_iterator(directory_iterator&&) = default; +``` + +### Parameters + +*`pval`*\ +The stored file name path. + +*`ec`*\ +The status error code. + +*`directory_iterator`*\ +The stored object. + +## `directory_iterator::increment` + +The function attempts to advance to the next filename in the directory. If successful, it stores that filename in `myentry`; otherwise it produces an end-of-sequence iterator. + +```cpp +directory_iterator& increment(error_code& ec) noexcept; +``` + +### Parameters + +*`ec`*\ +The status error code. + +## `directory_iterator::operator!=` + +The operator returns `!(*this == right)`. + +```cpp +bool operator!=(const directory_iterator& right) const; +``` + +### Parameters + +*`right`*\ +The `directory_iterator` being compared to the `directory_iterator`. + +## `directory_iterator::operator=` + +The defaulted member assignment operators behave as expected. + +```cpp +directory_iterator& operator=(const directory_iterator&) = default; +directory_iterator& operator=(directory_iterator&&) = default; +``` + +### Parameters + +*`right`*\ +The `directory_iterator` being copied into the `directory_iterator`. + +## `directory_iterator::operator==` + +The operator returns **`true`** only if both **`*this`** and *`right`* are end-of-sequence iterators or both aren't end-of-sequence-iterators. + +```cpp +bool operator==(const directory_iterator& right) const; +``` + +### Parameters + +*`right`*\ +The `directory_iterator` being compared to the `directory_iterator`. + +## `directory_iterator::operator*` + +The member operator returns `myentry`. + +```cpp +const directory_entry& operator*() const; +``` + +## `directory_iterator::operator->` + +The member function returns `&**this`. + +```cpp +const directory_entry * operator->() const; +``` + +## `directory_iterator::operator++` + +The first member function calls `increment()`, then returns **`*this`**. The second member function makes a copy of the object, calls `increment()`, then returns the copy. + +```cpp +directory_iterator& operator++(); +directory_iterator operator++(int); +``` + +### Parameters + +*`int`*\ +Dummy argument. It's a C++ convention used only to distinguish the postfix increment operator from the prefix increment operator. The C++ standard requires the postfix form to take a dummy int parameter. + +## See also + +[``](../standard-library/experimental-filesystem.md)\ +[`directory_entry` class](../standard-library/experimental-filesystem-directory-entry-class.md) diff --git a/docs/standard-library/experimental-filesystem-enumerations.md b/docs/standard-library/experimental-filesystem-enumerations.md new file mode 100644 index 0000000000..2cc015abae --- /dev/null +++ b/docs/standard-library/experimental-filesystem-enumerations.md @@ -0,0 +1,162 @@ +--- +description: "Learn more about: enumerations" +title: " enumerations" +ms.date: 08/27/2026 +f1_keywords: ["filesystem/std::experimental::filesystem::copy_options", "filesystem/std::experimental::filesystem::directory_options", "filesystem/std::experimental::filesystem::file_type", "filesystem/std::experimental::filesystem::perms"] +helpviewer_keywords: ["std::experimental::filesystem::copy_options", "std::experimental::filesystem::directory_options", "std::experimental::filesystem::file_type", "std::experimental::filesystem::perms"] +--- +# `` enumerations + +> [!IMPORTANT] +> The `` header and the `std::experimental::filesystem` namespace provided a prestandard implementation of the File System Technical Specification (TS). This documentation is retained for code written against MSVC's original filesystem implementation, which was removed starting in MSVC version 14.51. For new code, use the C++17 [``](../standard-library/filesystem.md) header and the `std::filesystem` namespace instead. For the standard equivalents of these enumerations, see [`` enumerations](../standard-library/filesystem-enumerations.md). + +This article documents the enumerations in the historical prestandard `std::experimental::filesystem` implementation. + +## Requirements + +**Header:** `` + +**Namespace:** `std::experimental::filesystem` + +## copy_options + +An enumeration of bitmask values that is used with [copy](experimental-filesystem-functions.md#copy) and [copy_file](experimental-filesystem-functions.md#copy_file) functions to specify behavior. + +### Syntax + +```cpp +enum class copy_options { + none = 0, + skip_existing = 1, + overwrite_existing = 2, + update_existing = 4, + recursive = 8, + copy_symlinks = 16, + skip_symlinks = 32, + directories_only = 64, + create_symlinks = 128, + create_hard_links = 256 +}; +``` + +### Values + +| Name | Description | +|------------|-----------------| +|`none`|Perform the default behavior for the operation.| +|`skip_existing`|Do not copy if the file already exists, do not report an error.| +|`overwrite_existing`|Overwrite the file if it already exists.| +|`update_existing`|Overwrite the file if it already exists and is older than the replacement.| +|`recursive`|Recursively copy subdirectories and their contents.| +|`copy_symlinks`|Copy symbolic links as symbolic links, instead of copying the files they point to.| +|`skip_symlinks`|Ignore symbolic links.| +|`directories_only`|Only iterate over directories, ignore files.| +|`create_symlinks`|Make symbolic links instead of copying files. An absolute path must be used as the source path unless the destination is the current directory.| +|`create_hard_links`|Make hard links instead of copying files.| + +## directory_options + +A bitmask enumeration that controls how directory iteration handles symbolic links to directories. + +### Syntax + +```cpp +enum class directory_options { + none = 0, + follow_directory_symlink = 1 +}; +``` + +### Values + +|Name|Description| +|----------|-----------------| +|`none`|Default behavior: don't follow symbolic links to directories.| +|`follow_directory_symlink`|Follow symbolic links to directories rather than skipping them.| + +## file_type + +An enumeration for file types. + +### Syntax + +```cpp +enum class file_type { + not_found = -1, + none = 0, + regular, + directory, + symlink, + block, + character, + fifo, + socket, + unknown +}; +``` + +The underlying integer values of these enumerators aren't fixed, so don't depend on specific numeric values. + +### Values + +|Name|Description| +|----------|-----------------| +|`none`|The file type hasn't been evaluated yet, or an error occurred when evaluating it.| +|`not_found`|The file wasn't found.| +|`regular`|A regular file.| +|`directory`|A directory.| +|`symlink`|A symbolic link.| +|`block`|A block-special file. (Not used on Windows.)| +|`character`|A character-special file. (Not used on Windows.)| +|`fifo`|A FIFO or pipe file. (Not used on Windows.)| +|`socket`|A socket. (Not used on Windows.)| +|`unknown`|The file exists but its type can't be determined.| + +## perms + +A bitmask enumeration of file permission bits together with the control flags that the [`permissions`](experimental-filesystem-functions.md#permissions) function uses to decide how to apply those bits. On Windows, the supported permission values are essentially "read-only" and `all`. For a read-only file, none of the `*_write` bits are set. Otherwise, the `all` bit (0777) is set. + +### Syntax + +```cpp +enum class perms {// names for permissions + none = 0, + owner_read = 0400, // S_IRUSR + owner_write = 0200, // S_IWUSR + owner_exec = 0100, // S_IXUSR + owner_all = 0700, // S_IRWXU + group_read = 040, // S_IRGRP + group_write = 020, // S_IWGRP + group_exec = 010, // S_IXGRP + group_all = 070, // S_IRWXG + others_read = 04, // S_IROTH + others_write = 02, // S_IWOTH + others_exec = 01, // S_IXOTH + others_all = 07, // S_IRWXO + all = 0777, + set_uid = 04000, // S_ISUID + set_gid = 02000, // S_ISGID + sticky_bit = 01000, // S_ISVTX + mask = 07777, + unknown = 0xFFFF, + add_perms = 0x10000, // control flag + remove_perms = 0x20000, // control flag + resolve_symlinks = 0x40000 // control flag +}; +``` + +### Control flags + +Unlike the C++17 `std::filesystem` implementation, which controls the `permissions` function with a separate `perm_options` enumeration, the prestandard TS implementation carries the control flags in `perms` itself. + +|Name|Description| +|----------|-----------------| +|`add_perms`|Add the specified permission bits to the file's current permissions instead of replacing them.| +|`remove_perms`|Remove the specified permission bits from the file's current permissions.| +|`resolve_symlinks`|Resolve symbolic links so the permission change applies to the target file rather than the link.| + +## See also + +[``](../standard-library/experimental-filesystem.md)\ +[`` functions](../standard-library/experimental-filesystem-functions.md)\ +[`` operators](../standard-library/experimental-filesystem-operators.md) diff --git a/docs/standard-library/experimental-filesystem-error-class.md b/docs/standard-library/experimental-filesystem-error-class.md new file mode 100644 index 0000000000..1acb0db702 --- /dev/null +++ b/docs/standard-library/experimental-filesystem-error-class.md @@ -0,0 +1,105 @@ +--- +description: "Learn more about: filesystem_error Class" +title: " filesystem_error Class" +ms.date: 08/27/2026 +f1_keywords: ["filesystem/std::experimental::filesystem::filesystem_error"] +--- +# `` filesystem_error Class + +> [!IMPORTANT] +> This article describes the prestandard `` implementation of `filesystem_error`. It documents the historical File System Technical Specification ([ISO/IEC JTC 1/SC 22/WG 21 N4100](https://wg21.link/n4100)), not the C++17 `std::filesystem::filesystem_error` class. The experimental implementation was removed starting with MSVC version 14.51. For current code, use the standard [filesystem_error Class](../standard-library/filesystem-error-class.md). + +A base class for all exceptions that are thrown to report a low-level system error. + +## Syntax + +```cpp +class filesystem_error : public system_error; +``` + +## Remarks + +The class serves as the base class for all exceptions thrown to report an error in \ functions. It stores an object of type `string`, called `mymesg` here for the purposes of exposition. It also stores two objects of type `path`, called `mypval1` and `mypval2`. + +## Members + +### Constructors + +|Name|Description| +|-|-| +|[filesystem_error](#filesystem_error)|Constructs a `filesystem_error` message.| + +### Functions + +|Name|Description| +|-|-| +|[path1](#path1)|Returns `mypval1`| +|[path2](#path2)|Returns `mypval2`| +|[what](#what)|Returns a pointer to an `NTBS`.| + +## Requirements + +**Header:** \ + +**Namespace:** std::experimental::filesystem + +## filesystem_error + +The first constructor constructs its message from *what_arg* and *ec*. The second constructor also constructs its message from *pval1*, which it stores in `mypval1`. The third constructor also constructs its message from *pval1*, which it stores in `mypval1`, and from *pval2*, which it stores in `mypval2`. + +```cpp +filesystem_error(const string& what_arg, + error_code ec); + +filesystem_error(const string& what_arg, + const path& pval1, + error_code ec); + +filesystem_error(const string& what_arg, + const path& pval1, + const path& pval2, + error_code ec); +``` + +### Parameters + +*what_arg*\ +Specified message. + +*ec*\ +Specified error code. + +*mypval1*\ +Further specified message parameter. + +*mypval2*\ +Further specified message parameter. + +## path1 + +The member function returns `mypval1` + +```cpp +const path& path1() const noexcept; +``` + +## path2 + +The member function returns `mypval2` + +```cpp +const path& path2() const noexcept; +``` + +## what + +The member function returns a pointer to an `NTBS`, preferably composed from `runtime_error::what()`, `system_error::what()`, `mymesg`, `mypval1.native_string()`, and `mypval2.native_string()`. + +```cpp +const char *what() const noexcept; +``` + +## See also + +[``](../standard-library/experimental-filesystem.md)\ +[`path` class](../standard-library/experimental-filesystem-path-class.md) diff --git a/docs/standard-library/experimental-filesystem-file-status-class.md b/docs/standard-library/experimental-filesystem-file-status-class.md new file mode 100644 index 0000000000..9631d6b51f --- /dev/null +++ b/docs/standard-library/experimental-filesystem-file-status-class.md @@ -0,0 +1,120 @@ +--- +title: " file_status Class" +description: "Learn more about: file_status Class" +ms.date: 08/27/2026 +f1_keywords: ["filesystem/std::experimental::filesystem::file_status", "filesystem/std::experimental::filesystem::file_status::operator=", "filesystem/std::experimental::filesystem::file_status::type", "filesystem/std::experimental::filesystem::file_status::permissions"] +helpviewer_keywords: ["std::experimental::filesystem::file_status", "std::experimental::filesystem::file_status::operator=", "std::experimental::filesystem::file_status::type", "std::experimental::filesystem::file_status::permissions"] +--- +# `` file_status class + +> [!IMPORTANT] +> This article describes the prestandard `` implementation of `file_status`. It documents the historical File System Technical Specification ([ISO/IEC JTC 1/SC 22/WG 21 N4100](https://wg21.link/n4100)), not the C++17 `std::filesystem::file_status` class. The experimental implementation was removed starting with MSVC version 14.51. For current code, use the standard [file_status Class](../standard-library/file-status-class.md). + +Wraps a [`file_type`](../standard-library/experimental-filesystem-enumerations.md#file_type) and file [`perms`](../standard-library/experimental-filesystem-enumerations.md#perms). + +## Syntax + +```cpp +class file_status; +``` + +### Constructors + +|Constructor|Description| +|-|-| +|[file_status](#file_status)|Constructs a wrapper for [`file_type`](../standard-library/experimental-filesystem-enumerations.md#file_type) and file [`perms`](../standard-library/experimental-filesystem-enumerations.md#perms).| + +### Member functions + +|Member function|Description| +|-|-| +|[type](#type)|Gets or sets the `file_type`.| +|[permissions](#permissions)|Gets or sets the file permissions.| + +### Operators + +|Operator|Description| +|-|-| +|[operator=](#op_as)|The defaulted member assignment operators behave as expected.| + +## Requirements + +**Header:** \ + +**Namespace:** std::experimental::filesystem + +## file_status::file_status + +Constructs a wrapper for [`file_type`](../standard-library/experimental-filesystem-enumerations.md#file_type) and file [`perms`](../standard-library/experimental-filesystem-enumerations.md#perms). + +```cpp +explicit file_status( + file_type ftype = file_type::none, + perms mask = perms::unknown) noexcept; + +file_status(const file_status&) noexcept = default; + +file_status(file_status&&) noexcept = default; + +~file_status() noexcept = default; +``` + +### Parameters + +*ftype*\ +Specified `file_type`, defaults to `file_type::none`. + +*mask*\ +Specified file `perms`, defaults to `perms::unknown`. + +*file_status*\ +The stored object. + +## file_status::operator= + +The defaulted member assignment operators behave as expected. + +```cpp +file_status& operator=(const file_status&) noexcept = default; +file_status& operator=(file_status&&) noexcept = default; +``` + +### Parameters + +*file_status*\ +The [file_status](../standard-library/experimental-filesystem-file-status-class.md) being copied into the `file_status`. + +## type + +Gets or sets the `file_type`. + +```cpp +file_type type() const noexcept; +void type(file_type ftype) noexcept; +``` + +### Parameters + +*ftype*\ +Specified `file_type`. + +## permissions + +Gets or sets the file permissions. + +Use the setter to make a file `readonly` or remove the `readonly` attribute. + +```cpp +perms permissions() const noexcept; +void permissions(perms mask) noexcept; +``` + +### Parameters + +*mask*\ +Specified `perms`. + +## See also + +[``](../standard-library/experimental-filesystem.md)\ +[`path` class](../standard-library/experimental-filesystem-path-class.md) diff --git a/docs/standard-library/experimental-filesystem-functions.md b/docs/standard-library/experimental-filesystem-functions.md new file mode 100644 index 0000000000..c9d6bbc5ef --- /dev/null +++ b/docs/standard-library/experimental-filesystem-functions.md @@ -0,0 +1,497 @@ +--- +title: " functions" +description: "Learn more about: functions" +ms.date: 08/27/2026 +f1_keywords: ["filesystem/std::experimental::filesystem::absolute", "filesystem/std::experimental::filesystem::begin", "filesystem/std::experimental::filesystem::canonical", "filesystem/std::experimental::filesystem::copy", "filesystem/std::experimental::filesystem::copy_file", "filesystem/std::experimental::filesystem::copy_symlink", "filesystem/std::experimental::filesystem::create_directories", "filesystem/std::experimental::filesystem::create_directory", "filesystem/std::experimental::filesystem::create_directory_symlink", "filesystem/std::experimental::filesystem::create_hard_link", "filesystem/std::experimental::filesystem::create_symlink", "filesystem/std::experimental::filesystem::current_path", "filesystem/std::experimental::filesystem::end", "filesystem/std::experimental::filesystem::equivalent", "filesystem/std::experimental::filesystem::exists", "filesystem/std::experimental::filesystem::file_size", "filesystem/std::experimental::filesystem::hard_link_count", "filesystem/std::experimental::filesystem::hash_value", "filesystem/std::experimental::filesystem::is_block_file", "filesystem/std::experimental::filesystem::is_character_file", "filesystem/std::experimental::filesystem::is_directory", "filesystem/std::experimental::filesystem::is_empty", "filesystem/std::experimental::filesystem::is_fifo", "filesystem/std::experimental::filesystem::is_other", "filesystem/std::experimental::filesystem::is_regular_file", "filesystem/std::experimental::filesystem::is_socket", "filesystem/std::experimental::filesystem::is_symlink", "filesystem/std::experimental::filesystem::last_write_time", "filesystem/std::experimental::filesystem::permissions", "filesystem/std::experimental::filesystem::read_symlink", "filesystem/std::experimental::filesystem::remove", "filesystem/std::experimental::filesystem::remove_all", "filesystem/std::experimental::filesystem::rename", "filesystem/std::experimental::filesystem::resize_file", "filesystem/std::experimental::filesystem::space", "filesystem/std::experimental::filesystem::status", "filesystem/std::experimental::filesystem::status_known", "filesystem/std::experimental::filesystem::swap", "filesystem/std::experimental::filesystem::symlink_status", "filesystem/std::experimental::filesystem::system_complete", "filesystem/std::experimental::filesystem::temp_directory_path", "filesystem/std::experimental::filesystem::u8path"] +helpviewer_keywords: ["std::experimental::filesystem::absolute", "std::experimental::filesystem::begin", "std::experimental::filesystem::canonical", "std::experimental::filesystem::copy", "std::experimental::filesystem::copy_file", "std::experimental::filesystem::copy_symlink", "std::experimental::filesystem::create_directories", "std::experimental::filesystem::create_directory", "std::experimental::filesystem::create_directory_symlink", "std::experimental::filesystem::create_hard_link", "std::experimental::filesystem::create_symlink", "std::experimental::filesystem::current_path", "std::experimental::filesystem::end", "std::experimental::filesystem::equivalent", "std::experimental::filesystem::exists", "std::experimental::filesystem::file_size", "std::experimental::filesystem::hard_link_count", "std::experimental::filesystem::hash_value", "std::experimental::filesystem::is_block_file", "std::experimental::filesystem::is_character_file", "std::experimental::filesystem::is_directory", "std::experimental::filesystem::is_empty", "std::experimental::filesystem::is_fifo", "std::experimental::filesystem::is_other", "std::experimental::filesystem::is_regular_file", "std::experimental::filesystem::is_socket", "std::experimental::filesystem::is_symlink", "std::experimental::filesystem::last_write_time", "std::experimental::filesystem::permissions", "std::experimental::filesystem::read_symlink", "std::experimental::filesystem::remove", "std::experimental::filesystem::remove_all", "std::experimental::filesystem::rename", "std::experimental::filesystem::resize_file", "std::experimental::filesystem::space", "std::experimental::filesystem::status", "std::experimental::filesystem::status_known", "std::experimental::filesystem::swap", "std::experimental::filesystem::symlink_status", "std::experimental::filesystem::system_complete", "std::experimental::filesystem::temp_directory_path", "std::experimental::filesystem::u8path"] +--- +# `` functions + +> [!IMPORTANT] +> The `` header and the `std::experimental::filesystem` namespace provided a prestandard implementation of the File System Technical Specification (TS). This documentation is retained for code written against MSVC's original filesystem implementation, which was removed starting in MSVC version 14.51. For new code, use the C++17 [``](../standard-library/filesystem.md) header and the `std::filesystem` namespace instead. For the standard equivalents of these functions, see [`` functions](../standard-library/filesystem-functions.md). + +These free functions in the `` header do modifying and query operations on paths, files, symlinks, directories, and volumes. For more information and code examples, see [File System Navigation (C++)](../standard-library/file-system-navigation.md). + +## Requirements + +**Header:** `` + +**Namespace:** `std::experimental::filesystem` + +## `absolute` + +```cpp +path absolute(const path& pval, const path& base = current_path()); +``` + +The function returns the absolute pathname corresponding to *`pval`* relative to the pathname `base`: + +1. If `pval.has_root_name() && pval.has_root_directory()` the function returns *`pval`*. + +1. If `pval.has_root_name() && !pval.has_root_directory()` the function returns `pval.root_name()` / `absolute(base).root_directory()` / `absolute(base).relative_path()` / `pval.relative_path()`. + +1. If `!pval.has_root_name() && pval.has_root_directory()` the function returns `absolute(base).root_name()` / *`pval`*. + +1. If `!pval.has_root_name() && !pval.has_root_directory()` the function returns `absolute(base)` / *`pval`*. + +## `begin` + +```cpp +const directory_iterator& begin(const directory_iterator& iter) noexcept; +const recursive_directory_iterator& + begin(const recursive_directory_iterator& iter) noexcept; +``` + +Both functions return *`iter`*. + +## `canonical` + +```cpp +path canonical(const path& pval, const path& base = current_path()); +path canonical(const path& pval, error_code& ec); +path canonical(const path& pval, const path& base, error_code& ec); +``` + +The functions all form an absolute pathname `pabs = absolute(pval, base)` (or `pabs = absolute(pval)` for the overload with no base parameter), then reduce it to a canonical form in the following sequence of steps: + +1. Replace every path component `X` for which `is_symlink(X)` is **`true`** with `read_symlink(X)`. + +1. Remove every path component `.` (dot is the current directory established by previous path components). + +1. Remove every pair of path components `X`/`..` (dot-dot is the parent directory established by previous path components). + +The function then returns `pabs`. + +## `copy` + +```cpp +void copy(const path& from, const path& to); +void copy(const path& from, const path& to, error_code& ec) noexcept; +void copy(const path& from, const path& to, copy_options opts); +void copy(const path& from, const path& to, copy_options opts, error_code& ec) noexcept; +``` + +The functions all possibly copy or link one or more files at `from` to `to` under control of *`opts`*, which is taken as `copy_options::none` for the overloads with no *`opts`* parameter. *`opts`* shall contain at most one of: + +- `skip_existing`, `overwrite_existing`, or `update_existing` + +- `copy_symlinks` or `skip_symlinks` + +- `directories_only`, `create_symlinks`, or `create_hard_links` + +The functions first determine the `file_status` values `f` for `from` and `t` for `to`. They use `symlink_status` when *`opts`* contains `copy_options::create_symlinks`, `copy_options::skip_symlinks`, or `copy_options::copy_symlinks`, as required for the source or destination. Otherwise, they use `status`. + +If `!exists(f) || equivalent(f, t) || is_other(f) || is_other(t) || is_directory(f)&& is_regular_file(t)`, the functions report an error and stop. Otherwise, if `is_symlink(f)`, then: + + +- If `options & copy_options::skip_symlinks`, then do nothing. + +- Otherwise, if `!exists(t) && options & copy_options::copy_symlinks`, then `copy_symlink(from, to)`. + +- Otherwise, report an error. + +Otherwise, if `is_regular_file(f)`, then: + +- If `opts & copy_options::directories_only`, then do nothing. + +- Otherwise, if `opts & copy_options::create_symlinks`, then `create_symlink(from, to)`. + +- Otherwise, if `opts & copy_options::create_hard_links`, then `create_hard_link(from, to)`. + +- Otherwise, if `is_directory(t)`, then `copy_file(from, to / from.filename(), opts)`. + +- Otherwise, `copy_file(from, to, opts)`. + +Otherwise, if `is_directory(f) && (opts & copy_options::recursive || !opts)`, then: + +```cpp +if (!exists(t)) +{ // copy directory contents recursively + create_directory(to, from, ec); + + for (directory_iterator next(from), end; ec == error_code() && next != end; ++next) + { + copy(next->path(), to / next->path().filename(), opts, ec); + } +} +``` + +Otherwise, do nothing. + +## `copy_file` + +```cpp +bool copy_file(const path& from, const path& to); +bool copy_file(const path& from, const path& to, error_code& ec) noexcept; +bool copy_file(const path& from, const path& to, copy_options opts); +bool copy_file(const path& from, const path& to, copy_options opts, error_code& ec) noexcept; +``` + +The functions all possibly copy the file at `from` to `to` under control of *`opts`*, which is taken as `copy_options::none` for the overloads with no *`opts`* parameter. *`opts`* shall contain at most one of `skip_existing`, `overwrite_existing`, or `update_existing`. + +If `exists(to) && !(opts & (copy_options::skip_existing | copy_options::overwrite_existing | copy_options::update_existing))`, then report as an error that the file already exists. + +Otherwise, if `!exists(to) || opts & copy_options::overwrite_existing || opts & copy_options::update_existing&& last_write_time(to) < last_write_time(from) || !(opts & (copy_options::skip_existing | copy_options::overwrite_existing | copy_options::update_existing))`, then attempt to copy the contents and attributes of the file `from` to the file `to`. Report as an error if the copy attempt fails. + +The functions return **`true`** if the copy is successful, and **`false`** otherwise. + +## `copy_symlink` + +```cpp +void copy_symlink(const path& from, const path& to); +void copy_symlink(const path& from, const path& to, error_code& ec) noexcept; +``` + +If `is_directory(from)`, the function calls `create_directory_symlink(from, to)`. Otherwise, it calls `create_symlink(from, to)`. + +## `create_directories` + +```cpp +bool create_directories(const path& pval); +bool create_directories(const path& pval, error_code& ec) noexcept; +``` + +For a pathname such as `a\/b\/c`, the function creates directories `a` and `a\/b` as needed so that it can create the directory `a\/b\/c`. It returns **`true`** only if it actually creates the directory *`pval`*. + +## `create_directory` + +```cpp +bool create_directory(const path& pval); + +bool create_directory(const path& pval, error_code& ec) noexcept; +bool create_directory(const path& pval, const path& attr); +bool create_directory(const path& pval, const path& attr, error_code& ec) noexcept; +``` + +The function creates the directory *`pval`* as needed. It returns `true` only if it actually creates the directory *`pval`*. If you specify the `attr` parameter, the function copies permissions from the existing file. If you don't specify the `attr` parameter, the function uses `perms::all`. + +## `create_directory_symlink` + +```cpp +void create_directory_symlink(const path& to, const path& link); +void create_directory_symlink(const path& to, const path& link, error_code& ec) noexcept; +``` + +The function creates *`link`* as a symlink to the directory `to`. + +## `create_hard_link` + +```cpp +void create_hard_link(const path& to, const path& link); +void create_hard_link(const path& to, const path& link, error_code& ec) noexcept; +``` + +The function creates *`link`* as a hard link to the directory or file `to`. + +## `create_symlink` + +```cpp +void create_symlink(const path& to, const path& link); + +void create_symlink(const path& to, const path& link, error_code& ec) noexcept; +``` + +The function creates *`link`* as a symlink to the file `to`. + +## `current_path` + +```cpp +path current_path(); +path current_path(error_code& ec); +void current_path(const path& pval); +void current_path(const path& pval, error_code& ec) noexcept; +``` + +The functions with no parameter *`pval`* return the pathname for the current directory. The remaining functions set the current directory to *`pval`*. + +## `end` + +```cpp +directory_iterator end(const directory_iterator&) noexcept; +recursive_directory_iterator end(const recursive_directory_iterator&) noexcept; +``` + +The first function returns `directory_iterator()` and the second function returns `recursive_directory_iterator()`. + +## `equivalent` + +```cpp +bool equivalent(const path& left, const path& right); +bool equivalent(const path& left, const path& right, error_code& ec) noexcept; +``` + +The functions return **`true`** only if *left* and *right* refer to the same filesystem entity. + +## `exists` + +```cpp +bool exists(file_status stat) noexcept; +bool exists(const path& pval); +bool exists(const path& pval, error_code& ec) noexcept; +``` + +The first function returns `status_known(stat) && stat.type() != file_type::not_found`. The second and third functions return `exists(status(pval))`. + +## `file_size` + +```cpp +uintmax_t file_size(const path& pval); +uintmax_t file_size(const path& pval, error_code& ec) noexcept; +``` + +The functions return the size in bytes of the file chosen by *`pval`*, if `exists(pval) && is_regular_file(pval)` and the file size can be determined. Otherwise they report an error and return `uintmax_t(-1)`. + +## `hard_link_count` + +```cpp +uintmax_t hard_link_count(const path& pval); +uintmax_t hard_link_count(const path& pval, error_code& ec) noexcept; +``` + +The function returns the number of hard links for *`pval`*, or \-1 if an error occurs. + +## `hash_value` + +```cpp +size_t hash_value(const path& pval) noexcept; +``` + +The function returns a hash value for `pval.native()`. + +## `is_block_file` + +```cpp +bool is_block_file(file_status stat) noexcept; +bool is_block_file(const path& pval); +bool is_block_file(const path& pval, error_code& ec) noexcept; +``` + +The first function returns `stat.type() == file_type::block`. The remaining functions return `is_block_file(status(pval))`. + +## `is_character_file` + +```cpp +bool is_character_file(file_status stat) noexcept; +bool is_character_file(const path& pval); +bool is_character_file(const path& pval, error_code& ec) noexcept; +``` + +The first function returns `stat.type() == file_type::character`. The remaining functions return `is_character_file(status(pval))`. + +## `is_directory` + +```cpp +bool is_directory(file_status stat) noexcept; +bool is_directory(const path& pval); +bool is_directory(const path& pval, error_code& ec) noexcept; +``` + +The first function returns `stat.type() == file_type::directory`. The remaining functions return `is_directory(status(pval))`. + +## `is_empty` + +```cpp +bool is_empty(const path& pval); +bool is_empty(const path& pval, error_code& ec) noexcept; +``` + +If `is_directory(pval)`, the function returns `directory_iterator(pval) == directory_iterator()`. Otherwise, it returns `file_size(pval) == 0`. + +## `is_fifo` + +```cpp +bool is_fifo(file_status stat) noexcept; +bool is_fifo(const path& pval); +bool is_fifo(const path& pval, error_code& ec) noexcept; +``` + +The first function returns `stat.type() == file_type::fifo`. The remaining functions return `is_fifo(status(pval))`. + +## `is_other` + +```cpp +bool is_other(file_status stat) noexcept; +bool is_other(const path& pval); +bool is_other(const path& pval, error_code& ec) noexcept; +``` + +The first function returns `exists(stat) && !is_regular_file(stat) && !is_directory(stat) && !is_symlink(stat)`. The remaining functions return `is_other(status(pval))`. + +## `is_regular_file` + +```cpp +bool is_regular_file(file_status stat) noexcept; +bool is_regular_file(const path& pval); +bool is_regular_file(const path& pval, error_code& ec) noexcept; +``` + +The first function returns `stat.type() == file_type::regular`. The remaining functions return `is_regular_file(status(pval))`. + +## `is_socket` + +```cpp +bool is_socket(file_status stat) noexcept; +bool is_socket(const path& pval); +bool is_socket(const path& pval, error_code& ec) noexcept; +``` + +The first function returns `stat.type() == file_type::socket`. The remaining functions return `is_socket(status(pval))`. + +## `is_symlink` + +```cpp +bool is_symlink(file_status stat) noexcept; +bool is_symlink(const path& pval); +bool is_symlink(const path& pval, error_code& ec) noexcept; +``` + +The first function returns `stat.type() == file_type::symlink`. The remaining functions return `is_symlink(status(pval))`. + +## `last_write_time` + +```cpp +file_time_type last_write_time(const path& pval); +file_time_type last_write_time(const path& pval, error_code& ec) noexcept; +void last_write_time(const path& pval, file_time_type new_time); +void last_write_time(const path& pval, file_time_type new_time, error_code& ec) noexcept; +``` + +The first two functions return the time of last data modification for *`pval`*, or `file_time_type(-1)` if an error occurs. The last two functions set the time of last data modification for *`pval`* to *`new_time`*. + +## `permissions` + +```cpp +void permissions(const path& pval, perms mask); +void permissions(const path& pval, perms mask, error_code& ec) noexcept; +``` + +The functions set the permissions for the pathname chosen by *`pval`* to `mask & perms::mask` under control of `perms & (perms::add_perms | perms::remove_perms)`. *`mask`* contains at most one of `perms::add_perms` and `perms::remove_perms`. + +If `mask & perms::add_perms`, the functions set the permissions to `status(pval).permissions() | mask & perms::mask`. Otherwise, if `mask & perms::remove_perms`, the functions set the permissions to `status(pval).permissions() & ~(mask & perms::mask)`. Otherwise, the functions set the permissions to `mask & perms::mask`. + +## `read_symlink` + +```cpp +path read_symlink(const path& pval); +path read_symlink(const path& pval, error_code& ec); +``` + +The functions report an error and return `path()` if `!is_symlink(pval)`. Otherwise, the functions return an object of type `path` containing the symbolic link. + +## `remove` + +```cpp +bool remove(const path& pval); +bool remove(const path& pval, error_code& ec) noexcept; +``` + +The functions return **`true`** only if `exists(symlink_status(pval))` and the file is successfully removed. A symlink is itself removed, not the file it chooses. + +## `remove_all` + +```cpp +uintmax_t remove_all(const path& pval); +uintmax_t remove_all(const path& pval, error_code& ec) noexcept; +``` + +If *`pval`* is a directory, the functions recursively remove all directory entries, then the entry itself. Otherwise, the functions call `remove`. They return a count of all elements successfully removed. + +## `rename` + +```cpp +void rename(const path& from, const path& to); +void rename(const path& from, const path& to, error_code& ec) noexcept; +``` + +The functions rename `from` to `to`. A symlink is itself renamed, not the file it chooses. + +## `resize_file` + +```cpp +void resize_file(const path& pval, uintmax_t size); +void resize_file(const path& pval, uintmax_t size, error_code& ec) noexcept; +``` + +The functions alter the size of a file such that `file_size(pval) == size`. + +## `space` + +```cpp +space_info space(const path& pval); +space_info space(const path& pval, error_code& ec) noexcept; +``` + +The function returns information about the volume chosen by *`pval`*, in a structure of type `space_info`. The structure contains `uintmax_t(-1)` for any value that can't be determined. + +## `status` + +```cpp +file_status status(const path& pval); +file_status status(const path& pval, error_code& ec) noexcept; +``` + +The functions return the pathname status, the file type, and permissions, associated with *`pval`*. A symlink is itself not tested, but the file it chooses. + +## `status_known` + +```cpp +bool status_known(file_status stat) noexcept; +``` + +The function returns `stat.type() != file_type::none` + +## `swap` + +```cpp +void swap(path& left, path& right) noexcept; +``` + +The function exchanges the contents of *left* and *right*. + +## `symlink_status` + +```cpp +file_status symlink_status(const path& pval); +file_status symlink_status(const path& pval, error_code& ec) noexcept; +``` + +The functions return the pathname symlink status, the file type, and permissions, associated with *`pval`*. The functions behave the same as `status(pval)` except that a symlink is itself tested, not the file it chooses. + +## `system_complete` + +> [!NOTE] +> C++17 `std::filesystem` doesn't provide `system_complete`. For current code, use [`std::filesystem::absolute`](../standard-library/filesystem-functions.md#absolute) when it provides the required behavior. + +```cpp +path system_complete(const path& pval); +path system_complete(const path& pval, error_code& ec); +``` + +The functions return an absolute pathname that takes into account, as necessary, the current directory associated with its root name. For POSIX, the functions return `absolute(pval)`. + +## `temp_directory_path` + +```cpp +path temp_directory_path(); +path temp_directory_path(error_code& ec); +``` + +The functions return a pathname for a directory suitable for containing temporary files. + +## `u8path` + +```cpp +template +path u8path(const Source& source); + +template +path u8path(InIt first, InIt last); +``` + +The first function behaves the same as `path(source)` and the second function behaves the same as `path(first, last)` except that the chosen source in each case is taken as a sequence of char elements encoded as UTF-8, whatever the filesystem. + +## See also + +[``](../standard-library/experimental-filesystem.md)\ +[`` enumerations](../standard-library/experimental-filesystem-enumerations.md)\ +[`` operators](../standard-library/experimental-filesystem-operators.md) diff --git a/docs/standard-library/experimental-filesystem-operators.md b/docs/standard-library/experimental-filesystem-operators.md new file mode 100644 index 0000000000..2ee445fce0 --- /dev/null +++ b/docs/standard-library/experimental-filesystem-operators.md @@ -0,0 +1,108 @@ +--- +description: "Learn more about: operators" +title: " operators" +ms.date: 08/27/2026 +f1_keywords: ["filesystem/std::experimental::filesystem::operator==", "filesystem/std::experimental::filesystem::operator!=", "filesystem/std::experimental::filesystem::operator<", "filesystem/std::experimental::filesystem::operator<=", "filesystem/std::experimental::filesystem::operator>", "filesystem/std::experimental::filesystem::operator>=", "filesystem/std::experimental::filesystem::operator/", "filesystem/std::experimental::filesystem::operator<<", "filesystem/std::experimental::filesystem::operator>>"] +helpviewer_keywords: ["std::experimental::filesystem::operator==", "std::experimental::filesystem::operator!=", "std::experimental::filesystem::operator<", "std::experimental::filesystem::operator<=", "std::experimental::filesystem::operator>", "std::experimental::filesystem::operator>=", "std::experimental::filesystem::operator/", "std::experimental::filesystem::operator<<", "std::experimental::filesystem::operator>>"] +--- +# `` operators + +> [!IMPORTANT] +> The `` header and the `std::experimental::filesystem` namespace provided a prestandard implementation of the File System Technical Specification (TS). This documentation is retained for code written against MSVC's original filesystem implementation, which was removed starting in MSVC version 14.51. For new code, use the C++17 [``](../standard-library/filesystem.md) header and the `std::filesystem` namespace instead. For the standard equivalents of these operators, see [`` operators](../standard-library/filesystem-operators.md). + +These nonmember operators for `std::experimental::filesystem::path` are declared in the historical `` header. The comparison operators compare two paths element by element in generic format by using `path::compare`, not as raw strings. Use the [`equivalent`](../standard-library/experimental-filesystem-functions.md#equivalent) function to determine whether two paths (for example, a relative path and an absolute path) refer to the same file or directory on disk. + +For more information, see [File System Navigation (C++)](../standard-library/file-system-navigation.md). + +## Requirements + +**Header:** `` + +**Namespace:** `std::experimental::filesystem` + +## operator== + +```cpp +bool operator==(const path& left, const path& right) noexcept; +``` + +The function returns `left.compare(right) == 0`. + +## operator!= + +```cpp +bool operator!=(const path& left, const path& right) noexcept; +``` + +The function returns `!(left == right)`. + +## operator< + +```cpp +bool operator<(const path& left, const path& right) noexcept; +``` + +The function returns `left.compare(right) < 0`. + +## operator<= + +```cpp +bool operator<=(const path& left, const path& right) noexcept; +``` + +The function returns `!(right < left)`. + +## operator> + +```cpp +bool operator>(const path& left, const path& right) noexcept; +``` + +The function returns `right < left`. + +## operator>= + +```cpp +bool operator>=(const path& left, const path& right) noexcept; +``` + +The function returns `!(left < right)`. + +## operator/ + +```cpp +path operator/(const path& left, const path& right); +``` + +The function returns `path(left) /= right`. + +## operator<< + +```cpp +template +basic_ostream& operator<<(basic_ostream& os, const path& pval); +``` + +The function inserts the path's string representation into the stream. It returns `os << pval.string()`. + +## operator>> + +```cpp +template +basic_istream& operator>>(basic_istream& is, path& pval); +``` + +The function extracts a string from the stream and assigns it to *`pval`*. It executes: + +```cpp +basic_string str; +is >> str; +pval = str; +return is; +``` + +## See also + +[``](../standard-library/experimental-filesystem.md)\ +[`` functions](../standard-library/experimental-filesystem-functions.md)\ +[`` enumerations](../standard-library/experimental-filesystem-enumerations.md) diff --git a/docs/standard-library/experimental-filesystem-path-class.md b/docs/standard-library/experimental-filesystem-path-class.md new file mode 100644 index 0000000000..61de5d684a --- /dev/null +++ b/docs/standard-library/experimental-filesystem-path-class.md @@ -0,0 +1,852 @@ +--- +title: " path class" +description: "Learn more about the removed Microsoft prestandard std::experimental::filesystem path class." +ms.date: 08/27/2026 +f1_keywords: ["filesystem/std::experimental::filesystem::path"] +helpviewer_keywords: ["std::experimental::filesystem::path class"] +--- +# `` path class + +> [!IMPORTANT] +> This page documents the removed Microsoft prestandard `std::experimental::filesystem::path` implementation provided by the `` header. It is **not** the C++17 `std::filesystem::path` class. This prestandard implementation is based on the *File System Technical Specification* (N4100) and predates C++17 `std::filesystem`. The `` header and the `std::experimental::filesystem` namespace are removed starting in the Microsoft Visual C++ toolset 14.51. For the current, supported C++17 implementation, see [`path` class](path-class.md). + +The **`path`** class stores an object of type `string_type`, called `myname` here for the purposes of exposition, suitable for use as a pathname. `string_type` is a synonym for `basic_string`, where `value_type` is a synonym for **`wchar_t`** on Windows. + +## Syntax + +```cpp +class path; +``` + +### Constructors + +|Constructor|Description| +|-|-| +|[`path`](#path)|Constructs a `path`.| + +### Typedefs + +|Type name|Description| +|-|-| +|[`const_iterator`](#const_iterator)|A synonym for `iterator`.| +|[`iterator`](#iterator)|A bidirectional constant iterator that designates the `path` components of `myname`.| +|[`string_type`](#string_type)|The type is a synonym for `basic_string`.| + +### Member functions + +|Member function|Description| +|-|-| +|[`append`](#append)|Appends the specified sequence to `myname`, converted and inserting a preferred_separator as needed.| +|[`assign`](#assign)|Replaces `myname` with the specified sequence, converted as needed.| +|[`begin`](#begin)|Returns a `path::iterator` designating the first path element in the pathname, if present.| +|[`c_str`](#c_str)|Returns a pointer to the first character in `myname`.| +|[`clear`](#clear)|Executes `myname.clear()`.| +|[`compare`](#compare)|Returns comparison values.| +|[`concat`](#concat)|Appends the specified sequence to `myname`, converted (but not inserting a separator) as needed.| +|[`empty`](#empty)|Returns `myname.empty()`.| +|[`end`](#end)|Returns an end-of-sequence iterator of type `iterator`.| +|[`extension`](#extension)|Returns the suffix of `filename()`.| +|[`filename`](#filename)|Returns the filename component of `myname`, specifically `empty() ? path() : *--end()`. The component may be empty.| +|[`generic_string`](#generic_string)|Returns `this->string(al)` with (under Windows) any backslash converted to a forward slash.| +|[`generic_u16string`](#generic_u16string)|Returns `u16string()` with (under Windows) any backslash converted to a forward slash.| +|[`generic_u32string`](#generic_u32string)|Deleted in the historical MSVC implementation.| +|[`generic_u8string`](#generic_u8string)|Returns `u8string()` with (under Windows) any backslash converted to a forward slash.| +|[`generic_wstring`](#generic_wstring)|Returns `wstring()` with (under Windows) any backslash converted to a forward slash.| +|[`has_extension`](#has_extension)|Returns `!extension().empty()`.| +|[`has_filename`](#has_filename)|Returns `!filename().empty()`.| +|[`has_parent_path`](#has_parent_path)|Returns `!parent_path().empty()`.| +|[`has_relative_path`](#has_relative_path)|Returns `!relative_path().empty()`.| +|[`has_root_directory`](#has_root_directory)|Returns `!root_directory().empty()`.| +|[`has_root_name`](#has_root_name)|Returns `!root_name().empty()`.| +|[`has_root_path`](#has_root_path)|Returns `!root_path().empty()`.| +|[`has_stem`](#has_stem)|Returns `!stem().empty()`.| +|[`is_absolute`](#is_absolute)|For Windows, the function returns `has_root_name() && has_root_directory()`. For POSIX, the function returns `has_root_directory()`.| +|[`is_relative`](#is_relative)|Returns `!is_absolute()`.| +|[`make_preferred`](#make_preferred)|Converts each separator to a `preferred_separator` as needed.| +|[`native`](#native)|Returns the native representation of the path.| +|[`parent_path`](#parent_path)|Returns the parent path component of `myname`.| +|[`preferred_separator`](#preferred_separator)|The constant object gives the preferred character for separating path components, depending on the host operating system. | +|[`relative_path`](#relative_path)|Returns the relative path component of `myname`. | +|[`remove_filename`](#remove_filename)|Removes the filename.| +|[`replace_extension`](#replace_extension)|Replaces the extension of `myname`. | +|[`replace_filename`](#replace_filename)|Replaces the filename.| +|[`root_directory`](#root_directory)|Returns the root directory component of `myname`. | +|[`root_name`](#root_name)|Returns the root name component of `myname`. | +|[`root_path`](#root_path)|Returns the root path component of `myname`.| +|[`stem`](#stem)|Returns the `stem` component of `myname`.| +|[`string`](#string)|Converts the sequence stored in `myname`.| +|[`swap`](#swap)|Executes `swap(myname, right.myname)`.| +|[`u16string`](#u16string)|Converts the sequence stored in `myname` to UTF-16 and returns it stored in an object of type `u16string`.| +|[`u32string`](#u32string)|Deleted in the historical MSVC implementation.| +|[`u8string`](#u8string)|Converts the sequence stored in `myname` to UTF-8 and returns it stored in an object of type `u8string`.| +|[`value_type`](#value_type)|The type describes the path elements favored by the host operating system.| +|[`wstring`](#wstring)|Converts the sequence stored in `myname` to the encoding favored by the host system for a **`wchar_t`** sequence and returns it stored in an object of type `wstring`.| + +### Operators + +|Operator|Description| +|-|-| +|[`operator=`](#op_as)|Replaces the elements of the path with a copy of another path.| +|[`operator+=`](#op_add)|Various `concat` expressions.| +|[`operator/=`](#op_divide)|Various `append` expressions.| +|[`operator string_type`](#op_string)|Returns `myname`.| + +## Requirements + +**Header:** `` + +**Namespace:** `std::experimental::filesystem` + +## `path::append` + +Appends the specified sequence to `myname`, converted and inserting a `preferred_separator` as needed. + +```cpp +template +path& append(const Source& source); + +template +path& append(InIt first, InIt last); +``` + +### Parameters + +*`source`*\ +Specified sequence. + +*`first`*\ +Start of specified sequence. + +*`last`*\ +End of specified sequence. + +## `path::assign` + +Replaces `myname` with the specified sequence, converted as needed. + +```cpp +template +path& assign(const Source& source); + +template +path& assign(InIt first, InIt last); +``` + +### Parameters + +*`source`*\ +Specified sequence. + +*`first`*\ +Start of specified sequence. + +*`last`*\ +End of specified sequence. + +## `path::begin` + +Returns a `path::iterator` designating the first path element in the pathname, if present. + +```cpp +iterator begin() const; +``` + +## `path::c_str` + +Returns a pointer to the first character in `myname`. + +```cpp +const value_type* c_str() const noexcept; +``` + +## `path::clear` + +Executes `myname.clear()`. + +```cpp +void clear() noexcept; +``` + +## `path::compare` + +The first function returns `myname.compare(pval.native())`. The second function returns `myname.compare(str)`. The third function returns `myname.compare(ptr)`. + +```cpp +int compare(const path& pval) const noexcept; +int compare(const string_type& str) const; +int compare(const value_type *ptr) const; +``` + +### Parameters + +*`pval`*\ +Path to compare. + +*`str`*\ +String to compare. + +*`ptr`*\ +Pointer to compare. + +## `path::concat` + +Appends the specified sequence to `myname`, converted (but not inserting a separator) as needed. + +```cpp +template +path& concat(const Source& source); + +template +path& concat(InIt first, InIt last); +``` + +### Parameters + +*`source`*\ +Specified sequence. + +*`first`*\ +Start of specified sequence. + +*`last`*\ +End of specified sequence. + +## `path::const_iterator` + +A synonym for `iterator`. + +```cpp +typedef iterator const_iterator; +``` + +## `path::empty` + +Returns `myname.empty()`. + +```cpp +bool empty() const noexcept; +``` + +## `path::end` + +Returns an end-of-sequence iterator of type `iterator`. + +```cpp +iterator end() const; +``` + +## `path::extension` + +Returns the suffix of `filename()`. + +```cpp +path extension() const; +``` + +### Remarks + +Returns the suffix of `filename() X` such that: + +If `X == path(".") || X == path("..")` or if `X` contains no dot, the suffix is empty. + +Otherwise, the suffix begins with (and includes) the rightmost dot. + +## `path::filename` + +Returns the filename component of `myname`, specifically `empty() ? path() : *--end()`. The component may be empty. + +```cpp +path filename() const; +``` + +## `path::generic_string` + +Returns `this->string(al)` with (under Windows) any backslash converted to a forward slash. + +```cpp +template , + class Alloc = allocator> + basic_string + generic_string(const Alloc& al = Alloc()) const; + +string generic_string() const; +``` + +## `path::generic_u16string` + +Returns `u16string()` with (under Windows) any backslash converted to a forward slash. + +```cpp +u16string generic_u16string() const; +``` + +## `path::generic_u32string` + +This function is deleted in the historical MSVC implementation. + +```cpp +u32string generic_u32string() const = delete; +``` + +## `path::generic_u8string` + +Returns `u8string()` with (under Windows) any backslash converted to a forward slash. + +```cpp +string generic_u8string() const; +``` + +## `path::generic_wstring` + +Returns `wstring()` with (under Windows) any backslash converted to a forward slash. + +```cpp +wstring generic_wstring() const; +``` + +## `path::has_extension` + +Returns `!extension().empty()`. + +```cpp +bool has_extension() const; +``` + +## `path::has_filename` + +Returns `!filename().empty()`. + +```cpp +bool has_filename() const; +``` + +## `path::has_parent_path` + +Returns `!parent_path().empty()`. + +```cpp +bool has_parent_path() const; +``` + +## `path::has_relative_path` + +Returns `!relative_path().empty()`. + +```cpp +bool has_relative_path() const; +``` + +## `path::has_root_directory` + +Returns `!root_directory().empty()`. + +```cpp +bool has_root_directory() const; +``` + +## `path::has_root_name` + +Returns `!root_name().empty()`. + +```cpp +bool has_root_name() const; +``` + +## `path::has_root_path` + +Returns `!root_path().empty()`. + +```cpp +bool has_root_path() const; +``` + +## `path::has_stem` + +Returns `!stem().empty()`. + +```cpp +bool has_stem() const; +``` + +## `path::is_absolute` + +For Windows, the function returns `has_root_name() && has_root_directory()`. For POSIX, the function returns `has_root_directory()`. + +```cpp +bool is_absolute() const; +``` + +## `path::is_relative` + +Returns `!is_absolute()`. + +```cpp +bool is_relative() const; +``` + +## `path::iterator` + +A bidirectional constant iterator that designates the path components of `myname`. + +```cpp +class iterator + { + // bidirectional iterator for path + typedef bidirectional_iterator_tag iterator_category; + typedef path_type value_type; + typedef ptrdiff_t difference_type; + typedef const value_type *pointer; + typedef const value_type& reference; + // ... + }; +``` + +### Remarks + +The class describes a bidirectional constant iterator that designates the `path` components of `myname` in the sequence: + +1. the root name, if present + +1. the root directory, if present + +1. the remaining directory elements of the parent `path`, if present, ending with the filename, if present + +For `pval` an object of type `path`: + +1. `path::iterator X = pval.begin()` designates the first `path` element in the pathname, if present. + +1. `X == pval.end()` is `true` when `X` points just past the end of the sequence of components. + +1. `*X` returns a string that matches the current component + +1. `++X` designates the next component in the sequence, if present. + +1. `--X` designates the preceding component in the sequence, if present. + +1. Altering `myname` invalidates all iterators designating elements in `myname`. + +## `path::make_preferred` + +Converts each separator to a `preferred_separator` as needed. + +```cpp +path& make_preferred(); +``` + +## `path::native` + +Get the native string representation of the path. + +```cpp +const string_type& native() const noexcept; +``` + +### Remarks + +The path is available in a portable generic format (see [`generic_string()`](#generic_string)) or the native format of the path. This function returns the native string. On a POSIX system, the generic format and the native format are the same. + +In the following example running on Windows, the generic path string is `c:/t/temp.txt` and the native string is `c:\t\temp.txt`. + +```cpp +// Compile with /std:c++14 and _SILENCE_EXPERIMENTAL_FILESYSTEM_DEPRECATION_WARNING defined. +#include + +int main() +{ + std::experimental::filesystem::path p(LR"(c:\t\temp.txt)"); + auto native = p.native(); // Windows: L"c:\\t\\temp.txt" + auto generic = p.generic_string(); // Windows: "c:/t/temp.txt" +} +``` + +## `path::operator=` + +Replaces the elements of the path with a copy of another path. + +```cpp +path& operator=(const path& right); +path& operator=(path&& right) noexcept; + +template +path& operator=(const Source& source); +``` + +### Parameters + +*`right`*\ +The [`path`](../standard-library/experimental-filesystem-path-class.md) being copied into the `path`. + +*`source`*\ +The source `path`. + +### Remarks + +The first member operator copies `right.myname` to `myname`. The second member operator moves `right.myname` to `myname`. The third member operator behaves the same as `*this = path(source)`. + +## `path::operator+=` + +Various `concat` expressions. + +```cpp +path& operator+=(const path& right); +path& operator+=(const string_type& str); +path& operator+=(const value_type *ptr); +path& operator+=(value_type elem); + +template +path& operator+=(const Source& source); + +template +path& operator+=(Elem elem); +``` + +### Parameters + +*`right`*\ +The added path. + +*`str`*\ +The added string. + +*`ptr`*\ +The added pointer. + +*`elem`*\ +The added `value_type` or `Elem`. + +*`source`*\ +The added source. + +### Remarks + +The member functions behave the same as the following corresponding expressions: + +1. `concat(right);` + +1. `concat(path(str));` + +1. `concat(ptr);` + +1. `concat(string_type(1, elem));` + +1. `concat(source);` + +1. `concat(path(basic_string(1, elem)));` + +## `path::operator/=` + +Various `append` expressions. + +```cpp +path& operator/=(const path& right); + +template +path& operator/=(const Source& source); +``` + +### Parameters + +*`right`*\ +The added path. + +*`source`*\ +The added source. + +### Remarks + +The member functions behave the same as the following corresponding expressions: + +1. `append(right);` + +1. `append(source);` + +## `path::operator string_type` + +Returns `myname`. + +```cpp +operator string_type() const; +``` + +## `path::parent_path` + +Returns the parent path component of `myname`. + +```cpp +path parent_path() const; +``` + +### Remarks + +Returns the parent path component of `myname`, specifically the prefix of `myname` after removing `filename().native()` and any immediately preceding directory separators. (Equally, if `begin() != end()`, it's the combining of all elements in the range `[begin(), --end())` by successively applying `operator/=`.) The component may be empty. + +## `path::path` + +Constructs a `path` in various ways. + +```cpp +path(); + +path(const path& right); +path(path&& right) noexcept; + +template +path(const Source& source); + +template +path(const Source& source, const locale& loc); + +template +path(InIt first, InIt last); + +template +path(InIt first, InIt last, const locale& loc); +``` + +### Parameters + +*`right`*\ +The path of which the constructed path is to be a copy. + +*`source`*\ +The source of which the constructed path is to be a copy. + +*`loc`*\ +The specified locale. + +*`first`*\ +The position of the first element to be copied. + +*`last`*\ +The position of the last element to be copied. + +### Remarks + +The constructors all construct `myname` in various ways: + +For `path()` it's `myname()`. + +For `path(const path& right`) it's `myname(right.myname)`. + +For `path(path&& right)` it's `myname(right.myname)`. + +For `template path(const Source& source)` it's `myname(source)`. + +For `template path(const Source& source, const locale& loc)` it's `myname(source)`, obtaining any needed `codecvt` facets from `loc`. + +For `template path(InIt first, InIt last)` it's `myname(first, last)`. + +For `template path(InIt first, InIt last, const locale& loc)` it's `myname(first, last)`, obtaining any needed `codecvt` facets from `loc`. + +## `path::preferred_separator` + +The constant object gives the preferred character for separating path components, depending on the host operating system. + +```cpp +#if _WIN32_C_LIB +static constexpr value_type preferred_separator = L'\\'; +#else // assume POSIX +static constexpr value_type preferred_separator = '/'; +#endif // filesystem model now defined +``` + +### Remarks + +It's equally permissible in most contexts under Windows to use `L'/'` in its place. + +## `path::relative_path` + +Returns the relative path component of `myname`. + +```cpp +path relative_path() const; +``` + +### Remarks + +Returns the relative path component of `myname`, specifically the suffix of `myname` after removing `root_path().native()` and any immediately subsequent redundant directory separators. The component may be empty. + +## `path::remove_filename` + +Removes the filename. + +```cpp +path& remove_filename(); +``` + +## `path::replace_extension` + +Replaces the extension of `myname`. + +```cpp +path& replace_extension(const path& newext = path()); +``` + +### Parameters + +*`newext`*\ +The new extension. + +### Remarks + +First removes the suffix `extension().native()` from `myname`. Then if `!newext.empty() && newext[0] != dot` (where *dot* is `*path(".").c_str()`), then *dot* is appended to `myname`. Then *`newext`* is appended to `myname`. + +## `path::replace_filename` + +Replaces the filename. + +```cpp +path& replace_filename(const path& pval); +``` + +### Parameters + +*`pval`*\ +The path of the filename. + +### Remarks + +The member function executes: + +```cpp +remove_filename(); + +*this /= pval; +return (*this); +``` + +## `path::root_directory` + +Returns the root directory component of `myname`. + +```cpp +path root_directory() const; +``` + +### Remarks + +The component may be empty. + +## `path::root_name` + +Returns the root name component of `myname`. + +```cpp +path root_name() const; +``` + +### Remarks + +The component may be empty. + +## `path::root_path` + +Returns the root path component of `myname`. + +```cpp +path root_path() const; +``` + +### Remarks + +Returns the root path component of `myname`, specifically `root_name()` / `root_directory`. The component may be empty. + +## `path::stem` + +Returns the `stem` component of `myname`. + +```cpp +path stem() const; +``` + +### Remarks + +Returns the `stem` component of `myname`, specifically `filename().native()` with any trailing `extension().native()` removed. The component may be empty. + +## `path::string` + +Converts the sequence stored in `myname`. + +```cpp +template , class Alloc = allocator> +basic_string string(const Alloc& al = Alloc()) const; +string string() const; +``` + +### Remarks + +The first (template) member function converts the sequence stored in `myname` the same way as: + +1. `string()` for `string()` + +1. `wstring()` for `string()` + +1. `u16string()` for `string()` + +The second member function converts the sequence stored in `myname` to the encoding favored by the host system for a **`char`** sequence and returns it stored in an object of type `string`. + +## `path::string_type` + +The type is a synonym for `basic_string`. + +```cpp +typedef basic_string string_type; +``` + +## `path::swap` + +Executes `swap(myname, right.myname)`. + +```cpp +void swap(path& right) noexcept; +``` + +## `path::u16string` + +Converts the sequence stored in `myname` to UTF-16 and returns it stored in an object of type `u16string`. + +```cpp +u16string u16string() const; +``` + +## `path::u32string` + +This function is deleted in the historical MSVC implementation. + +```cpp +u32string u32string() const = delete; +``` + +## `path::u8string` + +Converts the sequence stored in `myname` to UTF-8 and returns it stored in an object of type `u8string`. + +```cpp +string u8string() const; +``` + +## `path::value_type` + +The type describes the `path` elements favored by the host operating system. + +```cpp +#if _WIN32_C_LIB +typedef wchar_t value_type; +#else // assume POSIX +typedef char value_type; +#endif // filesystem model now defined +``` + +## `path::wstring` + +Converts the sequence stored in `myname` to the encoding favored by the host system for a **`wchar_t`** sequence and returns it stored in an object of type `wstring`. + +```cpp +wstring wstring() const; +``` + +## See also + +[``](../standard-library/experimental-filesystem.md)\ +[`` operators](../standard-library/experimental-filesystem-operators.md) diff --git a/docs/standard-library/experimental-filesystem-recursive-directory-iterator-class.md b/docs/standard-library/experimental-filesystem-recursive-directory-iterator-class.md new file mode 100644 index 0000000000..bd9a3b17b1 --- /dev/null +++ b/docs/standard-library/experimental-filesystem-recursive-directory-iterator-class.md @@ -0,0 +1,258 @@ +--- +description: "Learn more about: recursive_directory_iterator class" +title: " recursive_directory_iterator class" +ms.date: 08/27/2026 +f1_keywords: ["filesystem/std::experimental::filesystem::recursive_directory_iterator"] +helpviewer_keywords: ["std::experimental::filesystem::recursive_directory_iterator"] +--- + +# `` `recursive_directory_iterator` class + +> [!IMPORTANT] +> This article describes the `recursive_directory_iterator` class from the prestandard `` implementation of the ISO C++ Filesystem Technical Specification (N4100). This API isn't the same as the C++17 [`recursive_directory_iterator`](recursive-directory-iterator-class.md) class in ``. It uses different signatures, including a `noexcept` `increment` and a single-form `pop` with no `error_code` overload. The experimental implementation was removed starting with the Microsoft Visual C++ (MSVC) 14.51 toolset. New code should use the C++17 [`recursive_directory_iterator`](recursive-directory-iterator-class.md) class instead. + +Describes an input iterator that sequences through the filenames in a directory, possibly descending into subdirectories recursively. For an iterator `X`, the expression `*X` returns an object of class `directory_entry` that wraps the filename and anything known about its status. + +## Syntax + +```cpp +class recursive_directory_iterator; +``` + +## Remarks + +The class stores: + +1. an object of type `stack>`, called `mystack` here for the purposes of exposition, which represents the nest of directories to sequence + +1. an object of type `directory_entry` called `myentry` here, which represents the current filename in the directory sequence + +1. an object of type **`bool`**, called `no_push` here, which records whether recursive descent into subdirectories is disabled + +1. an object of type `directory_options`, called `myoptions` here, which records the options established at construction + +A default-constructed object of type `recursive_directory_iterator` has an end-of-sequence iterator at `mystack.top().first` and represents the end-of-sequence iterator. For example, given the directory `abc` with entries `def` (a directory), `def/ghi`, and `jkl`, the code: + +```cpp +for (recursive_directory_iterator next(path("abc")), end; next != end; ++next) + visit(next->path()); +``` + +calls `visit` with the arguments `path("abc/def/ghi")` and `path("abc/jkl")`. You can qualify sequencing through a directory subtree in two ways: + +1. A directory symlink is scanned only if you construct a `recursive_directory_iterator` with a `directory_options` argument whose value is `directory_options::follow_directory_symlink`. + +1. If you call `disable_recursion_pending`, a subsequent directory encountered during an increment isn't recursively scanned. + +### Constructors + +|Constructor|Description| +|-|-| +|[recursive_directory_iterator](#recursive_directory_iterator)|Constructs a `recursive_directory_iterator`.| + +### Member functions + +|Member function|Description| +|-|-| +|[depth](#depth)|Returns `mystack.size() - 1`, so `pval` is at depth zero.| +|[disable_recursion_pending](#disable_recursion_pending)|Stores **`true`** in `no_push`.| +|[increment](#increment)|Advances to the next filename in sequence.| +|[options](#options)|Returns `myoptions`.| +|[pop](#pop)|Moves the iterator to the next entry at the next lower depth.| +|[recursion_pending](#recursion_pending)|Returns `!no_push`.| + +### Operators + +|Operator|Description| +|-|-| +|[operator!=](#op_neq)|Returns `!(*this == right)`.| +|[operator=](#op_as)|The defaulted member assignment operators behave as expected.| +|[operator==](#op_eq)|Returns **`true`** only if both **`*this`** and *right* are end-of-sequence iterators or both aren't end-of-sequence-iterators.| +|[operator*](#op_multiply)|Returns `myentry`.| +|[operator->](#op_cast)|Returns `&**this`.| +|[operator++](#op_increment)|Increments the `recursive_directory_iterator`.| + +## Requirements + +**Header:** `` + +**Namespace:** `std::experimental::filesystem` + +## recursive_directory_iterator::depth + +Returns `mystack.size() - 1`, so `pval` is at depth zero. + +```cpp +int depth() const; +``` + +## recursive_directory_iterator::disable_recursion_pending + +Stores **`true`** in `no_push`. + +```cpp +void disable_recursion_pending(); +``` + +## recursive_directory_iterator::increment + +Advances to the next filename in sequence. + +```cpp +recursive_directory_iterator& increment(error_code& ec) noexcept; +``` + +### Parameters + +`ec`\ +Specified error code. + +### Remarks + +The function attempts to advance to the next filename in the nested sequence. If successful, it stores that filename in `myentry`; otherwise it produces an end-of-sequence iterator. + +## recursive_directory_iterator::operator!= + +Returns `!(*this == right)`. + +```cpp +bool operator!=(const recursive_directory_iterator& right) const; +``` + +### Parameters + +*right*\ +The `recursive_directory_iterator` for comparison. + +## recursive_directory_iterator::operator= + +The defaulted member assignment operators behave as expected. + +```cpp +recursive_directory_iterator& operator=(const recursive_directory_iterator&) = default; +recursive_directory_iterator& operator=(recursive_directory_iterator&&) = default; +``` + +### Parameters + +*recursive_directory_iterator*\ +The `recursive_directory_iterator` being copied into the `recursive_directory_iterator`. + +## recursive_directory_iterator::operator== + +Returns **`true`** only if both **`*this`** and *right* are end-of-sequence iterators or both aren't end-of-sequence iterators. + +```cpp +bool operator==(const recursive_directory_iterator& right) const; +``` + +### Parameters + +*right*\ +The `recursive_directory_iterator` for comparison. + +## recursive_directory_iterator::operator* + +Returns `myentry`. + +```cpp +const directory_entry& operator*() const; +``` + +## recursive_directory_iterator::operator-> + +Returns `&**this`. + +```cpp +const directory_entry * operator->() const; +``` + +## recursive_directory_iterator::operator++ + +Increments the `recursive_directory_iterator`. + +```cpp +recursive_directory_iterator& operator++(); + +recursive_directory_iterator operator++(int); +``` + +### Parameters + +*int*\ +Dummy argument. It's a C++ convention used only to distinguish the postfix increment operator from the prefix increment operator. The C++ standard requires the postfix form to take a dummy int parameter. + +### Remarks + +The first member function calls `increment()`, then returns **`*this`**. The second member function makes a copy of the object, calls `increment()`, then returns the copy. + +## recursive_directory_iterator::options + +Returns `myoptions`. + +```cpp +directory_options options() const; +``` + +## recursive_directory_iterator::pop + +Moves the iterator to the next entry at the next lower depth. + +```cpp +void pop(); +``` + +### Remarks + +If `depth() == 0`, the object becomes an end-of-sequence iterator. Otherwise, the member function terminates scanning of the current (deepest) directory and resumes at the next lower depth. + +## recursive_directory_iterator::recursion_pending + +Returns `!no_push`. + +```cpp +bool recursion_pending() const; +``` + +## recursive_directory_iterator::recursive_directory_iterator + +Constructs a `recursive_directory_iterator`. + +```cpp +recursive_directory_iterator() noexcept; +explicit recursive_directory_iterator(const path& pval, + directory_options opts = directory_options::none); + +recursive_directory_iterator(const path& pval, + directory_options opts, + error_code& ec) noexcept; +recursive_directory_iterator(const path& pval, + error_code& ec) noexcept; +recursive_directory_iterator(const recursive_directory_iterator&) = default; +recursive_directory_iterator(recursive_directory_iterator&&) = default; +``` + +### Parameters + +`pval`\ +The specified path. + +*error_code*\ +The specified error code. + +*opts*\ +The specified directory options. + +*recursive_directory_iterator*\ +The `recursive_directory_iterator` of which the constructed `recursive_directory_iterator` is to be a copy. + +### Remarks + +The first constructor creates an end-of-sequence iterator. The second constructor stores **`false`** in `no_push` and *opts* in `myoptions`, then tries to open and read *pval* as a directory. If it succeeds, it initializes `mystack` and `myentry` to point to the first non-directory filename in the nested sequence. If it fails, it creates an end-of-sequence iterator. + +The third and fourth constructors behave the same as the second, except that they report errors in *ec* instead of throwing an exception. The fourth constructor stores `directory_options::none` in `myoptions`. The default constructor behaves as expected. + +## See also + +[``](../standard-library/experimental-filesystem.md)\ +[`directory_entry` class](../standard-library/experimental-filesystem-directory-entry-class.md) diff --git a/docs/standard-library/experimental-filesystem-space-info-structure.md b/docs/standard-library/experimental-filesystem-space-info-structure.md new file mode 100644 index 0000000000..ab675f69c7 --- /dev/null +++ b/docs/standard-library/experimental-filesystem-space-info-structure.md @@ -0,0 +1,44 @@ +--- +description: "Learn more about: space_info Structure" +title: " space_info Structure" +ms.date: 08/27/2026 +f1_keywords: ["filesystem/std::experimental::filesystem::space_info"] +--- +# `` space_info Structure + +> [!IMPORTANT] +> This article describes the prestandard `` implementation of `space_info`. It documents the historical File System Technical Specification ([ISO/IEC JTC 1/SC 22/WG 21 N4100](https://wg21.link/n4100)), not the C++17 `std::filesystem::space_info` structure. The experimental implementation was removed starting with MSVC version 14.51. For current code, use the standard [space_info Structure](../standard-library/space-info-structure.md). + +Holds information about a volume. + +## Syntax + +```cpp +struct space_info +{ + uintmax_t capacity; + uintmax_t free; + uintmax_t available; +}; +``` + +## Members + +### Public Data Members + +|Name|Description| +|----------|-----------------| +|`uintmax_t capacity`|Represents the total number of bytes that the volume can represent.| +|`uintmax_t free`|Represents the number of bytes that are not used to represent data on the volume.| +|`uintmax_t available`|Represents the number of bytes that are available to represent data on the volume.| + +## Requirements + +**Header:** \ + +**Namespace:** std::experimental::filesystem + +## See also + +[``](../standard-library/experimental-filesystem.md)\ +[`space`](../standard-library/experimental-filesystem-functions.md#space) diff --git a/docs/standard-library/experimental-filesystem.md b/docs/standard-library/experimental-filesystem.md new file mode 100644 index 0000000000..7e41182c98 --- /dev/null +++ b/docs/standard-library/experimental-filesystem.md @@ -0,0 +1,67 @@ +--- +title: "" +description: "Describes the historical, prestandard MSVC experimental/filesystem header, which was removed starting in MSVC version 14.51." +ms.date: 08/27/2026 +f1_keywords: ["", "filesystem/std::experimental::filesystem", "std::experimental::filesystem"] +no-loc: [experimental, filesystem, char, wchar_t, char16_t, char32_t] +--- +# `` + +> [!IMPORTANT] +> This article documents the historical, prestandard MSVC implementation of the File System Technical Specification that was provided in the `` header. It's **not** the C++17 `std::filesystem` library. This experimental implementation was **removed starting in MSVC version 14.51**. For current file system support, use the C++17 [``](../standard-library/filesystem.md) header and the `std::filesystem` namespace. + +Use this documentation only when maintaining older code that includes `` or uses the `std::experimental::filesystem` namespace. The reference links on this page stay within that historical API unless they're explicitly labeled as current C++17 documentation. + +Before C++17 standardized file system support, MSVC shipped a prestandard implementation of the File System Technical Specification in the `` header, under the `std::experimental::filesystem` namespace. This article is retained for historical reference. New code should use the C++17 [``](../standard-library/filesystem.md) header instead. + +## Syntax + +```cpp +#include // Removed starting in MSVC version 14.51 +using namespace std::experimental::filesystem::v1; +``` + +## Visual Studio version history + +- When Visual Studio 2017 was released, the C++17 `` header wasn't yet standardized. C++ in Visual Studio 2017 implemented the prestandard File System Technical Specification in the `` header. +- Visual Studio 2017 version 15.7 and later added support for the new C++17 `` standard. This C++17 implementation is a completely new implementation, incompatible with the previous `std::experimental` version. +- In Visual Studio 2019 version 16.3 and later, including `` provides only the new `std::filesystem`, and including `` provides only the old experimental implementation. +- The experimental implementation was removed starting in MSVC Build Tools version 14.51, which became the default toolset in Visual Studio 2026 version 18.6. + +## Classes + +|Name|Description| +|-|-| +|[`directory_entry` class](../standard-library/experimental-filesystem-directory-entry-class.md)|Describes an object that is returned by a `directory_iterator` or a `recursive_directory_iterator` and contains a `path`.| +|[`directory_iterator` class](../standard-library/experimental-filesystem-directory-iterator-class.md)|Describes an input iterator that sequences through the file names in a file-system directory.| +|[`filesystem_error` class](../standard-library/experimental-filesystem-error-class.md)|A base class for exceptions that are thrown to report a low-level system error.| +|[`path` class](../standard-library/experimental-filesystem-path-class.md)|Defines a class that stores an object of template type `String` that is suitable for use as a file name.| +|[`recursive_directory_iterator` class](../standard-library/experimental-filesystem-recursive-directory-iterator-class.md)|Describes an input iterator that sequences through the file names in a file-system directory. The iterator can also descend into subdirectories.| +|[`file_status` class](../standard-library/experimental-filesystem-file-status-class.md)|Wraps a `file_type`.| + +## Structs + +|Name|Description| +|-|-| +|[`space_info` structure](../standard-library/experimental-filesystem-space-info-structure.md)|Holds information about a volume.| + +## Functions + +[`` functions](../standard-library/experimental-filesystem-functions.md) + +## Operators + +[`` operators](../standard-library/experimental-filesystem-operators.md) + +## Enumerations + +|Name|Description| +|-|-| +|[`copy_options`](../standard-library/experimental-filesystem-enumerations.md#copy_options)|An enumeration that is used with `copy_file` and determines behavior if a destination file already exists.| +|[`directory_options`](../standard-library/experimental-filesystem-enumerations.md#directory_options)|An enumeration that specifies options for directory iterators.| +|[`file_type`](../standard-library/experimental-filesystem-enumerations.md#file_type)|An enumeration for file types.| +|[`perms`](../standard-library/experimental-filesystem-enumerations.md#perms)|A bitmask type used to convey permissions and options to permissions.| + +## See also + +[Current `` documentation](../standard-library/filesystem.md) diff --git a/docs/standard-library/file-status-class.md b/docs/standard-library/file-status-class.md index 02d399d3cd..2a547064db 100644 --- a/docs/standard-library/file-status-class.md +++ b/docs/standard-library/file-status-class.md @@ -1,9 +1,9 @@ --- title: "file_status Class" description: "Learn more about: file_status Class" -ms.date: 09/10/2018 -f1_keywords: ["filesystem/std::experimental::filesystem::file_status", "filesystem/std::experimental::filesystem::file_status::operator=", "filesystem/std::experimental::filesystem::file_status::type", "filesystem/std::experimental::filesystem::file_status::permissions"] -helpviewer_keywords: ["std::experimental::filesystem::file_status", "std::experimental::filesystem::file_status::operator=", "std::experimental::filesystem::file_status::type", "std::experimental::filesystem::file_status::permissions"] +ms.date: 08/27/2026 +f1_keywords: ["filesystem/std::filesystem::file_status", "filesystem/std::filesystem::file_status::operator=", "filesystem/std::filesystem::file_status::type", "filesystem/std::filesystem::file_status::permissions"] +helpviewer_keywords: ["std::filesystem::file_status", "std::filesystem::file_status::operator=", "std::filesystem::file_status::type", "std::filesystem::file_status::permissions"] --- # file_status Class @@ -38,7 +38,7 @@ class file_status; **Header:** \ -**Namespace:** std::experimental::filesystem, std::experimental::filesystem +**Namespace:** std::filesystem ## file_status::file_status @@ -86,8 +86,8 @@ The [file_status](../standard-library/file-status-class.md) being copied into th Gets or sets the `file_type`. ```cpp -file_type type() const noexcept -void type(file_type ftype) noexcept +file_type type() const noexcept; +void type(file_type ftype) noexcept; ``` ### Parameters @@ -102,8 +102,8 @@ Gets or sets the file permissions. Use the setter to make a file `readonly` or remove the `readonly` attribute. ```cpp -perms permissions() const noexcept -void permissions(perms mask) noexcept +perms permissions() const noexcept; +void permissions(perms mask) noexcept; ``` ### Parameters diff --git a/docs/standard-library/file-system-navigation.md b/docs/standard-library/file-system-navigation.md index 30b075f62b..3cdab3a9b4 100644 --- a/docs/standard-library/file-system-navigation.md +++ b/docs/standard-library/file-system-navigation.md @@ -1,12 +1,14 @@ --- title: "File System Navigation" description: "How to use the C++ Standard library filesystem APIs to navigate the file system." -ms.date: "04/13/2020" -ms.assetid: f7cc5f5e-a541-4e00-87c7-a3769ef6096d +ms.date: 08/27/2026 --- # File System Navigation -The `` header implements the C++ File System Technical Specification ISO/IEC TS 18822:2015 (Final draft: [ISO/IEC JTC 1/SC 22/WG 21 N4100](https://wg21.link/n4100)) and has types and functions that enable you to write platform-independent code for navigating the file system. Because it's cross-platform, it contains APIs that aren't relevant for Windows systems. For example, `is_fifo(const path&)` always returns **`false`** on Windows. +The C++17 `` header provides types and functions that enable you to write platform-independent code for navigating the file system. Because it's cross-platform, it contains APIs that aren't relevant for Windows systems. For example, `is_fifo(const path&)` always returns **`false`** on Windows. + +> [!NOTE] +> This article covers the current C++17 `std::filesystem` library. For the historical prestandard MSVC implementation that was removed starting in MSVC version 14.51, see [``](../standard-library/experimental-filesystem.md). ## Overview diff --git a/docs/standard-library/filesystem-enumerations.md b/docs/standard-library/filesystem-enumerations.md index fb87d4f293..3252ccfd7d 100644 --- a/docs/standard-library/filesystem-enumerations.md +++ b/docs/standard-library/filesystem-enumerations.md @@ -1,19 +1,22 @@ --- description: "Learn more about: enumerations" title: " enumerations" -ms.date: "11/04/2016" -f1_keywords: ["filesystem/std::filesystem::copy_options", "filesystem/std::experimental::filesystem::copy_options", "filesystem/std::filesystem::directory_options", "filesystem/std::experimental::filesystem::directory_options", "filesystem/std::filesystem::file_type", "filesystem/std::experimental::filesystem::file_type", "filesystem/std::filesystem::perms", "filesystem/std::experimental::filesystem::perms"] -ms.assetid: 0096c046-d101-464c-8259-b878a48280b0 +ms.date: 08/27/2026 +f1_keywords: ["filesystem/std::filesystem::copy_options", "filesystem/std::filesystem::directory_options", "filesystem/std::filesystem::file_type", "filesystem/std::filesystem::perm_options", "filesystem/std::filesystem::perms"] +helpviewer_keywords: ["std::filesystem::copy_options", "std::filesystem::directory_options", "std::filesystem::file_type", "std::filesystem::perm_options", "std::filesystem::perms"] --- # `` enumerations -This topic documents the enums in the filesystem header. +This article documents the enumerations in the C++17 `std::filesystem` implementation of the [``](../standard-library/filesystem.md) header. + +> [!NOTE] +> This page documents the C++17 `std::filesystem` enumerations. For the historical prestandard enumerations that MSVC provided in ``, see [`` enumerations](../standard-library/experimental-filesystem-enumerations.md). ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std::experimental::filesystem +**Namespace:** `std::filesystem` ## copy_options @@ -53,14 +56,15 @@ enum class copy_options { ## directory_options -Specifies whether to follow symbolic links to directories or to ignore them. +A bitmask enumeration that controls how directory iteration handles symbolic links to directories and permission-denied errors. ### Syntax ```cpp enum class directory_options { none = 0, - follow_directory_symlink + follow_directory_symlink = 1, + skip_permission_denied = 2 }; ``` @@ -68,19 +72,20 @@ enum class directory_options { |Name|Description| |----------|-----------------| -|`none`|Default behavior: ignore symbolic links to directories. Permission denied is an error.| -|`follow_directory_symlink`|Treat symbolic links to directories as actual directories.| +|`none`|Default behavior: don't follow symbolic links to directories, and treat permission denied as an error.| +|`follow_directory_symlink`|Follow symbolic links to directories rather than skipping them.| +|`skip_permission_denied`|Silently skip directories that would otherwise result in a permission-denied error.| ## file_type -An enumeration for file types. The supported values are regular, directory, not_found, and unknown. +An enumeration for file types. ### Syntax ```cpp enum class file_type { - not_found = -1, - none, + none = 0, + not_found, regular, directory, symlink, @@ -92,32 +97,50 @@ enum class file_type { }; ``` +The C++ standard doesn't fix the underlying integer values of these enumerators, so don't depend on specific numeric values. + ### Values -|Name|Value|Description| -|----------|-----------|-----------------| -|`not_found`|-1|Represents a file that does not exist.| -|`none`|0|Represents a file that has no type attribute. (Not supported.)| -|`regular`|1|Represents a conventional disk file.| -|`directory`|2|Represents a directory.| -|`symlink`|3|Represents a symbolic link. (Not supported.)| -|`block`|4|Represents a block-special file on UNIX-based systems. (Not supported.)| -|`character`|5|Represents a character-special file on UNIX-based systems. (Not supported.)| -|`fifo`|6|Represents a FIFO file on UNIX-based systems. (Not supported.)| -|`socket`|7|Represents a socket on UNIX based systems. (Not supported.)| -|`unknown`|8|Represents a file whose status cannot be determined.| +|Name|Description| +|----------|-----------------| +|`none`|The file type hasn't been evaluated yet, or an error occurred when evaluating it.| +|`not_found`|The file wasn't found.| +|`regular`|A regular file.| +|`directory`|A directory.| +|`symlink`|A symbolic link.| +|`block`|A block-special file. (Not used on Windows.)| +|`character`|A character-special file. (Not used on Windows.)| +|`fifo`|A FIFO or pipe file. (Not used on Windows.)| +|`socket`|A socket. (Not used on Windows.)| +|`unknown`|The file exists but its type can't be determined.| ## perm_options -Includes values `replace`, `add`, `remove`, and `nofollow`. +A bitmask enumeration that controls how the [`permissions`](../standard-library/filesystem-functions.md#permissions) function applies permission bits. + +### Syntax ```cpp -enum class perm_options; +enum class perm_options { + replace = 1, + add = 2, + remove = 4, + nofollow = 8 +}; ``` +### Values + +|Name|Description| +|----------|-----------------| +|`replace`|Replace the file's permission bits with the specified permissions.| +|`add`|Add the specified permission bits to the file's current permissions.| +|`remove`|Remove the specified permission bits from the file's current permissions.| +|`nofollow`|Change the permissions of a symbolic link itself rather than the file it resolves to.| + ## perms -Flags for file permissions. The supported values are essentially "readonly" and all. For a readonly file, none of the *_write bits are set. Otherwise the `all` bit (0x0777) is set. +A bitmask enumeration of file permission bits. On Windows, the supported values are essentially "read-only" and `all`. For a read-only file, none of the `*_write` bits are set. Otherwise, the `all` bit (0777) is set. ### Syntax @@ -141,10 +164,7 @@ enum class perms {// names for permissions set_gid = 02000, // S_ISGID sticky_bit = 01000, // S_ISVTX mask = 07777, - unknown = 0xFFFF, - add_perms = 0x10000, - remove_perms = 0x20000, - resolve_symlinks = 0x40000 + unknown = 0xFFFF }; ``` diff --git a/docs/standard-library/filesystem-error-class.md b/docs/standard-library/filesystem-error-class.md index 5e2dee1e4a..182aea657b 100644 --- a/docs/standard-library/filesystem-error-class.md +++ b/docs/standard-library/filesystem-error-class.md @@ -1,18 +1,17 @@ --- description: "Learn more about: filesystem_error Class" title: "filesystem_error Class" -ms.date: "09/10/2018" -f1_keywords: ["filesystem/std::experimental::filesystem::filesystem_error"] -ms.assetid: c53aac27-c1fa-43e4-8967-48ea8ba1f172 +ms.date: 08/27/2026 +f1_keywords: ["filesystem/std::filesystem::filesystem_error"] --- # filesystem_error Class -A base class for all exceptions that are thrown to report a low-level system overflow. +A base class for all exceptions that report a low-level system error. ## Syntax ```cpp -class filesystem_error : public system_error; +class filesystem_error : public system_error; ``` ## Remarks @@ -39,7 +38,7 @@ The class serves as the base class for all exceptions thrown to report an error **Header:** \ -**Namespace:** std::experimental::filesystem +**Namespace:** std::filesystem ## filesystem_error diff --git a/docs/standard-library/filesystem-functions.md b/docs/standard-library/filesystem-functions.md index 2c642f3180..56fec50c3c 100644 --- a/docs/standard-library/filesystem-functions.md +++ b/docs/standard-library/filesystem-functions.md @@ -1,57 +1,49 @@ --- title: " functions" description: "Learn more about: functions" -ms.date: "03/27/2019" -f1_keywords: ["FILESYSTEM/std::experimental::filesystem::absolute", "FILESYSTEM/std::experimental::filesystem::canonical", "FILESYSTEM/std::experimental::filesystem::copy", "FILESYSTEM/std::experimental::filesystem::copy_file", "FILESYSTEM/std::experimental::filesystem::copy_symlink", "FILESYSTEM/std::experimental::filesystem::create_directories", "FILESYSTEM/std::experimental::filesystem::create_directory", "FILESYSTEM/std::experimental::filesystem::create_directory_symlink", "FILESYSTEM/std::experimental::filesystem::create_hard_link", "FILESYSTEM/std::experimental::filesystem::create_symlink", "FILESYSTEM/std::experimental::filesystem::current_path", "FILESYSTEM/std::experimental::filesystem::equivalent", "FILESYSTEM/std::experimental::filesystem::exists", "FILESYSTEM/std::experimental::filesystem::file_size", "FILESYSTEM/std::experimental::filesystem::hard_link_count", "FILESYSTEM/std::experimental::filesystem::hash_value", "FILESYSTEM/std::experimental::filesystem::is_block_file", "FILESYSTEM/std::experimental::filesystem::is_character_file", "FILESYSTEM/std::experimental::filesystem::is_directory", "FILESYSTEM/std::experimental::filesystem::is_empty", "FILESYSTEM/std::experimental::filesystem::is_fifo", "FILESYSTEM/std::experimental::filesystem::is_other", "FILESYSTEM/std::experimental::filesystem::is_regular_file", "FILESYSTEM/std::experimental::filesystem::is_socket", "FILESYSTEM/std::experimental::filesystem::is_symlink", "FILESYSTEM/std::experimental::filesystem::last_write_time", "FILESYSTEM/std::experimental::filesystem::permissions", "FILESYSTEM/std::experimental::filesystem::read_symlink", "FILESYSTEM/std::experimental::filesystem::remove", "FILESYSTEM/std::experimental::filesystem::remove_all", "FILESYSTEM/std::experimental::filesystem::rename", "FILESYSTEM/std::experimental::filesystem::resize_file", "FILESYSTEM/std::experimental::filesystem::space", "FILESYSTEM/std::experimental::filesystem::status", "FILESYSTEM/std::experimental::filesystem::status_known", "FILESYSTEM/std::experimental::filesystem::swap", "FILESYSTEM/std::experimental::filesystem::symlink_status", "FILESYSTEM/std::experimental::filesystem::system_complete", "FILESYSTEM/std::experimental::filesystem::temp_directory_path", "FILESYSTEM/std::experimental::filesystem::u8path"] -helpviewer_keywords: ["std::experimental::filesystem::absolute", "std::experimental::filesystem::canonical", "std::experimental::filesystem::copy", "std::experimental::filesystem::copy_file", "std::experimental::filesystem::copy_symlink", "std::experimental::filesystem::create_directories", "std::experimental::filesystem::create_directory", "std::experimental::filesystem::create_directory_symlink", "std::experimental::filesystem::create_hard_link", "std::experimental::filesystem::create_symlink", "std::experimental::filesystem::current_path", "std::experimental::filesystem::equivalent", "std::experimental::filesystem::exists", "std::experimental::filesystem::file_size", "std::experimental::filesystem::hard_link_count", "std::experimental::filesystem::hash_value", "std::experimental::filesystem::is_block_file", "std::experimental::filesystem::is_character_file", "std::experimental::filesystem::is_directory", "std::experimental::filesystem::is_empty", "std::experimental::filesystem::is_fifo", "std::experimental::filesystem::is_other", "std::experimental::filesystem::is_regular_file", "std::experimental::filesystem::is_socket", "std::experimental::filesystem::is_symlink", "std::experimental::filesystem::last_write_time", "std::experimental::filesystem::permissions", "std::experimental::filesystem::read_symlink", "std::experimental::filesystem::remove", "std::experimental::filesystem::remove_all", "std::experimental::filesystem::rename", "std::experimental::filesystem::resize_file", "std::experimental::filesystem::space", "std::experimental::filesystem::status", "std::experimental::filesystem::status_known", "std::experimental::filesystem::swap", "std::experimental::filesystem::symlink_status", "std::experimental::filesystem::system_complete", "std::experimental::filesystem::temp_directory_path", "std::experimental::filesystem::u8path"] +ms.date: 08/27/2026 +f1_keywords: ["filesystem/std::filesystem::absolute", "filesystem/std::filesystem::canonical", "filesystem/std::filesystem::copy", "filesystem/std::filesystem::copy_file", "filesystem/std::filesystem::copy_symlink", "filesystem/std::filesystem::create_directories", "filesystem/std::filesystem::create_directory", "filesystem/std::filesystem::create_directory_symlink", "filesystem/std::filesystem::create_hard_link", "filesystem/std::filesystem::create_symlink", "filesystem/std::filesystem::current_path", "filesystem/std::filesystem::equivalent", "filesystem/std::filesystem::exists", "filesystem/std::filesystem::file_size", "filesystem/std::filesystem::hard_link_count", "filesystem/std::filesystem::hash_value", "filesystem/std::filesystem::is_block_file", "filesystem/std::filesystem::is_character_file", "filesystem/std::filesystem::is_directory", "filesystem/std::filesystem::is_empty", "filesystem/std::filesystem::is_fifo", "filesystem/std::filesystem::is_other", "filesystem/std::filesystem::is_regular_file", "filesystem/std::filesystem::is_socket", "filesystem/std::filesystem::is_symlink", "filesystem/std::filesystem::last_write_time", "filesystem/std::filesystem::permissions", "filesystem/std::filesystem::proximate", "filesystem/std::filesystem::read_symlink", "filesystem/std::filesystem::relative", "filesystem/std::filesystem::remove", "filesystem/std::filesystem::remove_all", "filesystem/std::filesystem::rename", "filesystem/std::filesystem::resize_file", "filesystem/std::filesystem::space", "filesystem/std::filesystem::status", "filesystem/std::filesystem::status_known", "filesystem/std::filesystem::swap", "filesystem/std::filesystem::symlink_status", "filesystem/std::filesystem::temp_directory_path", "filesystem/std::filesystem::u8path", "filesystem/std::filesystem::weakly_canonical"] +helpviewer_keywords: ["std::filesystem::absolute", "std::filesystem::canonical", "std::filesystem::copy", "std::filesystem::copy_file", "std::filesystem::copy_symlink", "std::filesystem::create_directories", "std::filesystem::create_directory", "std::filesystem::create_directory_symlink", "std::filesystem::create_hard_link", "std::filesystem::create_symlink", "std::filesystem::current_path", "std::filesystem::equivalent", "std::filesystem::exists", "std::filesystem::file_size", "std::filesystem::hard_link_count", "std::filesystem::hash_value", "std::filesystem::is_block_file", "std::filesystem::is_character_file", "std::filesystem::is_directory", "std::filesystem::is_empty", "std::filesystem::is_fifo", "std::filesystem::is_other", "std::filesystem::is_regular_file", "std::filesystem::is_socket", "std::filesystem::is_symlink", "std::filesystem::last_write_time", "std::filesystem::permissions", "std::filesystem::proximate", "std::filesystem::read_symlink", "std::filesystem::relative", "std::filesystem::remove", "std::filesystem::remove_all", "std::filesystem::rename", "std::filesystem::resize_file", "std::filesystem::space", "std::filesystem::status", "std::filesystem::status_known", "std::filesystem::swap", "std::filesystem::symlink_status", "std::filesystem::temp_directory_path", "std::filesystem::u8path", "std::filesystem::weakly_canonical"] --- # `` functions -These free functions in the [``](../standard-library/filesystem.md) header do modifying and query operations on paths, files, symlinks, directories, and volumes. For more information and code examples, see [File System Navigation (C++)](../standard-library/file-system-navigation.md). +These free functions in the C++17 [``](../standard-library/filesystem.md) header perform modifying and query operations on paths, files, symlinks, directories, and volumes. For more information and code examples, see [File System Navigation (C++)](../standard-library/file-system-navigation.md). -## `absolute` +> [!NOTE] +> This article documents the C++17 `std::filesystem` functions. For the historical prestandard functions that MSVC provided in ``, see [`` functions](../standard-library/experimental-filesystem-functions.md). -```cpp -path absolute(const path& pval, const path& base = current_path()); -``` +## Requirements -The function returns the absolute pathname corresponding to *`pval`* relative to the pathname `base`: +**Header:** `` -1. If `pval.has_root_name() && pval.has_root_directory()` the function returns *`pval`*. +**Namespace:** `std::filesystem` -1. If `pval.has_root_name() && !pval.has_root_directory()` the function returns `pval.root_name()` / `absolute(base).root_directory()` / `absolute(base).relative_path()` / `pval.relative_path()`. +## `absolute` -1. If `!pval.has_root_name() && pval.has_root_directory()` the function returns `absolute(base).root_name()` / *`pval`*. +```cpp +path absolute(const path& pval); +path absolute(const path& pval, error_code& ec); +``` -1. If `!pval.has_root_name() && !pval.has_root_directory()` the function returns `absolute(base)` / *`pval`*. +The functions compose an absolute path that refers to the same file system location as *`pval`*, according to operating-system semantics. The overload that takes *`ec`* returns `path()` if an error occurs. ## `begin` ```cpp -const directory_iterator& begin(const directory_iterator& iter) noexcept; -const recursive_directory_iterator& - begin(const recursive_directory_iterator& iter) noexcept; +directory_iterator begin(directory_iterator iter) noexcept; +recursive_directory_iterator begin(recursive_directory_iterator iter) noexcept; ``` -Both functions return *`iter`*. +Both functions return *`iter`*. Together with `end`, they enable range-based `for` loops over a `directory_iterator` or `recursive_directory_iterator`. ## `canonical` ```cpp -path canonical(const path& pval, const path& base = current_path()); +path canonical(const path& pval); path canonical(const path& pval, error_code& ec); -path canonical(const path& pval, const path& base, error_code& ec); ``` -The functions all form an absolute pathname `pabs = absolute(pval, base)` (or `pabs = absolute(pval)` for the overload with no base parameter), then reduce it to a canonical form in the following sequence of steps: - -1. Every path component `X` for which `is_symlink(X)` is **`true`** is replaced by `read_symlink(X)`. - -1. Every path component `.` (dot is the current directory established by previous path components) is removed. - -1. Every pair of path components `X`/`..` (dot-dot is the parent directory established by previous path components) is removed. - -The function then returns `pabs`. +The functions convert *`pval`*, which must exist, to an absolute path that refers to the same file system object and has no symbolic-link, dot, or dot-dot elements. The overload that takes *`ec`* returns `path()` if an error occurs. ## `copy` @@ -70,13 +62,7 @@ The functions all possibly copy or link one or more files at *from* to *to* unde - `directories_only`, `create_symlinks`, or `create_hard_links` -The functions first determine the file_status values `f` for *from* and `t` for *to*: - -- if `opts & (copy_options::create_symlinks | copy_options::skip_symlinks)`, by calling `symlink_status` - -- otherwise, by calling `status` - -- Otherwise report an error. +The functions first determine the `file_status` values `f` for *from* and `t` for *to*. They use `symlink_status` when *`opts`* contains `copy_options::create_symlinks`, `copy_options::skip_symlinks`, or `copy_options::copy_symlinks`, as required for the source or destination. Otherwise, they use `status`. If `!exists(f) || equivalent(f, t) || is_other(f) || is_other(t) || is_directory(f)&& is_regular_file(t)`, they then report an error (and do nothing else). @@ -84,7 +70,7 @@ Otherwise, if `is_symlink(f)` then: - If `options & copy_options::skip_symlinks`, then do nothing. -- Otherwise, if `!exists(t)&& options & copy_options::copy_symlinks`, then `copy_symlink(from, to, opts)`. +- Otherwise, if `!exists(t) && options & copy_options::copy_symlinks`, then `copy_symlink(from, to)`. - Otherwise, report an error. @@ -92,11 +78,11 @@ Otherwise, if `is_regular_file(f)`, then: - If `opts & copy_options::directories_only`, then do nothing. -- Otherwise, if `opts & copy_options::create_symlinks`, then `create_symlink(to, from)`. +- Otherwise, if `opts & copy_options::create_symlinks`, then `create_symlink(from, to)`. -- Otherwise, if `opts & copy_options::create_hard_links`, then `create_hard_link(to, from)`. +- Otherwise, if `opts & copy_options::create_hard_links`, then `create_hard_link(from, to)`. -- Otherwise, if `is_directory(f)`, then `copy_file(from, to` / `from.filename(), opts)`. +- Otherwise, if `is_directory(t)`, then `copy_file(from, to / from.filename(), opts)`. - Otherwise, `copy_file(from, to, opts)`. @@ -205,11 +191,11 @@ The functions with no parameter *`pval`* return the pathname for the current dir ## `end` ```cpp -directory_iterator& end(const directory_iterator& iter) noexcept; -recursive_directory_iterator& end(const recursive_directory_iterator& iter) noexcept; +directory_iterator end(const directory_iterator&) noexcept; +recursive_directory_iterator end(const recursive_directory_iterator&) noexcept; ``` -The first function returns `directory_iterator()` and the second function returns `recursive_directory_iterator()` +The first function returns `directory_iterator()` and the second function returns `recursive_directory_iterator()`. ## `equivalent` @@ -228,7 +214,7 @@ bool exists(const path& pval); bool exists(const path& pval, error_code& ec) noexcept; ``` -The first function returns `status_known && stat.type() != file_not_found`. The second and third functions return `exists(status(pval))`. +The first function returns `status_known(stat) && stat.type() != file_type::not_found`. The second and third functions return `exists(status(pval))`. ## `file_size` @@ -284,12 +270,11 @@ bool is_directory(const path& pval); bool is_directory(const path& pval, error_code& ec) noexcept; ``` -The first function returns `stat.type() == file_type::directory`. The remaining functions return `is_directory_file(status(pval))`. +The first function returns `stat.type() == file_type::directory`. The remaining functions return `is_directory(status(pval))`. ## `is_empty` ```cpp -bool is_empty(file_status stat) noexcept; bool is_empty(const path& pval); bool is_empty(const path& pval, error_code& ec) noexcept; ``` @@ -314,7 +299,7 @@ bool is_other(const path& pval); bool is_other(const path& pval, error_code& ec) noexcept; ``` -The first function returns `stat.type() == file_type::other`. The remaining functions return `is_other(status(pval))`. +The first function returns `exists(stat) && !is_regular_file(stat) && !is_directory(stat) && !is_symlink(stat)`. The remaining functions return `is_other(status(pval))`. ## `is_regular_file` @@ -360,13 +345,14 @@ The first two functions return the time of last data modification for *`pval`*, ## `permissions` ```cpp -void permissions(const path& pval, perms mask); +void permissions(const path& pval, perms mask, perm_options opts = perm_options::replace); void permissions(const path& pval, perms mask, error_code& ec) noexcept; +void permissions(const path& pval, perms mask, perm_options opts, error_code& ec); ``` -The functions set the permissions for the pathname chosen by *`pval`* to `mask & perms::mask` under control of `perms & (perms::add_perms | perms::remove_perms)`. *`mask`* shall contain at most one of `perms::add_perms` and `perms::remove_perms`. +The functions set the permissions for the pathname chosen by *`pval`* to `mask & perms::mask` under control of *`opts`*. *`opts`* must contain exactly one of `perm_options::replace`, `perm_options::add`, or `perm_options::remove`, and optionally `perm_options::nofollow`. The overloads with no *`opts`* parameter behave as if *`opts`* is `perm_options::replace`. -If `mask & perms::add_perms`, the functions set the permissions to `status(pval).permissions() | mask & perms::mask`. Otherwise, if `mask & perms::remove_perms`, the functions set the permissions to `status(pval).permissions() & ~(mask & perms::mask)`. Otherwise, the functions set the permissions to `mask & perms::mask`. +If `opts & perm_options::add`, the functions set the permissions to `status(pval).permissions() | (mask & perms::mask)`. Otherwise, if `opts & perm_options::remove`, the functions set the permissions to `status(pval).permissions() & ~(mask & perms::mask)`. Otherwise, the functions set the permissions to `mask & perms::mask`. If `opts & perm_options::nofollow` and *`pval`* names a symbolic link, the functions change the permissions of the symbolic link itself rather than the file it resolves to. ## `proximate` @@ -376,6 +362,8 @@ path proximate(const path& p, const path& base = current_path()); path proximate(const path& p, const path& base, error_code& ec); ``` +The first overload returns `proximate(p, current_path(), ec)`. The other overloads return the result of applying `lexically_proximate` to the weakly canonical forms of *`p`* and *`base`*. The overload that takes *`ec`* returns `path()` if an error occurs. + ## `read_symlink` ```cpp @@ -393,6 +381,8 @@ path relative(const path& p, const path& base = current_path()); path relative(const path& p, const path& base, error_code& ec); ``` +The first overload returns `relative(p, current_path(), ec)`. The other overloads return the result of applying `lexically_relative` to the weakly canonical forms of *`p`* and *`base`*. The overload that takes *`ec`* returns `path()` if an error occurs. + ## `remove` ```cpp @@ -423,11 +413,11 @@ The functions rename *from* to *to*. A symlink is itself renamed, not the file i ## `resize_file` ```cpp -void resize(const path& pval, uintmax_t size); -void resize(const path& pval, uintmax_t size, error_code& ec) noexcept; +void resize_file(const path& pval, uintmax_t size); +void resize_file(const path& pval, uintmax_t size, error_code& ec) noexcept; ``` -The functions alter the size of a file such that `file_size(pval) == size` +The functions alter the size of a file such that `file_size(pval) == size`. ## `space` @@ -472,15 +462,6 @@ file_status symlink_status(const path& pval, error_code& ec) noexcept; The functions return the pathname symlink status, the file type, and permissions, associated with *`pval`*. The functions behave the same as `status(pval)` except that a symlink is itself tested, not the file it chooses. -## `system_complete` - -```cpp -path system_complete(const path& pval); -path system_complete(const path& pval, error_code& ec); -``` - -The functions return an absolute pathname that takes into account, as necessary, the current directory associated with its root name. (For POSIX, the functions return `absolute(pval)`). - ## `temp_directory_path` ```cpp @@ -508,3 +489,11 @@ The first function behaves the same as `path(source)` and the second function be path weakly_canonical(const path& p); path weakly_canonical(const path& p, error_code& ec); ``` + +These functions return a path in canonical form, like the `canonical` function, but the path doesn't need to exist. + +## See also + +[Header Files Reference](../standard-library/cpp-standard-library-header-files.md)\ +[``](../standard-library/filesystem.md)\ +[File System Navigation (C++)](../standard-library/file-system-navigation.md) diff --git a/docs/standard-library/filesystem-operators.md b/docs/standard-library/filesystem-operators.md index cb62d33dd9..82332b0060 100644 --- a/docs/standard-library/filesystem-operators.md +++ b/docs/standard-library/filesystem-operators.md @@ -1,23 +1,32 @@ --- description: "Learn more about: operators" title: " operators" -ms.date: "11/04/2016" -f1_keywords: ["FILESYSTEM/std::experimental::filesystem::operator==", "FILESYSTEM/std::experimental::filesystem::operator!=", "FILESYSTEM/std::experimental::filesystem::operator<", "FILESYSTEM/std::experimental::filesystem::operator<=", "FILESYSTEM/std::experimental::filesystem::operator>", "FILESYSTEM/std::experimental::filesystem::operator>=", "FILESYSTEM/std::experimental::filesystem::operator/", "FILESYSTEM/std::experimental::filesystem::operator<<", "FILESYSTEM/std::experimental::filesystem::operator>>"] -ms.assetid: 102c4833-aa3b-41a8-8998-f5003c546bfd +ms.date: 08/27/2026 +f1_keywords: ["filesystem/std::filesystem::operator==", "filesystem/std::filesystem::operator!=", "filesystem/std::filesystem::operator<", "filesystem/std::filesystem::operator<=", "filesystem/std::filesystem::operator>", "filesystem/std::filesystem::operator>=", "filesystem/std::filesystem::operator/", "filesystem/std::filesystem::operator<<", "filesystem/std::filesystem::operator>>"] +helpviewer_keywords: ["std::filesystem::operator==", "std::filesystem::operator!=", "std::filesystem::operator<", "std::filesystem::operator<=", "std::filesystem::operator>", "std::filesystem::operator>=", "std::filesystem::operator/", "std::filesystem::operator<<", "std::filesystem::operator>>"] --- # `` operators -The operators perform a lexical comparison of two paths as strings. Use the `equivalent` function to determine whether two paths (for example a relative path and an absolute path) refer to the same file or directory on disk. +These nonmember operators for [`std::filesystem::path`](../standard-library/path-class.md) are declared in the C++17 [``](../standard-library/filesystem.md) header. The comparison operators compare two paths element by element in generic format by using `path::compare`, not as raw strings. Use the [`equivalent`](../standard-library/filesystem-functions.md#equivalent) function to determine whether two paths (for example, a relative path and an absolute path) refer to the same file or directory on disk. + +> [!NOTE] +> This page documents the C++17 `std::filesystem` operators. For the historical prestandard operators that MSVC provided in ``, see [`` operators](../standard-library/experimental-filesystem-operators.md). For more information, see [File System Navigation (C++)](../standard-library/file-system-navigation.md). +## Requirements + +**Header:** `` + +**Namespace:** `std::filesystem` + ## operator== ```cpp bool operator==(const path& left, const path& right) noexcept; ``` -The function returns left.native() == right.native(). +The function returns `left.compare(right) == 0`. ## operator!= @@ -25,7 +34,7 @@ The function returns left.native() == right.native(). bool operator!=(const path& left, const path& right) noexcept; ``` -The function returns !(left == right). +The function returns `!(left == right)`. ## operator< @@ -33,7 +42,7 @@ The function returns !(left == right). bool operator<(const path& left, const path& right) noexcept; ``` -The function returns left.native() < right.native(). +The function returns `left.compare(right) < 0`. ## operator<= @@ -41,7 +50,7 @@ The function returns left.native() < right.native(). bool operator<=(const path& left, const path& right) noexcept; ``` -The function returns !(right \< left). +The function returns `!(right < left)`. ## operator> @@ -49,7 +58,7 @@ The function returns !(right \< left). bool operator>(const path& left, const path& right) noexcept; ``` -The function returns right \< left. +The function returns `right < left`. ## operator>= @@ -57,7 +66,7 @@ The function returns right \< left. bool operator>=(const path& left, const path& right) noexcept; ``` -The function returns !(left < right). +The function returns `!(left < right)`. ## operator/ @@ -65,13 +74,7 @@ The function returns !(left < right). path operator/(const path& left, const path& right); ``` -The function executes: - -```cpp -basic_string str; -path ans = left; -return (ans /= right); -``` +The function returns `path(left) /= right`. ## operator<< @@ -80,20 +83,26 @@ template basic_ostream& operator<<(basic_ostream& os, const path& pval); ``` -The function returns os << pval.string\(). +The function inserts the path into the stream as a quoted string. It returns `os << quoted(pval.string())`. ## operator>> ```cpp template -basic_istream& operator<<(basic_istream& is, const path& pval); +basic_istream& operator>>(basic_istream& is, path& pval); ``` -The function executes: +The function extracts a quoted string from the stream and assigns it to *`pval`*. It executes: ```cpp basic_string str; -is>> str; +is >> quoted(str); pval = str; -return (is); +return is; ``` + +## See also + +[Header Files Reference](../standard-library/cpp-standard-library-header-files.md)\ +[``](../standard-library/filesystem.md)\ +[File System Navigation (C++)](../standard-library/file-system-navigation.md) diff --git a/docs/standard-library/filesystem.md b/docs/standard-library/filesystem.md index 449d7f2bb7..3b53ef8e6e 100644 --- a/docs/standard-library/filesystem.md +++ b/docs/standard-library/filesystem.md @@ -1,50 +1,41 @@ --- title: "" description: "Describes the classes, functions, and types in the filesystem header of the Standard C++ library." -ms.date: "09/02/2021" -f1_keywords: ["", "filesystem/std::filesystem", "std::filesystem", "std::experimental::filesystem"] -no-loc: [filesystem, experimental, char, wchar_t, char16_t, char32_t] +ms.date: 08/27/2026 +f1_keywords: ["", "filesystem/std::filesystem", "std::filesystem"] +no-loc: [filesystem, char, wchar_t, char16_t, char32_t] --- -# `filesystem` +# `` -Include the header `` for access to classes and functions that manipulate and retrieve information about paths, files, and directories. +For current code, include the C++17 standard header `` and use the `std::filesystem` namespace for classes and functions that manipulate and retrieve information about paths, files, and directories. Compile with `/std:c++17` or later. ## Syntax ```cpp #include // C++17 standard header file name -#include // Header file for pre-standard implementation -using namespace std::experimental::filesystem::v1; +using namespace std::filesystem; ``` -> [!IMPORTANT] -> At the release of Visual Studio 2017, the `` header was not yet a C++ standard. C++ in Visual Studio 2017 RTW implements the final draft standard, found in [ISO/IEC JTC 1/SC 22/WG 21 N4100](https://wg21.link/n4100). Visual Studio 2017 version 15.7 and later supports the new C++17 `` standard. -> This is a completely new implementation, incompatible with the previous `std::experimental` version. It was made necessary by symlink support, bug fixes, and changes in standard-required behavior. In Visual Studio 2019 version 16.3 and later, including `` provides only the new `std::filesystem`. Including `` provides only the old experimental implementation. The experimental implementation will be removed in the next ABI-breaking release of the libraries. +> [!NOTE] +> Historical note: Before C++17 standardized ``, MSVC shipped a separate prestandard implementation in the `` header, which was removed starting in MSVC Build Tools version 14.51. For its documentation, see [``](../standard-library/experimental-filesystem.md). -This header supports file systems for one of two broad classes of host operating systems: Microsoft Windows and POSIX. +The `` header supports file systems for Microsoft Windows and POSIX. While most functionality is common to both operating systems, this document identifies where differences occur. For example: - Windows supports multiple root names, such as `c:` or `\\network_name`. A file system consists of a forest of trees, each with its own root directory, such as `c:\` or `\\network_name\`, and each with its own current directory, for completing a relative pathname (one that's not an absolute pathname). - - POSIX supports a single tree, with no root name, the single root directory `/`, and a single current directory. Another significant difference is the native representation of pathnames: - Windows uses a null-terminated sequence of **`wchar_t`**, encoded as UTF-16 (one or more elements for each character). - - POSIX uses a null-terminated sequence of **`char`**, encoded as UTF-8 (one or more elements for each character). - - An object of class `path` stores the pathname in native form, but supports easy conversion between this stored form and several external forms: - A null-terminated sequence of **`char`**, encoded as favored by the operating system. - - A null-terminated sequence of **`char`**, encoded as UTF-8. - - A null-terminated sequence of **`wchar_t`**, encoded as favored by the operating system. - - A null-terminated sequence of **`char16_t`**, encoded as UTF-16. - - A null-terminated sequence of **`char32_t`**, encoded as UTF-32. Interconversions between these representations are mediated, as needed, by the use of one or more `codecvt` facets. If no specific locale object is specified, these facets are obtained from the global locale. @@ -52,25 +43,17 @@ Another significant difference is the native representation of pathnames: Another difference is the detail with which each operating system lets you specify file or directory access permissions: - Windows records whether a file is read-only or writable, an attribute that has no meaning for directories. - - POSIX records whether a file can be read, written, or executed (scanned, if a directory). And, whether each operation is allowed for the owner, the owner's group, or for everybody, plus a few other permissions. Common to both systems is the structure imposed on a pathname once you get past the root name. For the pathname `c:/abc/xyz/def.ext`: - The root name is `c:`. - - The root directory is `/`. - - The root path is `c:/`. - - The relative path is `abc/xyz/def.ext`. - - The parent path is `c:/abc/xyz`. - - The filename is `def.ext`. - - The stem is `def`. - - The extension is `.ext`. A minor difference is the preferred separator between the sequence of directories in a pathname. Both operating systems let you write a forward slash `/`, but in some contexts Windows prefers a backslash `\`. The implementation stores its preferred separator in the data member `preferred_separator` in `path`. @@ -79,20 +62,18 @@ Finally, `path` objects have an important feature: You can use them wherever a f For more information and code examples, see [File system navigation (C++)](../standard-library/file-system-navigation.md). -## Members - -### Classes +## Classes |Name|Description| |-|-| |[`directory_entry` class](../standard-library/directory-entry-class.md)|Describes an object that is returned by a `directory_iterator` or a `recursive_directory_iterator` and contains a `path`.| |[`directory_iterator` class](../standard-library/directory-iterator-class.md)|Describes an input iterator that sequences through the file names in a file-system directory.| -|[`filesystem_error` class](../standard-library/filesystem-error-class.md)|A base class for exceptions that are thrown to report a low-level system overflow.| +|[`filesystem_error` class](../standard-library/filesystem-error-class.md)|A base class for exceptions that are thrown to report a low-level system error.| |[`path` class](../standard-library/path-class.md)|Defines a class that stores an object of template type `String` that is suitable for use as a file name.| |[`recursive_directory_iterator` class](../standard-library/recursive-directory-iterator-class.md)|Describes an input iterator that sequences through the file names in a file-system directory. The iterator can also descend into subdirectories.| |[`file_status` class](../standard-library/file-status-class.md)|Wraps a `file_type`.| -### Structs +## Structs |Name|Description| |-|-| diff --git a/docs/standard-library/path-class.md b/docs/standard-library/path-class.md index 8f7edbb9c1..b57cc27eb2 100644 --- a/docs/standard-library/path-class.md +++ b/docs/standard-library/path-class.md @@ -1,14 +1,16 @@ --- title: "path Class" -description: "Learn more about: path Class" -ms.date: 06/17/2022 -f1_keywords: ["filesystem/std::experimental::filesystem::path"] +description: "Learn more about the C++17 std::filesystem path class in the header." +ms.date: 08/27/2026 +f1_keywords: ["filesystem/std::filesystem::path"] +helpviewer_keywords: ["std::filesystem::path class"] --- - -# `path` Class +# `path` class The **`path`** class stores an object of type `string_type`, called `myname` here for the purposes of exposition, suitable for use as a pathname. `string_type` is a synonym for `basic_string`, where `value_type` is a synonym for **`wchar_t`** on Windows or **`char`** on POSIX. +The `path` class described here is the C++17 `std::filesystem::path` class in the `` header. + For more information, and code examples, see [File System Navigation (C++)](../standard-library/file-system-navigation.md). ## Syntax @@ -31,21 +33,27 @@ class path; |[`iterator`](#iterator)|A bidirectional constant iterator that designates the `path` components of `myname`.| |[`string_type`](#string_type)|The type is a synonym for `basic_string`.| +### Enumerations + +|Type name|Description| +|-|-| +|[`format`](#format)|Specifies the pathname format for constructors: `auto_format`, `native_format`, or `generic_format`.| + ### Member functions |Member function|Description| |-|-| -|[`append`](#append)|Appends the specified sequence to `mypath`, converted and inserting a preferred_separator as needed.| -|[`assign`](#assign)|Replaces `mypath` with the specified sequence, converted as needed.| +|[`append`](#append)|Appends the specified sequence to `myname`, converted and inserting a preferred_separator as needed.| +|[`assign`](#assign)|Replaces `myname` with the specified sequence, converted as needed.| |[`begin`](#begin)|Returns a `path::iterator` designating the first path element in the pathname, if present.| -|[`c_str`](#c_str)|Returns a pointer to the first character in `mypath`.| -|[`clear`](#clear)|Executes `mypath.clear()`.| +|[`c_str`](#c_str)|Returns a pointer to the first character in `myname`.| +|[`clear`](#clear)|Executes `myname.clear()`.| |[`compare`](#compare)|Returns comparison values.| -|[`concat`](#concat)|Appends the specified sequence to `mypath`, converted (but not inserting a separator) as needed.| -|[`empty`](#empty)|Returns `mypath.empty()`.| +|[`concat`](#concat)|Appends the specified sequence to `myname`, converted (but not inserting a separator) as needed.| +|[`empty`](#empty)|Returns `myname.empty()`.| |[`end`](#end)|Returns an end-of-sequence iterator of type `iterator`.| |[`extension`](#extension)|Returns the suffix of `filename()`.| -|[`filename`](#filename)|Returns the root directory component of `myname`, specifically `empty() ? path() : *--end()`. The component may be empty.| +|[`filename`](#filename)|Returns the filename component of `myname`, specifically `empty() ? path() : *--end()`. The component may be empty.| |[`generic_string`](#generic_string)|Returns `this->string(al)` with (under Windows) any backslash converted to a forward slash.| |[`generic_u16string`](#generic_u16string)|Returns `u16string()` with (under Windows) any backslash converted to a forward slash.| |[`generic_u32string`](#generic_u32string)|Returns `u32string()` with (under Windows) any backslash converted to a forward slash.| @@ -61,6 +69,9 @@ class path; |[`has_stem`](#has_stem)|Returns `!stem().empty()`.| |[`is_absolute`](#is_absolute)|For Windows, the function returns `has_root_name() && has_root_directory()`. For POSIX, the function returns `has_root_directory()`.| |[`is_relative`](#is_relative)|Returns `!is_absolute()`.| +|[`lexically_normal`](#lexically_normal)|Returns `myname` converted to normal form.| +|[`lexically_proximate`](#lexically_proximate)|Returns `lexically_relative(base)`, or `*this` if that result is empty.| +|[`lexically_relative`](#lexically_relative)|Returns `myname` made relative to a base path, using lexical (string) analysis only.| |[`make_preferred`](#make_preferred)|Converts each separator to a `preferred_separator` as needed.| |[`native`](#native)|Returns the native representation of the path.| |[`parent_path`](#parent_path)|Returns the parent path component of `myname`.| @@ -73,13 +84,13 @@ class path; |[`root_name`](#root_name)|Returns the root name component of `myname`. | |[`root_path`](#root_path)|Returns the root path component of `myname`.| |[`stem`](#stem)|Returns the `stem` component of `myname`.| -|[`string`](#string)|Converts the sequence stored in `mypath`.| -|[`swap`](#swap)|Executes `swap(mypath, right.mypath)`.| -|[`u16string`](#u16string)|Converts the sequence stored in `mypath` to UTF-16 and returns it stored in an object of type `u16string`.| -|[`u32string`](#u32string)|Converts the sequence stored in `mypath` to UTF-32 and returns it stored in an object of type `u32string`.| -|[`u8string`](#u8string)|Converts the sequence stored in `mypath` to UTF-8 and returns it stored in an object of type `u8string`.| +|[`string`](#string)|Converts the sequence stored in `myname`.| +|[`swap`](#swap)|Executes `swap(myname, right.myname)`.| +|[`u16string`](#u16string)|Converts the sequence stored in `myname` to UTF-16 and returns it stored in an object of type `u16string`.| +|[`u32string`](#u32string)|Converts the sequence stored in `myname` to UTF-32 and returns it stored in an object of type `u32string`.| +|[`u8string`](#u8string)|Converts the sequence stored in `myname` to UTF-8 and returns it stored in an object of type `u8string`.| |[`value_type`](#value_type)|The type describes the path elements favored by the host operating system.| -|[`wstring`](#wstring)|Converts the sequence stored in `mypath` to the encoding favored by the host system for a **`wchar_t`** sequence and returns it stored in an object of type `wstring`.| +|[`wstring`](#wstring)|Converts the sequence stored in `myname` to the encoding favored by the host system for a **`wchar_t`** sequence and returns it stored in an object of type `wstring`.| ### Operators @@ -94,11 +105,11 @@ class path; **Header:** `` -**Namespace:** `std::experimental::filesystem` +**Namespace:** `std::filesystem` ## `path::append` -Appends the specified sequence to `mypath`, converted and inserting a `preferred_separator` as needed. +Appends the specified sequence to `myname`, converted and inserting a `preferred_separator` as needed. ```cpp template @@ -121,9 +132,11 @@ End of specified sequence. ## `path::assign` -Replaces `mypath` with the specified sequence, converted as needed. +Replaces `myname` with the specified sequence, converted as needed. ```cpp +path& assign(string_type&& source); + template path& assign(const Source& source); @@ -152,15 +165,15 @@ iterator begin() const; ## `path::c_str` -Returns a pointer to the first character in `mypath`. +Returns a pointer to the first character in `myname`. ```cpp -const value_type& *c_str() const noexcept; +const value_type* c_str() const noexcept; ``` ## `path::clear` -Executes `mypath.clear()`. +Executes `myname.clear()`. ```cpp void clear() noexcept; @@ -168,11 +181,12 @@ void clear() noexcept; ## `path::compare` -The first function returns `mypath.compare(pval.native())`. The second function returns `mypath.compare(str)`. The third function returns `mypath.compare(ptr)`. +The first function compares the elements of this path with *`pval`*. The other functions construct a path from their argument and return the result of comparing it with this path. ```cpp int compare(const path& pval) const noexcept; int compare(const string_type& str) const; +int compare(basic_string_view str) const; int compare(const value_type *ptr) const; ``` @@ -189,7 +203,7 @@ Pointer to compare. ## `path::concat` -Appends the specified sequence to `mypath`, converted (but not inserting a separator) as needed. +Appends the specified sequence to `myname`, converted (but not inserting a separator) as needed. ```cpp template @@ -220,7 +234,7 @@ typedef iterator const_iterator; ## `path::empty` -Returns `mypath.empty()`. +Returns `myname.empty()`. ```cpp bool empty() const noexcept; @@ -252,12 +266,36 @@ Otherwise, the suffix begins with (and includes) the rightmost dot. ## `path::filename` -Returns the root directory component of `myname`, specifically `empty() path() : *--end()`. The component may be empty. +Returns the filename component of `myname`, specifically `empty() ? path() : *--end()`. The component may be empty. ```cpp path filename() const; ``` +## `path::format` + +Specifies the pathname format used to interpret the character sequence passed to a `path` constructor. + +```cpp +enum format { + auto_format, + native_format, + generic_format +}; +``` + +### Members + +|Enumerator|Description| +|-|-| +|`auto_format`|The implementation autodetects the format. This is the default for the constructors that take a `format` argument.| +|`native_format`|Interpret the sequence in the native pathname format.| +|`generic_format`|Interpret the sequence in the generic pathname format.| + +### Remarks + +Because the native format and the generic format are interchangeable on Windows, the Microsoft implementation treats all three enumerators the same. The `format` parameter is provided for standard conformance and portability. For more information, see the WG21 N4659 [fs.class.path] specification. + ## `path::generic_string` Returns `this->string(al)` with (under Windows) any backslash converted to a forward slash. @@ -425,6 +463,48 @@ For `pval` an object of type `path`: 1. Altering `myname` invalidates all iterators designating elements in `myname`. +## `path::lexically_normal` + +Returns `myname` converted to normal form. The conversion is purely lexical: the filesystem isn't accessed. + +```cpp +path lexically_normal() const; +``` + +### Remarks + +Normalization collapses redundant elements such as `.` and `..` and directory separators. For example, `path("a/./b/../c").lexically_normal()` yields `a\c` on Windows. An empty path normalizes to an empty path; a path that reduces to nothing normalizes to `.`. For the full normalization algorithm, see the WG21 N4659 [fs.path.generic] specification. + +## `path::lexically_proximate` + +Returns the result of [`lexically_relative(base)`](#lexically_relative). If that result is an empty path, returns a copy of `*this` instead. + +```cpp +path lexically_proximate(const path& base) const; +``` + +### Parameters + +*`base`*\ +The base path to make `*this` proximate to. + +## `path::lexically_relative` + +Returns `myname` made relative to *`base`*, using lexical (string) analysis only. The filesystem isn't accessed. + +```cpp +path lexically_relative(const path& base) const; +``` + +### Parameters + +*`base`*\ +The base path to make `*this` relative to. + +### Remarks + +If `root_name() != base.root_name()`, or if one path is absolute and the other is relative, or if the path has a filename but no root directory while the base doesn't, returns an empty path. Otherwise, determines the relative path from *`base`* to `*this` by finding the first mismatched element and emitting `..` for each remaining element of *`base`*, followed by the remaining elements of `*this`. For example, `path("/a/d").lexically_relative("/a/b/c")` yields `..\..\d`. For the full algorithm, see the WG21 N4659 [fs.path.gen] specification. + ## `path::make_preferred` Converts each separator to a `preferred_separator` as needed. @@ -445,7 +525,7 @@ const string_type& native() const noexcept; The path is available in a portable generic format (see [`generic_string()`](#generic_string)) or the native format of the path. This function returns the native string. On a POSIX system, the generic format and the native format are the same. -In the following example running on Windows 11, the generic path string is `c:/t/temp/temp.txt` and the native string is `c:\\t\\temp.txt` +In the following example running on Windows, the generic path string is `c:/t/temp.txt` and the native string is `c:\t\temp.txt`. ```cpp // Compile with /std:c++17 or higher @@ -454,7 +534,7 @@ In the following example running on Windows 11, the generic path string is `c:/t int main() { std::filesystem::path p(R"(c:\t\temp.txt)"); - auto native = p.native(); // Windows: L"c:\\t\temp.txt" + auto native = p.native(); // Windows: L"c:\\t\\temp.txt" auto generic = p.generic_string(); // Windows: "c:/t/temp.txt" } ``` @@ -466,6 +546,7 @@ Replaces the elements of the path with a copy of another path. ```cpp path& operator=(const path& right); path& operator=(path&& right) noexcept; +path& operator=(string_type&& source); template path& operator=(const Source& source); @@ -481,7 +562,7 @@ The source `path`. ### Remarks -The first member operator copies `right.myname` to `myname`. The second member operator moves `right.myname` to `myname`. The third member operator behaves the same as `*this = path(source)`. +The first member operator copies `right.myname` to `myname`. The second member operator moves `right.myname` to `myname`. The third member operator moves *`source`* into `myname`. The fourth member operator behaves the same as `*this = path(source)`. ## `path::operator+=` @@ -490,6 +571,7 @@ Various `concat` expressions. ```cpp path& operator+=(const path& right); path& operator+=(const string_type& str); +path& operator+=(basic_string_view str); path& operator+=(const value_type *ptr); path& operator+=(value_type elem); @@ -519,19 +601,7 @@ The added source. ### Remarks -The member functions behave the same as the following corresponding expressions: - -1. `concat(right);` - -1. `concat(path(str));` - -1. `concat(ptr);` - -1. `concat(string_type(1, elem));` - -1. `concat(source);` - -1. `concat(path(basic_string(1, elem)));` +The member functions behave the same as calling [`concat`](#concat) with the argument. The `path`, `string_type`, `basic_string_view`, and null-terminated `value_type*` overloads concatenate the argument's character sequence. The `value_type` and `Elem` overloads concatenate a single character. The templated `Source` overload concatenates the converted source sequence. ## `path::operator/=` @@ -585,22 +655,24 @@ Returns the parent path component of `myname`, specifically the prefix of `mynam Constructs a `path` in various ways. ```cpp -path(); +path() noexcept; path(const path& right); path(path&& right) noexcept; -template -path(const Source& source); +path(string_type&& source, format fmt = auto_format); template -path(const Source& source, const locale& loc); +path(const Source& source, format fmt = auto_format); template -path(InIt first, InIt last); +path(InIt first, InIt last, format fmt = auto_format); + +template +path(const Source& source, const locale& loc, format fmt = auto_format); template -path(InIt first, InIt last, const locale& loc); +path(InIt first, InIt last, const locale& loc, format fmt = auto_format); ``` ### Parameters @@ -611,6 +683,9 @@ The path of which the constructed path is to be a copy. *`source`*\ The source of which the constructed path is to be a copy. +*`fmt`*\ +The pathname [`format`](#format) used to interpret *`source`* or the *`first`*/*`last`* range. Defaults to `auto_format`. + *`loc`*\ The specified locale. @@ -626,17 +701,21 @@ The constructors all construct `myname` in various ways: For `path()` it's `myname()`. -For `path(const path& right`) it's `myname(right.myname)`. +For `path(const path& right)` it's `myname(right.myname)`. For `path(path&& right)` it's `myname(right.myname)`. -For `template path(const Source& source)` it's `myname(source)`. +For `path(string_type&& source, format fmt)` it's `myname(move(source))`. + +For `template path(const Source& source, format fmt)` it's `myname(source)`. + +For `template path(const Source& source, const locale& loc, format fmt)` it's `myname(source)`, obtaining any needed `codecvt` facets from `loc`. -For `template path(const Source& source, const locale& loc)` it's `myname(source)`, obtaining any needed `codecvt` facets from `loc`. +For `template path(InIt first, InIt last, format fmt)` it's `myname(first, last)`. -For `template path(InIt first, InIt last)` it's `myname(first, last)`. +For `template path(InIt first, InIt last, const locale& loc, format fmt)` it's `myname(first, last)`, obtaining any needed `codecvt` facets from `loc`. -For `template path(InIt first, InIt last, const locale& loc)` it's `myname(first, last)`, obtaining any needed `codecvt` facets from `loc`. +The *`fmt`* parameter selects the pathname format. On Windows, the native and generic formats are interchangeable, so the Microsoft implementation ignores *`fmt`*. ## `path::preferred_separator` @@ -644,9 +723,9 @@ The constant object gives the preferred character for separating path components ```cpp #if _WIN32_C_LIB -static constexpr value_type preferred_separator == L'\\'; +static constexpr value_type preferred_separator = L'\\'; #else // assume POSIX -static constexpr value_type preferred_separator == '/'; +static constexpr value_type preferred_separator = '/'; #endif // filesystem model now defined ``` @@ -765,17 +844,17 @@ Returns the `stem` component of `myname`, specifically `filename().native()` wit ## `path::string` -Converts the sequence stored in `mypath`. +Converts the sequence stored in `myname`. ```cpp -template \, class Alloc = allocator\> -basic_string\ string(const Alloc& al = Alloc()) const; +template , class Alloc = allocator> +basic_string string(const Alloc& al = Alloc()) const; string string() const; ``` ### Remarks -The first (template) member function converts the sequence stored in `mypath` the same way as: +The first (template) member function converts the sequence stored in `myname` the same way as: 1. `string()` for `string()` @@ -785,7 +864,7 @@ The first (template) member function converts the sequence stored in `mypath` th 1. `u32string()` for `string()` -The second member function converts the sequence stored in `mypath` to the encoding favored by the host system for a **`char`** sequence and returns it stored in an object of type `string`. +The second member function converts the sequence stored in `myname` to the encoding favored by the host system for a **`char`** sequence and returns it stored in an object of type `string`. ## `path::string_type` @@ -797,7 +876,7 @@ typedef basic_string string_type; ## `path::swap` -Executes `swap(mypath, right.mypath)`. +Executes `swap(myname, right.myname)`. ```cpp void swap(path& right) noexcept; @@ -805,7 +884,7 @@ void swap(path& right) noexcept; ## `path::u16string` -Converts the sequence stored in `mypath` to UTF-16 and returns it stored in an object of type `u16string`. +Converts the sequence stored in `myname` to UTF-16 and returns it stored in an object of type `u16string`. ```cpp u16string u16string() const; @@ -813,7 +892,7 @@ u16string u16string() const; ## `path::u32string` -Converts the sequence stored in `mypath` to UTF-32 and returns it stored in an object of type `u32string`. +Converts the sequence stored in `myname` to UTF-32 and returns it stored in an object of type `u32string`. ```cpp u32string u32string() const; @@ -821,7 +900,7 @@ u32string u32string() const; ## `path::u8string` -Converts the sequence stored in `mypath` to UTF-8 and returns it stored in an object of type `u8string`. +Converts the sequence stored in `myname` to UTF-8 and returns it stored in an object of type `u8string`. ```cpp string u8string() const; @@ -841,7 +920,7 @@ typedef char value_type; ## `path::wstring` -Converts the sequence stored in `mypath` to the encoding favored by the host system for a **`wchar_t`** sequence and returns it stored in an object of type `wstring`. +Converts the sequence stored in `myname` to the encoding favored by the host system for a **`wchar_t`** sequence and returns it stored in an object of type `wstring`. ```cpp wstring wstring() const; @@ -849,4 +928,5 @@ wstring wstring() const; ## See also +[``](../standard-library/filesystem.md)\ [Header Files Reference](../standard-library/cpp-standard-library-header-files.md) diff --git a/docs/standard-library/recursive-directory-iterator-class.md b/docs/standard-library/recursive-directory-iterator-class.md index 12ce5fff52..cecff5a423 100644 --- a/docs/standard-library/recursive-directory-iterator-class.md +++ b/docs/standard-library/recursive-directory-iterator-class.md @@ -1,9 +1,8 @@ --- description: "Learn more about: recursive_directory_iterator Class" title: "recursive_directory_iterator Class" -ms.date: 06/17/2022 -f1_keywords: ["filesystem/std::tr2::sys::recursive_directory_iterator"] -ms.assetid: 79a061bd-5b64-404c-97e8-749c888c2ced +ms.date: 08/27/2026 +f1_keywords: ["filesystem/std::filesystem::recursive_directory_iterator"] ms.custom: devdivchpfy22 --- @@ -31,7 +30,7 @@ The class template stores: 1. an object of type `directory_options`, called `myoptions` here, which records the options established at construction -A default constructed object of type `recursive_directory_entry` has an end-of-sequence iterator at `mystack.top().first` and represents the end-of-sequence iterator. For example, given the directory `abc` with entries `def` (a directory), `def/ghi`, and `jkl`, the code: +A default-constructed object of type `recursive_directory_iterator` has an end-of-sequence iterator at `mystack.top().first` and represents the end-of-sequence iterator. For example, given the directory `abc` with entries `def` (a directory), `def/ghi`, and `jkl`, the code: ```cpp for (recursive_directory_iterator next(path("abc")), end; next != end; ++next) @@ -58,7 +57,7 @@ will call visit with the arguments `path("abc/def/ghi")` and `path("abc/jkl")`. |[disable_recursion_pending](#disable_recursion_pending)|Stores **`true`** in `no_push`.| |[increment](#increment)|Advances to the next filename in sequence.| |[options](#options)|Returns `myoptions`.| -|[pop](#pop)|Returns the next object.| +|[pop](#pop)|Moves the iterator to the next entry at the next lower depth.| |[recursion_pending](#recursion_pending)|Returns `!no_push`.| ### Operators @@ -74,9 +73,9 @@ will call visit with the arguments `path("abc/def/ghi")` and `path("abc/jkl")`. ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std::tr2::sys +**Namespace:** `std::filesystem` ## recursive_directory_iterator::depth @@ -99,7 +98,7 @@ void disable_recursion_pending(); Advances to the next filename in sequence. ```cpp -recursive_directory_iterator& increment(error_code& ec) noexcept; +recursive_directory_iterator& increment(error_code& ec); ``` ### Parameters @@ -173,14 +172,13 @@ Increments the `recursive_directory_iterator`. ```cpp recursive_directory_iterator& operator++(); - -recursive_directory_iterator& operator++(int); +recursive_directory_iterator operator++(int); ``` ### Parameters *int*\ -The specified increment. +Dummy argument. It's a C++ convention used only to distinguish the postfix increment operator from the prefix increment operator. The C++ standard requires the postfix form to take a dummy int parameter. ### Remarks @@ -196,12 +194,18 @@ directory_options options() const; ## recursive_directory_iterator::pop -Returns the next object. +Moves the iterator to the next entry at the next lower depth. ```cpp void pop(); +void pop(error_code& ec); ``` +### Parameters + +`ec`\ +The error code that reports the status of the operation. The overload that takes an *ec* argument reports errors in *ec* instead of throwing an exception. + ### Remarks If `depth() == 0` the object becomes an end-of-sequence iterator. Otherwise, the member function terminates scanning of the current (deepest) directory and resumes at the next lower depth. diff --git a/docs/standard-library/space-info-structure.md b/docs/standard-library/space-info-structure.md index bdb546b54b..e305998f98 100644 --- a/docs/standard-library/space-info-structure.md +++ b/docs/standard-library/space-info-structure.md @@ -1,9 +1,8 @@ --- description: "Learn more about: space_info Structure" title: "space_info Structure" -ms.date: "09/10/2018" -f1_keywords: ["filesystem/std::tr2::sys::space_info"] -ms.assetid: f2b35b42-06ff-45bd-8617-39a0f5358a54 +ms.date: 08/27/2026 +f1_keywords: ["filesystem/std::filesystem::space_info"] --- # space_info Structure @@ -26,15 +25,15 @@ struct space_info |Name|Description| |----------|-----------------| -|`unsigned long long capacity`|Represents the total number of bytes that the volume can represent.| -|`unsigned long long free`|Represents the number of bytes that are not used to represent data on the volume.| -|`unsigned long long available`|Represents the number of bytes that are available to represent data on the volume.| +|`uintmax_t capacity`|Represents the total number of bytes that the volume can represent.| +|`uintmax_t free`|Represents the number of bytes that are not used to represent data on the volume.| +|`uintmax_t available`|Represents the number of bytes that are available to represent data on the volume.| ## Requirements **Header:** \ -**Namespace:** std::experimental::filesystem +**Namespace:** std::filesystem ## See also diff --git a/docs/standard-library/toc.yml b/docs/standard-library/toc.yml index bfb970bf6f..abcc34e3e7 100644 --- a/docs/standard-library/toc.yml +++ b/docs/standard-library/toc.yml @@ -8,7 +8,7 @@ items: href: cpp-standard-library-header-files.md - name: expanded: false - items: + items: - name: href: algorithm.md - name: functions @@ -375,6 +375,31 @@ items: href: recursive-directory-iterator-class.md - name: space_info struct href: space-info-structure.md + - name: (removed) + expanded: false + items: + - name: + href: experimental-filesystem.md + - name: functions + href: experimental-filesystem-functions.md + - name: operators + href: experimental-filesystem-operators.md + - name: enumerations + href: experimental-filesystem-enumerations.md + - name: directory_entry class + href: experimental-filesystem-directory-entry-class.md + - name: directory_iterator class + href: experimental-filesystem-directory-iterator-class.md + - name: file_status class + href: experimental-filesystem-file-status-class.md + - name: filesystem_error class + href: experimental-filesystem-error-class.md + - name: path class + href: experimental-filesystem-path-class.md + - name: recursive_directory_iterator class + href: experimental-filesystem-recursive-directory-iterator-class.md + - name: space_info struct + href: experimental-filesystem-space-info-structure.md - name: expanded: false items: