Reference

This reference documentation describes components that C++ programs may use to perform operations involving file systems, including paths, regular files, and directories.

Conformance

ISO/IEC 9945 Conformance
Operating System Dependent Conformance

ISO/IEC 9945 Conformance

Some behavior in this reference documentation is specified by reference to ISO/IEC 9945. How such behavior is actually implemented is unspecified.

	Note
	This constitutes an "as if" rule for implementation of operating system dependent behavior. In practice implementations will usually call native operating system API's.

Implementations are encouraged to provide such behavior as it is defined by ISO/IEC 9945. Implementations shall document any behavior that differs from the behavior defined by ISO/IEC 9945. Implementations that do not support exact ISO/IEC 9945 behavior are encouraged to provide behavior as close to ISO/IEC 9945 behavior as is reasonable given the limitations of actual operating systems and file systems. If an implementation cannot provide any reasonable behavior, the implementation shall report an error in an implementation-defined manner.

	Note
	Such errors might be reported by an `#error` directive, a `static_assert`, a [class_filesystem_filesystem_error] exception, a special return value, or some other manner.

Implementations are not required to provide behavior that is not supported by a particular file system.

	Tip
	The FAT file system used by some memory cards, camera memory, and floppy discs does not support hard links, symlinks, and many other features of more capable file systems. Implementations are only required to support the FAT features supported by the host operating system.

The behavior of functions described in this reference may differ from their specification in the presence of file system races. No diagnostic is required.

If the possibility of a file system race would make it unreliable for a program to test for a precondition before calling a function described in this reference documentation, Requires is not specified for the condition. Instead, the condition is specified as a Throws condition.

	Note
	As a design practice, preconditions are not specified when it is unreasonable for a program to detect them prior to calling the function.

Operating System Dependent Conformance

Some behavior is specified in this reference documentation as being operating system dependent ([fs.def.osdep]). The operation system an implementation is dependent upon is implementation defined.

It is permissible for an implementation to be dependent upon an operating system emulator rather than the actual operating system.

Tip

Example: An implementation uses Cygwin, a Linux® API emulator for some Windows® operating system versions. The implementation would define Cygwin as its operating system. Users could refer to the Cygwin documentation to find details of the operating system dependent behavior.

It is user and conformance test detectable that such an implementation is running on Cygwin. Users would be misled and conformance tests would fail if the implementation defined Linux or Windows rather than Cygwin as the operating system, since real behavior is a blend of the two.

Definitions

The following definitions shall apply throughout this reference documentation:

operating system dependent behavior

Behavior that is dependent upon the behavior and characteristics of an operating system. See here.

file

An object that can be written to, or read from, or both. A file has certain attributes, including type. File types include regular files and directories. Other types of files, such as symbolic links, may be supported by the implementation.

file system

A collection of files and their attributes.

filename

The name of a file. Filenames "." and ".." have special meaning. The following characteristics of filenames are operating system dependent:

The permitted characters. See here for examples.
Specific filenames that are not permitted.
Additional filenames that have special meaning.
Case awareness and sensitivity during path resolution.
Special rules that may apply to file types other than regular files, such as directories.

path

A sequence of elements that identify the location of a file within a filesystem. The elements are the root-name_opt, root-directory_opt, and an optional sequence of filenames.

	Note
	A pathname is the concrete representation of a path.

absolute path

A path that unambiguously identifies the location of a file without reference to an additional starting location. The elements of a path that determine if it is absolute are operating system dependent.

relative path

A path that is not absolute, and so only unambiguously identifies the location of a file when resolved relative to an implied starting location. The elements of a path that determine if it is relative are operating system dependent.

	Note
	Paths "." and ".." are relative paths.

canonical path

An absolute path that has no elements that are symbolic links, and no "." or ".." elements.

pathname

A character string that represents the name of a path. Pathnames are formatted according to the generic pathname grammar or an operating system dependent native pathname format.

native pathname format

The operating system dependent pathname format accepted by the host operating system.

normal form path

A path with no redundant directory separators, current directory (dot) or parent directory (dot-dot) elements. The normal form for an empty path is an empty path. [v3: The normal form for a path ending in a directory-separator that is not the root directory is the same path with a current directory (dot) element appended.]

link

A directory entry object that associates a filename with a file. On some file systems, several directory entries can associate names with the same file.

hard link

A link to an existing file. Some file systems support multiple hard links to a file. If the last hard link to a file is removed, the file itself is removed.

	Note
	A hard link can be thought of as a shared-ownership smart pointer to a file.

symbolic link

A type of file with the property that when the file is encountered during pathname resolution, a string stored by the file is used to modify the pathname resolution.

	Note
	A symbolic link can be thought of as a raw pointer to a file. If the file pointed to does not exist, the symbolic link is said to be a "dangling" symbolic link.

file system race

The condition that occurs when multiple threads, processes, or computers interleave access and modification of the same object within a file system.

Error Reporting

Many of the Filesystem library functions provide two overloads, one that throws an exception to report file system errors, and another that sets an error_code. This supports two common use cases:

Uses where file system errors are truly exceptional and indicate a serious failure. Throwing an exception is the most appropriate response. This is the preferred default for most everyday programming.
Uses where file system errors are routine and do not necessarily represent failure. Returning an error code is the most appropriate response. This allows application specific error handling, including simply ignoring the error.

Functions an argument of type system::error_code& report errors as follows, unless otherwise specified:

When a call by the implementation to an operating system or other underlying API results in an error that prevents the function from meeting its specifications, an exception of type filesystem_error is thrown.
If the implementation needs to perform path character code conversion as part of operation and the conversion fails, the error is reported by throwing an exception of type system::system_error.
Failure to allocate storage is reported by throwing an exception as described in the C++ standard, 17.6.4.10 [res.on.exception.handling].
Destructors throw nothing.

Functions an argument of type system::error_code& report errors as follows, unless otherwise specified:

If a call by the implementation to an operating system or other underlying API results in an error that prevents the function from meeting its specifications, the system::error_code& argument is set as appropriate for the specific error. Otherwise, clear() is called on the system::error_code& argument.
If the implementation needs to perform path character code conversion as part of operation and the conversion fails, the error is reported by throwing an exception of type system::system_error.
Failure to allocate storage is reported by throwing an exception as described in the C++ standard, 17.6.4.10 [res.on.exception.handling].
Destructors throw nothing.

Path

Generic Pathname Format
Operating System Dependent Examples (Informative)
Usage Concerns
Conversions
Argument Requirements
Composition
Iterators
Path Decomposition Table
Long Paths on Windows and the "\\?\" Namespace Prefix
Path Reference

Generic Pathname Format

Following is the formal grammar of a generic pathname.

pathname:
    root-name_opt root-directory_opt relative-path_opt

root-name:
    An operating system dependent name that identifies the starting location for absolute paths.

root-directory:
    directory-separator

relative-path:
    filename
    relative-path directory-separator
    relative-path directory-separator filename

filename:
    name
    "."
    ".."

preferred-separator:
    An operating system dependent directory separator character. May be a synonym for "/".

directory-separator:
    ""
    "" directory-separator
    preferred-separator
    preferred-separator directory-separator

	Note
	Many operating systems define a name beginning with two directory-separator characters as a root-name that identifies network or other resource locations. Some operating systems define a single letter followed by a colon as a drive specifier - a root-name identifying a specific device such as a disc drive.

Multiple successive directory-separator characters are considered to be the same as one directory-separator character.

The filename "." is considered to be a reference to the current directory. The filename ".." is considered to be a reference to the parent directory. Specific filenames may have special meanings for a particular operating system.

Operating System Dependent Examples (Informative)

Certain features are specified in this reference documentation as being operating system dependent. The following table shows the application of those specifications for operating systems that use the ISO/IEC 9945 or Windows application program interfaces (APIs). ^[1]

Feature	Section	ISO/IEC 9945 POSIX API	Windows API	Notes
`path::value_type`	`path`	`char`	`wchar_t`
`path::preferred_separator`	`path`	`'/'`	`L'\\'` (single backslash)
`path("/").is_absolute()`	`path::is_absolute`	`true`	`false`
`path("c:/").is_absolute()`	`path::is_absolute`	`false`	`true`
`path` argument disambiguation between generic format and native format	Format conversions	Not required	Not required	There is no need to distinguish between the generic format and native format for these operating systems.
`path` argument format conversion	Format conversions	No conversion performed	No conversion performed	The generic format is already acceptable to the native API of these operating systems.
`path("/cats/jane").c_str()`	Format conversions	`"/cats/jane"`	`L"/cats/jane"`	These operating systems accept the same native separator between directory names and a final file name, so no format conversion is performed. Other operating systems might require conversion.
`path("/cats/jane/").c_str()`	Format conversions	`"/cats/jane/"`	`L"/cats/jane/"`	These operating systems accept the same native separator between directory names and a final file name, so no format conversion is performed. Other operating systems might require conversion.
Format conversion by `path` native format observers	`path::native`	No conversion performed	No conversion performed	For efficiency, `path` objects are required to store pathnames in the native format regardless of operating system.
Format conversion by `path` generic format observers	`path::generic_path`	No conversion performed	Backslashes converted to slashes
`p.make_preferred()`	`path::make_preferred`	No change	Slashes converted to backslashes
Characters prohibited in filenames	filename	0x00, `'/'`	0x00-0x1F, `'"'`, `''`, `''`, `'<'`, `'>'`, `'?'`, `'\\'` (single backslash), `'/'`, `'\|'`	Many operating systems prohibit the ASCII control characters (0x00-0x1F) in filenames.
Initial imbued `path` locale	`path::imbue`, `path::codecvt`	`std::locale("")`^[2]	Implementation supplied locale using `MultiByteToWideChar` and `WideCharToMultiByte` with a codepage of `CP_ACP` if `AreFileApisANSI` is true, otherwise codepage `CP_OEMCP`.^[3]	Apple OS X®: Implementation supplied locale providing UTF-8 `codecvt` facet.^[4]

^[1] OS X® and Windows® are examples of commercially available operating systems. This information is given for the convenience of users of this document and does not constitute an endorsement by ISO or IEC of these products.

^[2] Rationale: ISO C specifies std::locale("") as "the locale-specific native environment", while ISO/IEC 9945 says it "Specifies an implementation-defined native environment."

^[3] Rationale: This is the current behavior of C and C++ standard library functions that perform file operations using narrow character strings to identify paths. Changing this behavior would be surprising and at variance with existing code, particularly where user input is involved.

^[4] Rationale: Vendor's documentation states "All BSD system functions expect their string parameters to be in UTF-8 encoding and nothing else."

Usage Concerns

Multithreading Concerns
Global Initialization and Destruction Concerns
POSIX Concerns

Multithreading Concerns

Filesystem library functions are not protected against data races. Modifying an object of a Filesystem library type that is shared between threads risks undefined behavior unless objects of that type are explicitly specified as being sharable without data races or the user supplies a locking mechanism.

Class path uses a global locale object to perform character code conversion, when needed. This means that changing the locale in one thread may affect library behavior in other threads. It is recommended to configure the path locale once, early during the application startup, before multiple threads have started using the library.

Global Initialization and Destruction Concerns

Given that class path uses a global locale, as well as some other internal objects, using the Filesystem library in global constructors and destructors (i.e. before or after main) may be problematic because the global objects do not exist. The Filesystem library attempts to mitigate the problem using various compiler and platform-specific and mechanisms, such as enforcing early initialization of the internal global objects. The currently supported configurations include MSVC on Windows and GCC and compatible compilers supporting the init_priority attribute on the target platform.

However, being non-portable, such workarounds cannot be guaranteed to work in every configuration. Portable programs should avoid using the Filesystem library in global constructors and destructors.

POSIX Concerns

Filesystem library initialization may throw an exception on POSIX systems (e.g. Linux, but not Mac OS X) that use environmental variables to determine the encoding of paths. This happens when std::locale("") throws because an environmental variable such as LANG is set to an invalid value, so it can affect any use of std::locale(""), not just the Filesystem library. Filesystem uses lazy initialization so the exception is only thrown if a valid std::locale("") is actually needed, and also so that the exception is thrown after main() starts.

Rather than waiting until a call to some Filesystem library function unexpectedly triggers the exception when it calls path::codecvt(), a program that needs be highly robust against environmental variable problems may want to preemptively call std::locale("") within a try block, catch the exception, and diagnose or repair the invalid environmental variable.

Conversions

Path Format Conversions
Character Encoding Conversions

Path Format Conversions

Member function arguments that take character sequences representing paths may use the generic pathname format or the native pathname format. Iff such arguments are in the generic format and the generic format is not acceptable to the operating system as a native path, conversion to native format shall be performed during the processing of the argument. See OS-specific examples.

Note

Depending on the operating system, there may be no unambiguous way for an implementation to always be able to distinguish between native format and generic format arguments. This is by design as it simplifies use for operating systems that do not require disambiguation. Should an implementation encounter an operating system where disambiguation is required, an implementation can define an extension to distinguish between the formats.

If the native format requires paths for regular files to be formatted differently from paths for directories, the path shall be treated as a directory path if last element is a separator, otherwise it shall be treated as a regular file path.

Generic format observer functions shall return strings formatted according to the generic pathname format using preferred-separator. See OS-specific examples.

Character Encoding Conversions

For path member function arguments that take character sequences representing paths, if the value type of the argument is not value_type, character encoding conversion to value_type shall be performed. Such conversions shall be performed by the path::codecvt() facet by default, unless another facet is specified in the operation.

The default character encoding facet is set globally for all path objects. It can be set as part of the locale object passed to the path::imbue() method.

Argument Requirements

Some of the class path member function templates have parameters with the following requirements.

Template parameters named InputIterator are required to meet the requirements for a C++ standard library InputIterator compliant iterator. The iterator's value type is required to be one of: char, wchar_t. Collectively, these types are referred to as supported path character types.

Template parameters named Source are required to be one of:

A std::basic_string, std::basic_string_view, boost::container::basic_string or boost::basic_string_view specialization with a value type of one of the supported path character types.
v3, deprecated: A container with a value type of one of the supported path character types.
A pointer into a null terminated string. The value type is required to be a supported path character type.
A C-array of supported path character type containing a null terminated string.
A boost::filesystem::directory_entry.

Composition

Class path supports a variety of methods for observing and modifying the path. Among the modifiers, there are two groups of methods for performing concatenation and appending. The important distinction between these two groups is that concatenation is performed on the path as if the path was a simple string (i.e. the concatenated characters are placed immediately at the end of the path), while appending maintains path structure and may insert a directory separator before the appended characters. The rules for inserting the separator depend on the library version and are documented in the path::append() method description.

Class path also supports operators + and / for concatenation and appending, respectively, as well as the corresponding assigning versions thereof.

p1 = "foo";
std::cout << (p + "bar") << std::endl; // outputs "foobar"
std::cout << (p / "bar") << std::endl; // outputs "foo/bar"

Iterators

Class path supports iterators iterator, const_iterator, reverse_iterator, and const_reverse_iterator to iterate over the elements of the stored pathname.

Path iterators are constant iterators satisfying the requirements of a bidirectional iterator (C++ Std, 24.1.4 Bidirectional iterators [lib.bidirectional.iterators]). The value_type of an iterator is path.

	Note
	Path iterators store their value objects internally and when dereferenced return references to those internal objects. They cannot be used with iterator adaptors such as `std::reverse_iterator` that assume references obtained by dereferencing an iterator point to objects that out-live the iterator itself.

Calling any non-const member function of a path object invalidates all iterators referring to elements of that object.

The forward traversal order is as follows:

The root-name element, if present.
The root-directory element, if present, in the generic format.

Note

The generic format is required to ensure lexicographical comparison works correctly.
Each successive filename element, if present.
[v3: Dot] [v4: Empty path], if one or more trailing non-root directory separators are present.

	Note
	Treating the last element during iteration as [v3: dot] [v4: an empty path] when there is a trailing directory separator enables lexical (i.e. syntactic) distinction between paths to directories versus paths to regular files. Such a distinction is usually irrelevant on POSIX and Windows based operating systems, but may be a requirement on other operating systems.

The backward traversal order is the reverse of forward traversal.

Path Decomposition Table

The table is generated by a program compiled with the Boost implementation. Multi-line entries indicate cases where ISO/IEC 9945 (POSIX) and Windows implementations yield different results. The top value is the ISO/IEC 9945 result and the bottom value is the Windows result.

Constructor argument	Iteration over elements	`string()`	`generic_string()`	`root_path()`	`root_name()`	`root_directory()`	`relative_path()`	`parent_path()`	`filename()`
empty	empty	empty	empty	empty	empty	empty	empty	empty	empty
`.`	`.`	`.`	`.`	empty	empty	empty	`.`	empty	`.`
`..`	`..`	`..`	`..`	empty	empty	empty	`..`	empty	`..`
`foo`	`foo`	`foo`	`foo`	empty	empty	empty	`foo`	empty	`foo`
`/`	`/`	`/`	`/`	`/`	empty	`/`	empty	empty	`/`
`/foo`	`/`, `foo`	`/foo`	`/foo`	`/`	empty	`/`	`foo`	`/`	`foo`
`foo/`	`foo`, `.`	`foo/`	`foo/`	empty	empty	empty	`foo/`	`foo`	`.`
`foo`	`/`, `foo`, `.`	`foo`	`foo`	`/`	empty	`/`	`foo/`	`/foo`	`.`
`foo/bar`	`foo`, `bar`	`foo/bar`	`foo/bar`	empty	empty	empty	`foo/bar`	`foo`	`bar`
`/foo/bar`	`/`, `foo`, `bar`	`/foo/bar`	`/foo/bar`	`/`	empty	`/`	`foo/bar`	`/foo`	`bar`
`//net`	`//net`	`//net`	`//net`	`//net`	`//net`	empty	empty	empty	`//net`
`//net/foo`	`//net`, `/`, `foo`	`//net/foo`	`//net/foo`	`//net/`	`//net`	`/`	`foo`	`//net/`	`foo`
`///foo///`	`/`, `foo`, `.`	`///foo///`	`///foo///`	`/`	empty	`/`	`foo///`	`///foo`	`.`
`///foo///bar`	`/`, `foo`, `bar`	`///foo///bar`	`///foo///bar`	`/`	empty	`/`	`foo///bar`	`///foo`	`bar`
`/.`	`/`, `.`	`/.`	`/.`	`/`	empty	`/`	`.`	`/`	`.`
`./`	`.`, `.`	`./`	`./`	empty	empty	empty	`./`	`.`	`.`
`/..`	`/`, `..`	`/..`	`/..`	`/`	empty	`/`	`..`	`/`	`..`
`../`	`..`, `.`	`../`	`../`	empty	empty	empty	`../`	`..`	`.`
`foo/.`	`foo`, `.`	`foo/.`	`foo/.`	empty	empty	empty	`foo/.`	`foo`	`.`
`foo/..`	`foo`, `..`	`foo/..`	`foo/..`	empty	empty	empty	`foo/..`	`foo`	`..`
`foo/./`	`foo`, `.`, `.`	`foo/./`	`foo/./`	empty	empty	empty	`foo/./`	`foo/.`	`.`
`foo/./bar`	`foo`, `.`, `bar`	`foo/./bar`	`foo/./bar`	empty	empty	empty	`foo/./bar`	`foo/.`	`bar`
`foo/..`	`foo`, `..`	`foo/..`	`foo/..`	empty	empty	empty	`foo/..`	`foo`	`..`
`foo/../`	`foo`, `..`, `.`	`foo/../`	`foo/../`	empty	empty	empty	`foo/../`	`foo/..`	`.`
`foo/../bar`	`foo`, `..`, `bar`	`foo/../bar`	`foo/../bar`	empty	empty	empty	`foo/../bar`	`foo/..`	`bar`
`c:`	`c:`	`c:`	`c:`	empty `c:`	empty `c:`	empty	`c:` empty	empty	`c:`
`c:/`	`c:`, `.` `c:`, `/`	`c:/`	`c:/`	empty `c:/`	empty `c:`	empty `/`	`c:/` empty	`c:`	`.` `/`
`c:foo`	`c:foo` `c:`, `foo`	`c:foo`	`c:foo`	empty `c:`	empty `c:`	empty	`c:foo` `foo`	empty `c:`	`c:foo` `foo`
`c:/foo`	`c:`, `foo` `c:`, `/`, `foo`	`c:/foo`	`c:/foo`	empty `c:/`	empty `c:`	empty `/`	`c:/foo` `foo`	`c:` `c:/`	`foo`
`c:foo/`	`c:foo`, `.` `c:`, `foo`, `.`	`c:foo/`	`c:foo/`	empty `c:`	empty `c:`	empty	`c:foo/` `foo/`	`c:foo`	`.`
`c:foo`	`c:`, `foo`, `.` `c:`, `/`, `foo`, `.`	`c:foo`	`c:foo`	empty `c:/`	empty `c:`	empty `/`	`c:foo` `foo/`	`c:/foo`	`.`
`c:/foo/bar`	`c:`, `foo`, `bar` `c:`, `/`, `foo`, `bar`	`c:/foo/bar`	`c:/foo/bar`	empty `c:/`	empty `c:`	empty `/`	`c:/foo/bar` `foo/bar`	`c:/foo`	`bar`
`prn:`	`prn:`	`prn:`	`prn:`	empty `prn:`	empty `prn:`	empty	`prn:` empty	empty	`prn:`
`c:\`	`c:\` `c:`, `/`	`c:\`	`c:\` `c:/`	empty `c:\`	empty `c:`	empty `\`	`c:\` empty	empty `c:`	`c:\` `\`
`c:foo`	`c:foo` `c:`, `foo`	`c:foo`	`c:foo`	empty `c:`	empty `c:`	empty	`c:foo` `foo`	empty `c:`	`c:foo` `foo`
`c:\foo`	`c:\foo` `c:`, `/`, `foo`	`c:\foo`	`c:\foo` `c:/foo`	empty `c:\`	empty `c:`	empty `\`	`c:\foo` `foo`	empty `c:\`	`c:\foo` `foo`
`c:foo\`	`c:foo\` `c:`, `foo`, `.`	`c:foo\`	`c:foo\` `c:foo/`	empty `c:`	empty `c:`	empty	`c:foo\` `foo\`	empty `c:foo`	`c:foo\` `.`
`c:\foo\`	`c:\foo\` `c:`, `/`, `foo`, `.`	`c:\foo\`	`c:\foo\` `c:foo`	empty `c:\`	empty `c:`	empty `\`	`c:\foo\` `foo\`	empty `c:\foo`	`c:\foo\` `.`
`c:\foo/`	`c:\foo`, `.` `c:`, `/`, `foo`, `.`	`c:\foo/`	`c:\foo/` `c:foo`	empty `c:\`	empty `c:`	empty `\`	`c:\foo/` `foo/`	`c:\foo`	`.`
`c:/foo\bar`	`c:`, `foo\bar` `c:`, `/`, `foo`, `bar`	`c:/foo\bar`	`c:/foo\bar` `c:/foo/bar`	empty `c:/`	empty `c:`	empty `/`	`c:/foo\bar` `foo\bar`	`c:` `c:/foo`	`foo\bar` `bar`

Long Paths on Windows and the "\\?\" Namespace Prefix

Cautions for Paths with Namespace Prefixes

The Microsoft Windows "Maximum Path Length Limitation" specifies:

In the Windows API (with some exceptions ...), the maximum length for a path is MAX_PATH, which is defined as 260 characters.

The Windows API has many functions that also have Unicode versions to permit an extended-length path for a maximum total path length of 32,767 characters. ... To specify an extended-length path, use the "\\?\" prefix. For example, "\\?\D:\very long path". [C++ string literals require backslashes be doubled, of course.]

Because most Boost.Filesystem operational functions just pass the contents of a class path object to the Windows API, they do work with the extended-length prefixes. But some won't work, because of the limitations imposed by Windows.

Effectively, the "\\?\" prefix informs the underlying Windows API that the path identifies an object in the Win32 filesystem namespace and disables most of the internal path processing, including normalization, by the Windows API. While it lifts the length limitation, this imposes a number of other restrictions on the acceptable paths that are listed in the section below. There are a number of other prefixes that have different special meanings, such as "\\.\" (a local device namespace prefix) and "\??\" (NT object namespace prefix). Note that UNC paths can be extended with the prefixes by referring to a special "UNC" device. For example, "\\server\share" can be extended as "\\?\UNC\server\share".

In terms of Boost.Filesystem, the namespace prefixes are considered as parts of the path's root name. For example, the root name of "\\?\c:\foo" is "\\?\c:". This interpretation is chosen to allow root paths to be iterable, that is you can list the contents of the "\\?\c:\" directory, provided that drive C: exists and you have the necessary permissions.

	Note
	You can't list the contents of "\\?\" as such path does not exist.

Cautions for Paths with Namespace Prefixes

Individual components of a path are still are limited to whatever is supported for the particular filesystem, commonly 255 characters.
Only backslashes are acceptable as directory separators. Slashes are not treated as separators.
All paths must be absolute and must not contain "." or ".." components.
Once an absolute path grows beyond 260 characters, it is essentially poisoned and all operations must use extended-length prefixes. So even a simple operation like create_directory("a") will fail if the absolute path of the resulting directory would exceed 260 characters.
Certain Boost.Filesystem functions that decompose their argument path and then work on individual relative directories or files will not work properly with namespace prefix paths.

Path Reference

Header <boost/filesystem/path.hpp>

Header <boost/filesystem/path.hpp>

namespace boost {
  namespace filesystem {
    class path;

    // path appending
    path operator/(path, path const &);
    template<typename Source> path operator/(path, Source const &);

    // path comparison
    bool operator==(path const &, path const &);
    template<typename Source> bool operator==(path const &, Source const &);
    template<typename Source> bool operator==(Source const &, path const &);
    bool operator!=(path const &, path const &);
    template<typename Source> bool operator!=(path const &, Source const &);
    template<typename Source> bool operator!=(Source const &, path const &);
    bool operator<(path const &, path const &);
    template<typename Source> bool operator<(path const &, Source const &);
    template<typename Source> bool operator<(Source const &, path const &);
    bool operator>(path const &, path const &);
    template<typename Source> bool operator>(path const &, Source const &);
    template<typename Source> bool operator>(Source const &, path const &);
    bool operator<=(path const &, path const &);
    template<typename Source> bool operator<=(path const &, Source const &);
    template<typename Source> bool operator<=(Source const &, path const &);
    bool operator>=(path const &, path const &);
    template<typename Source> bool operator>=(path const &, Source const &);
    template<typename Source> bool operator>=(Source const &, path const &);
    bool lexicographical_compare(path::const_iterator, path::const_iterator, 
                                 path::const_iterator, path::const_iterator);

    // path hashing
    std::size_t hash_value(path const &);

    // path swapping
    void swap(path &, path &);

    // path I/O
    template<typename Char, typename Traits> 
      std::basic_ostream< Char, Traits > & 
      operator<<(std::basic_ostream< Char, Traits > &, path const &);
    template<typename Char, typename Traits> 
      std::basic_istream< Char, Traits > & 
      operator>>(std::basic_istream< Char, Traits > &, path &);

    // path name checks
    bool portable_posix_name(std::string const &);
    bool windows_name(std::string const &);
    bool portable_name(std::string const &);
    bool portable_directory_name(std::string const &);
    bool portable_file_name(std::string const &);
    bool native(std::string const &);
  }
}

path appending

path operator/(path lhs, path const & rhs);

See Also: append.

Returns:

lhs.append(rhs).

template<typename Source> path operator/(path lhs, Source const & rhs);

See Also: append.

Returns:

lhs.append(rhs).

path comparison

bool operator==(path const & lhs, path const & rhs);

See Also: compare.

Returns:

lhs.compare(rhs) == 0.

template<typename Source> 
  bool operator==(path const & lhs, Source const & rhs);

See Also: compare.

Returns:

lhs.compare(rhs) == 0.

template<typename Source> 
  bool operator==(Source const & lhs, path const & rhs);

See Also: compare.

Returns:

rhs.compare(lhs) == 0.

bool operator!=(path const & lhs, path const & rhs);

See Also: compare.

Returns:

lhs.compare(rhs) != 0.

template<typename Source> 
  bool operator!=(path const & lhs, Source const & rhs);

See Also: compare.

Returns:

lhs.compare(rhs) != 0.

template<typename Source> 
  bool operator!=(Source const & lhs, path const & rhs);

See Also: compare.

Returns:

rhs.compare(lhs) != 0.

bool operator<(path const & lhs, path const & rhs);

See Also: compare.

Returns:

lhs.compare(rhs) < 0.

template<typename Source> bool operator<(path const & lhs, Source const & rhs);

See Also: compare.

Returns:

lhs.compare(rhs) < 0.

template<typename Source> bool operator<(Source const & lhs, path const & rhs);

See Also: compare.

Returns:

rhs.compare(lhs) > 0.

bool operator>(path const & lhs, path const & rhs);

See Also: compare.

Returns:

lhs.compare(rhs) > 0.

template<typename Source> bool operator>(path const & lhs, Source const & rhs);

See Also: compare.

Returns:

lhs.compare(rhs) > 0.

template<typename Source> bool operator>(Source const & lhs, path const & rhs);

See Also: compare.

Returns:

rhs.compare(lhs) < 0.

bool operator<=(path const & lhs, path const & rhs);

See Also: compare.

Returns:

lhs.compare(rhs) <= 0.

template<typename Source> 
  bool operator<=(path const & lhs, Source const & rhs);

See Also: compare.

Returns:

lhs.compare(rhs) <= 0.

template<typename Source> 
  bool operator<=(Source const & lhs, path const & rhs);

See Also: compare.

Returns:

rhs.compare(lhs) >= 0.

bool operator>=(path const & lhs, path const & rhs);

See Also: compare.

Returns:

lhs.compare(rhs) >= 0.

template<typename Source> 
  bool operator>=(path const & lhs, Source const & rhs);

See Also: compare.

Returns:

lhs.compare(rhs) >= 0.

template<typename Source> 
  bool operator>=(Source const & lhs, path const & rhs);

See Also: compare.

Returns:

lhs.compare(rhs) <= 0.

bool lexicographical_compare(path::const_iterator first1, 
                             path::const_iterator last1, 
                             path::const_iterator first2, 
                             path::const_iterator last2);

Tests whether the two sequences of path elements are lexicographically equal.

Note

If two sequences have the same number of elements and their corresponding elements are equivalent, then neither sequence is lexicographically less than the other. If one sequence is a prefix of the other, then the shorter sequence is lexicographically less than the longer sequence. Otherwise, the lexicographical comparison of the sequences yields the same result as the comparison of the first corresponding pair of elements that are not equivalent.

	Note
	A `path`-aware `lexicographical_compare` algorithm is provided for historical reasons.

Parameters:

`first1`	Beginning of the first sequence.
`last1`	End of the first sequence.
`first2`	Beginning of the second sequence.
`last2`	End of the second sequence.

Returns:

true if the sequence of native() strings for the elements defined by the half-open range [first1, last1) is lexicographically less than the sequence of native() strings for the elements defined by the half-open range [first2, last2). Returns false otherwise.

path hashing

```
std::size_t hash_value(path const & p);
```
Computes a hash value for the path.
If for two paths, p1 == p2 then hash_value(p1) == hash_value(p2). The opposite is not necessarily true. This allows paths to be used with Boost.Hash.

Parameters:

p

The path to compute hash for.

Returns:

A hash value for the path p.

path swapping

```
void swap(path & lhs, path & rhs);
```
Effects: As if lhs.swap(rhs).

See Also: swap.

path I/O

```
template<typename Char, typename Traits> 
  std::basic_ostream< Char, Traits > & 
  operator<<(std::basic_ostream< Char, Traits > & os, path const & p);
```
Outputs path representation into an output stream.
Effects:

Insert characters into os as follows:
- A double-quote.
- Each character in p.string< std::basic_string< Char > >(). If the character to be inserted is equal to the escape character '&' or a double-quote, as determined by operator==, first insert the escape character.
- A double-quote.
Note

The effects ensure that the path can safely round-trip with operator>>, even if the path contains spaces, double-quotes and '&' characters.

Parameters:

os

Output stream.

p

Path to output.

Returns:

os.
```
template<typename Char, typename Traits> 
  std::basic_istream< Char, Traits > & 
  operator>>(std::basic_istream< Char, Traits > & is, path & p);
```
Reads path representation from an input stream.
Effects:

Extract characters from is as follows:
- If the first character that would be extracted is equal to double-quote, as determined by operator==, then:
  - Discard the initial double-quote.
  - Save the value and then turn off the skipws flag in is.
  - p.clear().
  - Until an unescaped double-quote character is reached or is.not_good(), extract characters from is and concatenate them to p, except that if an escape character '&' is reached, ignore it and concatenate the next character to p.
  - Discard the final double-quote character.
  - Restore the skipws flag to its original value in is.
- Otherwise, for str being a string of type std::basic_string< Char >, is >> str; p = str;.
Note

The effects ensure that the path can safely round-trip with operator<<, even if the original path contained spaces, double-quotes and '&' characters.

Parameters:

is

Input stream.

p

Path to read into.

Returns:

is.

path name checks

bool portable_posix_name(std::string const & name);

Tests if the string can be portably used as a name on POSIX systems.

Parameters:

name

String to test.

Returns:

true if !name.empty() and name contains only the characters specified in Portable Filename Character Set rules as defined in by POSIX (https://pubs.opengroup.org/onlinepubs/007904975/basedefs/xbd_chap03.html).

The allowed characters are "0-9", "a-z", "A-Z", ".", "_", and "-".

bool windows_name(std::string const & name);

Tests if the string can be used as a name on Windows.

Parameters:

name

String to test.

Returns:

true if

!name.empty(), and
name contains only the characters specified by the Windows platform SDK as valid regardless of the file system, and
name is "." or ".." or does not end with a trailing space or period.

The allowed characters are anything except 0x0-0x1F, "<", ">", ":", """, "/", "\", and "|".

bool portable_name(std::string const & name);

Tests if the string can be used as a name on most systems.

Parameters:

name

String to test.

Returns:

true if

windows_name(name), and
portable_posix_name(name), and
name is "." or "..", or the first character of name is not a period or hyphen.

```
bool portable_directory_name(std::string const & name);
```
Tests if the string can be used as a directory name on most systems.

Parameters:

name

String to test.

Returns:

true if portable_name(name) and name is "." or ".." or contains no periods.
```
bool portable_file_name(std::string const & name);
```
Tests if the string can be used as a file name on most systems.

Parameters:

name

String to test.

Returns:

portable_name(name), and any period is followed by one to three additional non-period characters.
```
bool native(std::string const & name);
```
Tests if the string can be considered as a valid name for the native file system.

Note

May return true for some names not considered valid by the operating system under all conditions (particularly on operating systems which support multiple file systems.)

Returns:

Returns true for names considered valid by the operating system's native file systems. The actual criteria for validity are implementation-defined.

Filesystem Operations

Filesystem Operations Reference
Directory Iteration Reference
File Status

Operational functions query or modify files, including directories, in external storage.

Operational functions access a file by resolving an object of class path to a particular file in a file hierarchy. The path is resolved as if by the ISO/IEC 9945 Pathname Resolution mechanism.

Filesystem Operations Reference

Header <boost/filesystem/operations.hpp>

Header <boost/filesystem/operations.hpp>

namespace boost {
  namespace filesystem {
    struct space_info;

    enum copy_options;

    // Status Query Functions
    file_status status(path const &, system::error_code &);
    file_status status(path const &);
    file_status symlink_status(path const &, system::error_code &);
    file_status symlink_status(path const &);
    bool exists(path const &, system::error_code &);
    bool exists(path const &);
    bool is_regular_file(path const &, system::error_code &);
    bool is_regular_file(path const &);
    bool is_directory(path const &, system::error_code &);
    bool is_directory(path const &);
    bool is_symlink(path const &, system::error_code &);
    bool is_symlink(path const &);
    bool is_block_file(path const &, system::error_code &);
    bool is_block_file(path const &);
    bool is_character_file(path const &, system::error_code &);
    bool is_character_file(path const &);
    bool is_fifo(path const &, system::error_code &);
    bool is_fifo(path const &);
    bool is_socket(path const &, system::error_code &);
    bool is_socket(path const &);
    bool is_reparse_file(path const &, system::error_code &);
    bool is_reparse_file(path const &);
    bool is_other(path const &, system::error_code &);
    bool is_other(path const &);
    bool is_empty(path const &, system::error_code &);
    bool is_empty(path const &);

    // File Attributes Querying and Manipulation
    boost::uintmax_t file_size(path const &, system::error_code &);
    boost::uintmax_t file_size(path const &);
    void resize_file(path const &, uintmax_t, system::error_code &);
    void resize_file(path const &, uintmax_t);
    boost::uintmax_t hard_link_count(path const &, system::error_code &);
    boost::uintmax_t hard_link_count(path const &);
    std::time_t creation_time(path const &, system::error_code &);
    std::time_t creation_time(path const &);
    std::time_t last_write_time(path const &, system::error_code &);
    std::time_t last_write_time(path const &);
    void last_write_time(path const &, const std::time_t, 
                         system::error_code &);
    void last_write_time(path const &, const std::time_t);
    void permissions(path const &, perms, system::error_code &);
    void permissions(path const &, perms);

    // Path Manipulation Functions
    path initial_path(system::error_code &);
    path initial_path();
    path current_path(system::error_code &);
    path current_path();
    void current_path(path const &, system::error_code &);
    void current_path(path const &);
    path temp_directory_path(system::error_code &);
    path temp_directory_path();
    path unique_path(path const &, system::error_code &);
    path unique_path(system::error_code &);
    path unique_path(path const & = "%%%%-%%%%-%%%%-%%%%");
    path relative(path const &, path const &, system::error_code &);
    path relative(path const &, system::error_code &);
    path relative(path const &, path const & = current_path());
    path system_complete(path const &, system::error_code &);
    path system_complete(path const &);
    path absolute(path const &, path const &, system::error_code &);
    path absolute(path const &, system::error_code &);
    path absolute(path const &, path const & = current_path());
    path canonical(path const &, path const &, system::error_code &);
    path canonical(path const &, system::error_code &);
    path canonical(path const &, path const & = current_path());
    path weakly_canonical(path const &, path const &, system::error_code &);
    path weakly_canonical(path const &, system::error_code &);
    path weakly_canonical(path const &, path const & = current_path());

    // Operational Functions
    void copy(path const &, path const &, copy_options, system::error_code &);
    void copy(path const &, path const &, system::error_code &);
    void copy(path const &, path const &, copy_options);
    void copy(path const &, path const &);
    bool copy_file(path const &, path const &, copy_options, 
                   system::error_code &);
    bool copy_file(path const &, path const &, system::error_code &);
    bool copy_file(path const &, path const &, copy_options);
    bool copy_file(path const &, path const &);
    void copy_symlink(path const &, path const &, system::error_code &);
    void copy_symlink(path const &, path const &);
    bool create_directories(path const &, system::error_code &);
    bool create_directories(path const &);
    bool create_directory(path const &, path const &, system::error_code &);
    bool create_directory(path const &, system::error_code &);
    bool create_directory(path const &, path const &);
    bool create_directory(path const &);
    void create_directory_symlink(path const &, path const &, 
                                  system::error_code &);
    void create_directory_symlink(path const &, path const &);
    void create_hard_link(path const &, path const &, system::error_code &);
    void create_hard_link(path const &, path const &);
    void create_symlink(path const &, path const &, system::error_code &);
    void create_symlink(path const &, path const &);
    path read_symlink(path const &, system::error_code &);
    path read_symlink(path const &);
    bool remove(path const &, system::error_code &);
    bool remove(path const &);
    boost::uintmax_t remove_all(path const &, system::error_code &);
    boost::uintmax_t remove_all(path const &);
    void rename(path const &, path const &, system::error_code &);
    void rename(path const &, path const &);
    space_info space(path const &, system::error_code &);
    space_info space(path const &);
    bool equivalent(path const &, path const &, system::error_code &);
    bool equivalent(path const &, path const &);
  }
}

Status Query Functions

file_status status(path const & p, system::error_code & ec);
file_status status(path const & p);

Returns file_status for the file identified by p, following symbolic link resolution.

Effects:

Determines the attributes and access permissions of the file p resolves to, as if by ISO/IEC 9945 stat().

Note

If p resolves to a symbolic link, the behavior is as if the operation restarts with p being equal to the contents of the symbolic link. There may be a platform-specific limit on the number of symbolic link resolutions performed or other conditions for detecting symbolic link cycles. If such limit or conditions are reached, the operation returns with an error indication. Otherwise, if p does not resolve to a symbolic link, the effects are equivalent to symlink_status().

Error Reporting:

The overload that is not taking the ec argument throws filesystem_error only if the operation would have returned file_status(status_error). Other unsuccessful cases are indicated with the file_status returned normally.

The overload that takes the ec argument sets ec to a non-empty error_code if the operation fails to determine the file attributes and access permissions (e.g. if the path does not resolve to an existing file).

See Also: symlink_status.

Parameters:

`p`	Path to the file to obtain information about.
`ec`	Error code returned in case of failure.

Returns:

If symbolic link resolution in p succeeds (i.e. produces a path that does not resolve to a symbolic link), returns symlink_status() on the resolved path. Otherwise, returns file_status(status_error).

file_status symlink_status(path const & p, system::error_code & ec);
file_status symlink_status(path const & p);

Returns file_status for the file identified by p.

Effects:

Determines the attributes and access permissions of the file p resolves to, as if by ISO/IEC 9945 lstat(). If determining succeeded:

Based on the determined attributes, select a file_type enum value ft as follows:

If the attributes indicate a symbolic link, as if by ISO/IEC 9945 S_IFLNK(), then ft = symlink_file.
If the attributes indicate a regular file, as if by ISO/IEC 9945 S_ISREG(), then ft = regular_file.
Otherwise, if the attributes indicate a directory, as if by ISO/IEC 9945 S_ISDIR(), then ft = directory_file.
Otherwise, if the attributes indicate a block special file, as if by ISO/IEC 9945 S_ISBLK(), then ft = block_file.
Otherwise, if the attributes indicate a character special file, as if by ISO/IEC 9945 S_ISCHR(), then ft = character_file.
Otherwise, if the attributes indicate a fifo or pipe file, as if by ISO/IEC 9945 S_ISFIFO(), then ft = fifo_file.
Otherwise, if the attributes indicate a socket, as if by ISO/IEC 9945 S_ISSOCK(), then ft = socket_file.
Otherwise, on Windows, if the attributes indicate a reparse point, then ft = reparse_file.
Otherwise, ft = type_unknown.

	Note
	`regular_file` implies appropriate `<fstream>` operations would succeed, assuming no hardware, permission, access, or file system race errors. Lack of `regular_file` does not necessarily imply `<fstream>` operations would fail on a directory. `directory_file` implies `directory_iterator(p)` would succeed.

Note

On Windows, symbolic links are implemented as reparse points. The library recognizes this kind of reparse points, as well as junction reparse points, and reports such reparse points as symlink_file. reparse_file file type is reported for reparse points of unsupported types or when the reparse point doesn't fit into one of the more specialized categories. For ISO/IEC 9945, reparse points are not supported and never reported.

Based on the determined file access permissions, compute perms value prm as a combination of the following bits:

Permission	`perms` bit	ISO/IEC 9945 equivalent bit
Read by owner	`owner_read`	`S_IRUSR`
Write by owner	`owner_write`	`S_IWUSR`
Execute by owner	`owner_exe`	`S_IXUSR`
Read by group	`group_read`	`S_IRGRP`
Write by group	`group_write`	`S_IWGRP`
Execute by group	`group_exe`	`S_IXGRP`
Read by others	`others_read`	`S_IROTH`
Write by others	`others_write`	`S_IWOTH`
Execute by others	`others_exe`	`S_IXOTH`
Set-user-ID on execute	`set_uid_on_exe`	`S_ISUID`
Set-group-ID on execute	`set_gid_on_exe`	`S_ISGID`
Sticky bit	`sticky_bit`	`S_ISVTX`

	Note
	Support and semantics of the sticky bit may vary across platforms.

	Note
	On Windows, some permissions may not be reported accurately. Currently, all files are reported as readable by all users. Files not marked as read-only are reported as writable for all users. For certain well known executable file formats, based on the file name, the library reports executable permission for all users. The library does not use ACL to produce or verify these permissions.

The returned object is constructed from ft and prm as if by calling file_status(ft, prm).

Otherwise, if determining file attributes failed:

If the specific error indicates that p cannot be resolved because some element of the path does not exist, return file_status(file_not_found).

	Note
	ISO/IEC 9945 errors that indicate this are `ENOENT` or `ENOTDIR`. Windows equivalents include `ERROR_FILE_NOT_FOUND`, `ERROR_PATH_NOT_FOUND`, `ERROR_INVALID_NAME`, `ERROR_INVALID_PARAMETER`, `ERROR_BAD_PATHNAME`, and `ERROR_BAD_NETPATH`. This list of error codes may not be exhaustive.

Otherwise, if the specific error indicates that p can be resolved but the attributes cannot be determined, return file_status(type_unknown).

Note

For example, Windows ERROR_SHARING_VIOLATION errors. For ISO/IEC 9945, the case never arises.
Otherwise, return file_status(status_error).

	Note
	These semantics distinguish between `p` being known not to exist, `p` existing but not being able to determine its attributes, and there being an error that prevents even knowing if `p` exists. These distinctions are important to some use cases.

Error Reporting:

Parameters:

`p`	Path to the file to obtain information about.
`ec`	Error code returned in case of failure.

Returns:

The file_status object constructed as described above.

```
bool exists(path const & p, system::error_code & ec);
bool exists(path const & p);
```
Checks if file exists.
Effects: Determines file_status of p, as if by status(p, ec).

Parameters:

p

The path to query.

ec

The error code to set on failure.

Returns:

true if status(p, ec).type() is not status_error or file_not_found, false otherwise.
```
bool is_regular_file(path const & p, system::error_code & ec);
bool is_regular_file(path const & p);
```
Checks if file is a regular file.
Effects: Determines file_status of p, as if by status(p, ec).

Parameters:

p

The path to query.

ec

The error code to set on failure.

Returns:

true if status(p, ec).type() == regular_file, false otherwise.
```
bool is_directory(path const & p, system::error_code & ec);
bool is_directory(path const & p);
```
Checks if file is a directory.
Effects: Determines file_status of p, as if by status(p, ec).

Parameters:

p

The path to query.

ec

The error code to set on failure.

Returns:

true if status(p, ec).type() == directory_file, false otherwise.
```
bool is_symlink(path const & p, system::error_code & ec);
bool is_symlink(path const & p);
```
Checks if file is a symlink.
Effects: Determines file_status of p, as if by symlink_status(p, ec).

Parameters:

p

The path to query.

ec

The error code to set on failure.

Returns:

true if symlink_status(p, ec).type() == symlink_file, false otherwise.
```
bool is_block_file(path const & p, system::error_code & ec);
bool is_block_file(path const & p);
```
Checks if file is a block special file.
Effects: Determines file_status of p, as if by status(p, ec).

Parameters:

p

The path to query.

ec

The error code to set on failure.

Returns:

true if status(p, ec).type() == block_file, false otherwise.
```
bool is_character_file(path const & p, system::error_code & ec);
bool is_character_file(path const & p);
```
Checks if file is a character special file.
Effects: Determines file_status of p, as if by status(p, ec).

Parameters:

p

The path to query.

ec

The error code to set on failure.

Returns:

true if status(p, ec).type() == character_file, false otherwise.
```
bool is_fifo(path const & p, system::error_code & ec);
bool is_fifo(path const & p);
```
Checks if file is a FIFO or pipe file.
Effects: Determines file_status of p, as if by status(p, ec).

Parameters:

p

The path to query.

ec

The error code to set on failure.

Returns:

true if status(p, ec).type() == fifo_file, false otherwise.
```
bool is_socket(path const & p, system::error_code & ec);
bool is_socket(path const & p);
```
Checks if file is a socket file.
Effects: Determines file_status of p, as if by status(p, ec).

Parameters:

p

The path to query.

ec

The error code to set on failure.

Returns:

true if status(p, ec).type() == socket_file, false otherwise.
```
bool is_reparse_file(path const & p, system::error_code & ec);
bool is_reparse_file(path const & p);
```
Checks if file is a reparse point file.
Effects: Determines file_status of p, as if by symlink_status(p, ec).

Parameters:

p

The path to query.

ec

The error code to set on failure.

Returns:

true if symlink_status(p, ec).type() == reparse_file, false otherwise.
```
bool is_other(path const & p, system::error_code & ec);
bool is_other(path const & p);
```
Checks if file is an other type.
Effects: Determines file_status s of p, as if by s = status(p, ec).

Parameters:

p

The path to query.

ec

The error code to set on failure.

Returns:

true if exists(s) && !is_regular_file(s) && !is_directory(s), false otherwise.

bool is_empty(path const & p, system::error_code & ec);
bool is_empty(path const & p);

Checks if file or directory is empty.

Parameters:

`p`	The path to query.
`ec`	The error code to set on failure.

Returns:

is_directory(p, ec) ? directory_iterator(p, ec) == directory_iterator() : file_size(p, ec) == 0.

File Attributes Querying and Manipulation

boost::uintmax_t file_size(path const & p, system::error_code & ec);
boost::uintmax_t file_size(path const & p);

Returns the file size.

Parameters:

`p`	The path to the file.
`ec`	The error code to set on failure.

Returns:

If exists(p) && is_regular_file(p), the size in bytes of the file p resolves to, determined as if by the value of the ISO/IEC 9945 stat structure member st_size obtained as if by ISO/IEC 9945 stat(). Otherwise, indicates error and the overload taking ec returns static_cast<uintmax_t>(-1).

```
void resize_file(path const & p, uintmax_t size, system::error_code & ec);
void resize_file(path const & p, uintmax_t size);
```
Resizes a file.
Effects:

Sets the size of the file to which p resolves to size, as if by ISO/IEC 9945 truncate().

Parameters:

p

The path to the file.

size

The new size of the file.

ec

The error code to set on failure.

Postconditions:

file_size() == size is true.

boost::uintmax_t hard_link_count(path const & p, system::error_code & ec);
boost::uintmax_t hard_link_count(path const & p);

Returns the number of hard links.

Parameters:

`p`	The path to the file.
`ec`	The error code to set on failure.

Returns:

The number of hard links for p, determined as if by the value of the ISO/IEC 9945 stat structure member st_nlink obtained as if by ISO/IEC 9945 stat(). Otherwise, indicates error and the overload taking ec returns static_cast<uintmax_t>(-1).

std::time_t creation_time(path const & p, system::error_code & ec);
std::time_t creation_time(path const & p);

Returns the creation time of a file.

	Note
	Not all platforms support querying file creation time. Where not supported, the operation will fail with `errc::function_not_supported` error code.

Parameters:

`p`	The path to the file.
`ec`	The error code to set on failure.

Returns:

The time of creation of the file to which p resolves. In case of error, the overload taking ec returns std::numeric_limits<std::time_t>::min().

std::time_t last_write_time(path const & p, system::error_code & ec);
std::time_t last_write_time(path const & p);

Returns the last write time of a file.

Parameters:

`p`	The path to the file.
`ec`	The error code to set on failure.

Returns:

The time of last data modification of p, determined as if by the value of the ISO/IEC 9945 stat structure member st_mtime obtained as if by ISO/IEC 9945 stat(). In case of error, the overload taking ec returns std::numeric_limits<std::time_t>::min().

```
void last_write_time(path const & p, const std::time_t new_time, 
                     system::error_code & ec);
void last_write_time(path const & p, const std::time_t new_time);
```
Sets the last write time of a file.
Effects:

Sets the time of last data modification of the file resolved to by p to new_time, as if by ISO/IEC 9945 stat() followed by ISO/IEC 9945 utime().

Note

A postcondition of last_write_time(p) == new_time is not specified since it might not hold for file systems with coarse time granularity.

Parameters:

p

The path to the file.

new_time

The new last write time.

ec

The error code to set on failure.

void permissions(path const & p, perms prms, system::error_code & ec);
void permissions(path const & p, perms prms);

Applies file access permissions.

Effects:

Applies the effective permission bits from prms to the file p resolves to, as if by ISO/IEC 9945 fchmodat(). The effective permission bits are determined as specified by the following table.

Bits present in `prms`	Effective bits applied
Neither `add_perms` nor `remove_perms`	`prms & perms_mask`
`add_perms`	`status(p).permissions() \| (prms & perms_mask)`
`remove_perms`	`status(p).permissions() & ~(prms & perms_mask)`

	Note
	Conceptually permissions are viewed as bits, but the actual implementation may use some other mechanism.

Parameters:

`p`	The path to the file.
`prms`	The permissions to apply.
`ec`	The error code to set on failure.

Requires:

!((prms & add_perms) && (prms & remove_perms)).

Path Manipulation Functions

path initial_path(system::error_code & ec);
path initial_path();

Returns current_path() as of the first call to initial_path.

	Note
	This function is not thread safe and may return an undesirable result if called subsequent to a change to the current directory. These problems can be avoided by calling `initial_path` immediately on entry to `main()`.

Parameters:

`ec`	The error code to set on failure.

Returns:

The current working directory path, as it was on the first call to initial_path. If an error occurs, the overload taking ec returns an empty path.

path current_path(system::error_code & ec);

Returns the current working directory path.

	Note
	The `current_path()` name was chosen to emphasize that the return is a path, not just a single directory name.

	Note
	The current path as returned by many operating systems is a dangerous global variable. It may be changed unexpectedly by a third-party or system library functions, or by another thread.

Parameters:

`ec`	The error code to set on failure.

Returns:

The current working directory path, as if by ISO/IEC 9945 getcwd(). is_absolute() is true for the returned path. An empty path is returned in case of error.

```
path current_path();
```
Returns the current working directory path.

Note

The current_path() name was chosen to emphasize that the return is a path, not just a single directory name.

Note

The current path as returned by many operating systems is a dangerous global variable. It may be changed unexpectedly by a third-party or system library functions, or by another thread.

Returns:

The current working directory path, as if by ISO/IEC 9945 getcwd(). is_absolute() is true for the returned path.
```
void current_path(path const & p, system::error_code & ec);
```
Sets the current path.
Effects: Establishes the postcondition, as if by ISO/IEC 9945 chdir().

Note

The current path as returned by many operating systems is a dangerous global variable. It may be changed unexpectedly by a third-party or system library functions, or by another thread.

Parameters:

p

The path to set as the current path.

ec

The error code to set on failure.

Postconditions:

equivalent(p, current_path(ec)) is true.
```
void current_path(path const & p);
```
Sets the current path.
Effects: Establishes the postcondition, as if by ISO/IEC 9945 chdir().

Note

The current path as returned by many operating systems is a dangerous global variable. It may be changed unexpectedly by a third-party or system library functions, or by another thread.

Parameters:

p

The path to set as the current path.

Postconditions:

equivalent(p, current_path()) is true.

path temp_directory_path(system::error_code & ec);
path temp_directory_path();

Returns the temporary directory path.

	Note
	The `temp_directory_path` name was chosen to emphasize that the return is a path, not just a single directory name.

Overview:

The specifics of how the temporary directory path is determined are platform-dependent:

ISO/IEC 9945: The path supplied by the first environment variable found in the list TMPDIR, TMP, TEMP, TEMPDIR. If none of these are found, "/data/local/tmp" on Android, otherwise "/tmp".
Windows: The path reported by the GetTempPath API function.

Parameters:

`ec`	The error code to set on failure.

Returns:

A directory path suitable for temporary files under the conventions of the operating system. An error shall be reported if !exists(p) || !is_directory(p), where p is the path to be returned. In case of error, the overload taking ec returns an empty path.

path unique_path(path const & model, system::error_code & ec);
path unique_path(system::error_code & ec);
path unique_path(path const & model = "%%%%-%%%%-%%%%-%%%%");

Generates a unique path.

Overview:

The unique_path function generates a path name suitable for creating temporary files, including directories. The name is based on a model that uses the percent sign character to specify replacement by a random hexadecimal digit.

	Note
	The more bits of randomness in the generated path name, the less likelihood of prior existence or being guessed. Each replacement hexadecimal digit in the model adds four bits of randomness. The default model thus provides 64 bits of randomness. This is sufficient for most applications.

	Note
	The implementation will obtain the required randomness via a cryptographically secure pseudo-random number generator, such as one provided by the operating system, if possible. Such generators may block until sufficient entropy develops.

Parameters:

`model`	The path model to use for generating the unique path. "%%%%-%%%%-%%%%-%%%%" if not specified.
`ec`	The error code to set on failure.

Returns:

A path identical to model, except that each occurrence of a percent sign character ('%') is replaced by a random hexadecimal digit character in the range 0-9, a-f. In case of error, the overload taking ec returns an empty path.

path relative(path const & p, path const & base, system::error_code & ec);
path relative(path const & p, system::error_code & ec);
path relative(path const & p, path const & base = current_path());

Returns a relative path.

Overview:

Returns p made relative to base. Treats empty or identical paths as corner cases, not errors. Resolves symlinks and normalizes both p and base before other processing.

Parameters:

`p`	The path to be made relative.
`base`	The base path to make `p` relative to. `current_path()` if not specified.
`ec`	The error code to set on failure.

Postconditions:

The returned path is in normal form.

Returns:

weakly_canonical(p).lexically_relative(weakly_canonical(base)). Overloads taking ec return an empty path in case of error.

path system_complete(path const & p, system::error_code & ec);
path system_complete(path const & p);

Returns the system complete path.

Effects:

Composes an absolute path from p, using the same rules used by the operating system to resolve a path passed as the filename argument to standard library open functions.

Note

For ISO/IEC 9945, system_complete(p) has the same semantics as absolute(p, current_path()). For Windows, system_complete(p) has the same semantics as absolute(p, current_path()) if p.is_absolute() || !p.has_root_name() or p and base have the same root_name(). Otherwise it acts like absolute(p, cur), where cur is the current directory for the p.root_name() drive. This will be the current directory of that drive the last time it was set, and thus may be residue left over from a prior program run by the command processor. Although these semantics are often useful, they are also very error-prone.

Parameters:

`p`	The path to be completed.
`ec`	The error code to set on failure.

Postconditions:

For the returned path rp, rp.is_absolute() is true.

Returns:

The composed path. In case of error, the overload taking ec returns an empty path.

path absolute(path const & p, path const & base, system::error_code & ec);
path absolute(path const & p, system::error_code & ec);
path absolute(path const & p, path const & base = current_path());

Constructs an absolute path from p and base.

Overview:

The absolute path is composed according to the following table:

	`p.has_root_directory()`	`!p.has_root_directory()`
`p.has_root_name()`	`return p`	`return p.root_name() / absolute(base).root_directory() / absolute(base).relative_path() / p.relative_path()`
`!p.has_root_name()`	`return absolute(base).root_name() / p`	`return absolute(base) / p`

Parameters:

`p`	The path to make absolute.
`base`	The path to use as a base for `p`. `current_path()` if not specified.
`ec`	The error code to set on failure.

Postconditions:

For the returned path rp, rp.is_absolute() is true.

Returns:

If p.is_absolute() is true then p, otherwise an absolute path composed according to the table above. In case of error, the overloads taking ec return an empty path.

path canonical(path const & p, path const & base, system::error_code & ec);
path canonical(path const & p, system::error_code & ec);
path canonical(path const & p, path const & base = current_path());

Converts p to canonical path relative to base.

Overview:

Converts p to an absolute path that has no symbolic link, dot, or dot-dot elements. Testing path elements for symbolic links is done as if by calling is_symlink() and requires absolute(p, base) to exist.

	Note
	`!exists(absolute(p, base))` is an error.

	Note
	Canonical pathnames allow security checking of a path (e.g. does this path live in "/home/goodguy" or "/home/badguy"?).

Parameters:

`p`	The path to canonicalize.
`base`	The path to use as a base for `p`. `current_path()` if not specified.
`ec`	The error code to set on failure.

Returns:

A canonical path that refers to the same file system object as absolute(p, base). In case of error, the overloads taking ec return an empty path.

path weakly_canonical(path const & p, path const & base, 
                      system::error_code & ec);
path weakly_canonical(path const & p, system::error_code & ec);
path weakly_canonical(path const & p, path const & base = current_path());

Returns path with symlinks resolved and result normalized.

Effects: : Let head be the path composed of the leading elements of p that exist and tail - from the rest of p. Calls canonical(head, base) or canonical(head, base, ec), appends tail to the returned path as if by using operator/. The result is then normalized and returned.

	Note
	Uses `operator/=` to compose the returned path. Uses the `status()` function to determine existence.

	Note
	The implementation is allowed (and encouraged) to avoid unnecessary normalization such as when `canonical()` has already been called on the entirety of `p`.

See Also: canonical.

Parameters:

`p`	The path to canonicalize.
`base`	The path to use as a base for `p`. `current_path()` if not specified.
`ec`	The error code to set on failure.

Postconditions:

The returned path is in normal form.

Returns:

The canonicalized path. In case of error, the overloads taking ec return an empty path.

Operational Functions

void copy(path const & from, path const & to, copy_options options, 
          system::error_code & ec);
void copy(path const & from, path const & to, system::error_code & ec);
void copy(path const & from, path const & to, copy_options options);
void copy(path const & from, path const & to);

Copies files or directories.

Effects:

In the following description, assume any errors reported by the mentioned calls propagate immediately to the caller, either as an exception or by setting the ec argument to the error code, as described in the Error reporting section.

Let f and t be file_status objects obtained the following way:

If (options & (copy_options::create_symlinks | copy_options::skip_symlinks)) != copy_options::none then f = symlink_status(from) and t = symlink_status(to);
Otherwise, if (options & copy_options::copy_symlinks) != copy_options::none then f = symlink_status(from) and t = status(to);
Otherwise, f = status(from) and t = status(to).

Then, report an error if:

!exists(f), or
equivalent(from, to, ec), or
is_other(f) || is_other(t), or
is_directory(f) && is_regular_file(t)

Otherwise, if is_symlink(f), then:

If (options & copy_options::skip_symlinks) != copy_options::none then return;
Otherwise if !exists(to) && (options & copy_options::copy_symlinks) != copy_options::none then copy_symlink(from, to);
Otherwise report error.

Otherwise, if is_regular_file(f), then:

If (options & copy_options::directories_only) != copy_options::none then return;
Otherwise if (options & copy_options::create_symlinks) != copy_options::none then create_symlink(link, to), where link is determined as follows:
- If from.is_absolute() then link equals to from;
- Otherwise, link is equivalent to relative(absolute(to.parent_path()), absolute(from.parent_path())) / from.filename().
Otherwise if (options & copy_options::create_hard_links) != copy_options::none then create_hard_link(from, to);
Otherwise if is_directory(to) then copy_file(from, to / from.filename(), options);
Otherwise copy_file(from, to, options);

Otherwise, if is_directory(f), then:

If (options & copy_options::create_symlinks) != copy_options::none then report error with error code equal to make_error_code(system::errc::is_a_directory);
Otherwise if (options & copy_options::recursive) != copy_options::none, or options == copy_options::none and this call to copy is not a recursive call from copy then:
- If !exists(t), then create_directory(to, from).
- Then, iterate over files in from and for each directory_entry x obtained during iteration invoke copy(x.path(), to / x.path().filename(), options);
Otherwise, return.

Otherwise, for all unsupported file types of f report error.

Parameters:

`from`	The path to the file or directory to be copied.
`to`	The path to the destination.
`options`	Copy options to control the behavior of the operation. `copy_options::none` if not specified.
`ec`	The error code to set on failure.

Requires:

options must contain at most one option from each of the following groups:

bool copy_file(path const & from, path const & to, copy_options options, 
               system::error_code & ec);
bool copy_file(path const & from, path const & to, system::error_code & ec);
bool copy_file(path const & from, path const & to, copy_options options);
bool copy_file(path const & from, path const & to);

Copies a file.

Effects:

Report an error if:

!is_regular_file(from), or
exists(to) && !is_regular_file(to), or
exists(to) && equivalent(from, to), or
exists(to) && (options & (copy_options::skip_existing | copy_options::overwrite_existing)) == copy_options::none;

Otherwise, return successfully with no effect if:

exists(to) && (options & copy_options::skip_existing) != copy_options::none, or
exists(to) && (options & copy_options::update_existing) != copy_options::none and last write time of to is more recent than that of from;

Otherwise:

The contents and attributes of the file from resolves to are copied to the file to resolves to. If copying file attributes (but not contents) fails with an error and (options & copy_options::ignore_attribute_errors) != copy_options::none then that error is ignored. After that,
If (options & copy_options::synchronize) != copy_options::none, the written data and attributes are synchronized with the permanent storage; otherwise
If (options & copy_options::synchronize_data) != copy_options::none, the written data is synchronized with the permanent storage.

	Note
	When `copy_options::update_existing` is specified, checking the write times of `from` and `to` may not be atomic with the copy operation. Another process may create or modify the file identified by `to` after the file modification times have been checked but before copying starts. In this case the target file will be overwritten.

Note

The copy_options::synchronize_data and copy_options::synchronize options may have a significant performance impact. The copy_options::synchronize_data option may be less expensive than copy_options::synchronize. However, without these options, upon returning from copy_file it is not guaranteed that the copied file is completely written and preserved in case of a system failure. Any delayed write operations may fail after the function returns, at the point of physically writing the data to the underlying media, and this error will not be reported to the caller.

	Note
	The `copy_options::ignore_attribute_errors` option can be used when the caller does not require file attributes to be copied. The implementation is permitted to make an attempt to copy the file attributes, but still succeed the file copying operation if that attempt fails. This option may be useful with file systems that do not fully support operations of file attributes.

Parameters:

`from`	The path to the file to be copied.
`to`	The path to the destination file.
`options`	Copy options to control the behavior of the operation. `copy_options::none` if not specified.
`ec`	The error code to set on failure.

Requires:

options must contain at most one option from each of the following groups:

Returns:

true if the file was copied without error, false otherwise.

```
void copy_symlink(path const & existing_symlink, path const & new_symlink, 
                  system::error_code & ec);
void copy_symlink(path const & existing_symlink, path const & new_symlink);
```
Copies a symbolic link.
Effects: create_symlink(read_symlink(existing_symlink, ec), new_symlink, ec).

Parameters:

existing_symlink

The path to an existing symbolic link.

new_symlink

The path to the new symbolic link to be created.

ec

The error code to set on failure.

bool create_directories(path const & p, system::error_code & ec);
bool create_directories(path const & p);

Creates directories.

Effects: Establishes the postcondition by calling create_directory() for any element of p that does not exist.

Complexity: O(n+1) where n is the number of elements of p that do not exist.

Parameters:

`p`	The path to the directory to be created.
`ec`	The error code to set on failure.

Postconditions:

is_directory(p) is true.

Returns:

true if a new directory was created, false otherwise.

bool create_directory(path const & p, path const & existing, 
                      system::error_code & ec);
bool create_directory(path const & p, system::error_code & ec);
bool create_directory(path const & p, path const & existing);
bool create_directory(path const & p);

Creates a directory.

Effects:

If p resolves to an existing directory, returns with no effect.

Otherwise, establishes the postcondition by attempting to create the directory p resolves to, as if by ISO/IEC 9945 mkdir(). For overloads without the existing argument, the new directory is created with read, write and file iteration permissions for all users (S_IRWXU|S_IRWXG|S_IRWXO mode in ISO/IEC 9945). Overloads with existing argument obtain permissions from existing, which must be a path to an existing directory.

	Note
	On Windows, an implementation may call `CreateDirectoryW(p.c_str(), nullptr)` when `existing` is not specified and `CreateDirectoryExW(existing.c_str(), p.c_str(), nullptr)` otherwise.

Parameters:

`p`	The path to the directory to be created.
`existing`	The path to an existing directory to obtain permissions from.
`ec`	The error code to set on failure.

Postconditions:

is_directory(p) is true.

Returns:

true if a new directory was created, false otherwise.

void create_directory_symlink(path const & to, path const & new_symlink, 
                              system::error_code & ec);
void create_directory_symlink(path const & to, path const & new_symlink);

Creates a directory symbolic link.

Effects: Establishes the postcondition, as if by ISO/IEC 9945 symlink().

	Note
	Some operating systems, such as Windows, require symlink creation to identify that the link is to a directory. Portable code should use `create_directory_symlink()` to create directory symlinks rather than `create_symlink()`.

	Note
	Some operating systems do not support symbolic links at all or support them only for regular files. Some file systems do not support symbolic links regardless of the operating system - the FAT file system used on memory cards and flash drives, for example.

Parameters:

`to`	The target path that the symbolic link will point to.
`new_symlink`	The path to the new symbolic link to be created.
`ec`	The error code to set on failure.

Postconditions:

new_symlink resolves to a symbolic link file that contains an unspecified representation of to.

void create_hard_link(path const & to, path const & new_hard_link, 
                      system::error_code & ec);
void create_hard_link(path const & to, path const & new_hard_link);

Creates a hard link.

Effects: Establishes the postcondition, as if by ISO/IEC 9945 link().

	Note
	Some operating systems do not support hard links at all or support them only for regular files. Some file systems do not support hard links regardless of the operating system - the FAT file system used on memory cards and flash drives, for example. Some file systems limit the number of links per file.

Parameters:

`to`	The path to the existing file.
`new_hard_link`	The path to the new hard link to be created.
`ec`	The error code to set on failure.

Postconditions:

exists(to) && exists(new_hard_link) && equivalent(to, new_hard_link) is true. The contents of the file or directory to resolves to are unchanged.

void create_symlink(path const & to, path const & new_symlink, 
                    system::error_code & ec);
void create_symlink(path const & to, path const & new_symlink);

Creates a file symbolic link.

Effects: Establishes the postcondition, as if by ISO/IEC 9945 symlink().

	Note
	Some operating systems do not support symbolic links at all or support them only for regular files. Some file systems do not support symbolic links regardless of the operating system - the FAT system used on memory cards and flash drives, for example.

Parameters:

`to`	The target path that the symbolic link will point to.
`new_symlink`	The path to the new symbolic link to be created.
`ec`	The error code to set on failure.

Postconditions:

new_symlink resolves to a symbolic link file that contains an unspecified representation of to.

path read_symlink(path const & p, system::error_code & ec);
path read_symlink(path const & p);

Reads contents of a symbolic link.

	Note
	It is an error if `p` does not resolve to a symbolic link.

Parameters:

`p`	The path to the symbolic link.
`ec`	The error code to set on failure.

Returns:

If p resolves to a symbolic link, a path object containing the contents of that symbolic link. Otherwise an empty path object.

bool remove(path const & p, system::error_code & ec);
bool remove(path const & p);

Removes a file or directory.

Effects:

If exists(symlink_status(p, ec)), it is removed as if by ISO/IEC 9945 remove().

	Note
	A symbolic link is itself removed, rather than the file it resolves to being removed.

Parameters:

`p`	The path to the file or directory to be removed.
`ec`	The error code to set on failure.

Postconditions:

!exists(p) is true.

Returns:

false if p did not exist, true otherwise.

boost::uintmax_t remove_all(path const & p, system::error_code & ec);
boost::uintmax_t remove_all(path const & p);

Recursively removes files and directories.

Effects:

Recursively deletes the contents of p if it exists, then deletes file p itself, as if by ISO/IEC 9945 remove().

	Note
	A symbolic link is itself removed, rather than the file it resolves to being removed.

Parameters:

`p`	The path to the file or directory to be removed.
`ec`	The error code to set on failure.

Postconditions:

!exists(p) is true.

Returns:

The number of files removed.

void rename(path const & old_p, path const & new_p, system::error_code & ec);
void rename(path const & old_p, path const & new_p);

Renames a file or directory.

Effects:

Renames old_p to new_p, as if by ISO/IEC 9945 rename().

Note

If old_p and new_p resolve to the same existing file, no action is taken. Otherwise, if new_p resolves to an existing non-directory file, it is removed, while if new_p resolves to an existing directory, it is removed if empty on ISO/IEC 9945 but is an error on Windows. A symbolic link is itself renamed, rather than the file it resolves to being renamed. Renaming across different file systems is an error on ISO/IEC 9945 but may succeed on Windows, resulting in a copy to new_p and removal of old_p. Portable programs should avoid renaming files across file systems.

Parameters:

`old_p`	The current path of the file or directory.
`new_p`	The new path for the file or directory.
`ec`	The error code to set on failure.

space_info space(path const & p, system::error_code & ec);
space_info space(path const & p);

Returns filesystem space information.

Parameters:

`p`	The path to any file in the filesystem.
`ec`	The error code to set on failure.

Returns:

An object of type space_info. The value of the space_info object is determined as if by using ISO/IEC 9945 statvfs() to obtain an ISO/IEC 9945 struct statvfs, and then multiplying its f_blocks, f_bfree, and f_bavail members by its f_frsize member, and assigning the results to the capacity, free, and available members respectively. Any members for which the value cannot be determined shall be set to -1.

bool equivalent(path const & p1, path const & p2, system::error_code & ec);
bool equivalent(path const & p1, path const & p2);

Checks if two paths resolve to the same file.

Overview:

Two paths are considered to resolve to the same file system entity if two candidate entities reside on the same filesystem at the same location. This is determined as if by the values of the ISO/IEC 9945 stat structure, obtained as if by stat() for the two paths, having equal st_dev values and equal st_ino values.

Note

ISO/IEC 9945 requires that st_dev "must be unique within a Local Area Network". Conservative ISO/IEC 9945 implementations may also wish to check for equal st_size and st_mtime values. Windows implementations may use GetFileInformationByHandle() as a surrogate for stat(), and consider "same" to be equal values for dwVolumeSerialNumber, nFileIndexHigh, nFileIndexLow, nFileSizeHigh, nFileSizeLow, ftLastWriteTime.dwLowDateTime, and ftLastWriteTime.dwHighDateTime.

v3: !exists(p1) && !exists(p2) is an error. If only one of the paths doesn't exist, false is returned without error.

v4: !exists(p1) || !exists(p2) is an error.

Parameters:

`p1`	First path to test for equivalence.
`p2`	Second path to test for equivalence.
`ec`	The error code to set on failure.

Returns:

true, if p1 and p2 resolve to the same file system entity, else false.

Directory Iteration Reference

Header <boost/filesystem/directory.hpp>

Header <boost/filesystem/directory.hpp>

namespace boost {
  template<typename C, typename Enabler> struct range_const_iterator;

  template<> 
    struct range_const_iterator<boost::filesystem::directory_iterator, void>;
  template<> 
    struct range_const_iterator<boost::filesystem::recursive_directory_iterator, void>;

  template<typename C, typename Enabler> struct range_mutable_iterator;

  template<> 
    struct range_mutable_iterator<boost::filesystem::directory_iterator, void>;
  template<> 
    struct range_mutable_iterator<boost::filesystem::recursive_directory_iterator, void>;
  namespace filesystem {
    class directory_entry;
    class directory_iterator;
    class recursive_directory_iterator;

    enum directory_options;

    // File Status Queries for Directory Entries
    file_status status(directory_entry const &, system::error_code &);
    file_status status(directory_entry const &);
    file_status symlink_status(directory_entry const &, system::error_code &);
    file_status symlink_status(directory_entry const &);
    bool type_present(directory_entry const &, system::error_code &);
    bool type_present(directory_entry const &);
    bool status_known(directory_entry const &, system::error_code &);
    bool status_known(directory_entry const &);
    bool exists(directory_entry const &, system::error_code &);
    bool exists(directory_entry const &);
    bool is_regular_file(directory_entry const &, system::error_code &);
    bool is_regular_file(directory_entry const &);
    bool is_directory(directory_entry const &, system::error_code &);
    bool is_directory(directory_entry const &);
    bool is_symlink(directory_entry const &, system::error_code &);
    bool is_symlink(directory_entry const &);
    bool is_block_file(directory_entry const &, system::error_code &);
    bool is_block_file(directory_entry const &);
    bool is_character_file(directory_entry const &, system::error_code &);
    bool is_character_file(directory_entry const &);
    bool is_fifo(directory_entry const &, system::error_code &);
    bool is_fifo(directory_entry const &);
    bool is_socket(directory_entry const &, system::error_code &);
    bool is_socket(directory_entry const &);
    bool is_reparse_file(directory_entry const &, system::error_code &);
    bool is_reparse_file(directory_entry const &);
    bool is_other(directory_entry const &, system::error_code &);
    bool is_other(directory_entry const &);

    // Range Accessors and Range-based Loop Support
    directory_iterator const & begin(directory_iterator const &);
    directory_iterator end(directory_iterator const &);
    directory_iterator const & cbegin(directory_iterator const &);
    directory_iterator cend(directory_iterator const &);
    directory_iterator & range_begin(directory_iterator &);
    directory_iterator range_begin(directory_iterator const &);
    directory_iterator range_end(directory_iterator &);
    directory_iterator range_end(directory_iterator const &);
    recursive_directory_iterator const & 
    begin(recursive_directory_iterator const &);
    recursive_directory_iterator end(recursive_directory_iterator const &);
    recursive_directory_iterator const & 
    cbegin(recursive_directory_iterator const &);
    recursive_directory_iterator cend(recursive_directory_iterator const &);
    recursive_directory_iterator & range_begin(recursive_directory_iterator &);
    recursive_directory_iterator 
    range_begin(recursive_directory_iterator const &);
    recursive_directory_iterator range_end(recursive_directory_iterator &);
    recursive_directory_iterator 
    range_end(recursive_directory_iterator const &);
  }
}

File Status Queries for Directory Entries

```
file_status status(directory_entry const & e, system::error_code & ec);
file_status status(directory_entry const & e);
```
Returns the file status.

Parameters:

e

Directory entry.

ec

Error code returned in case of failure.

Returns:

e.status(ec) or e.status(ec), respectively.
```
file_status symlink_status(directory_entry const & e, system::error_code & ec);
file_status symlink_status(directory_entry const & e);
```
Returns the symlink file status.

Parameters:

e

Directory entry.

ec

Error code returned in case of failure.

Returns:

e.symlink_status(ec) or e.symlink_status(), respectively.

bool type_present(directory_entry const & e, system::error_code & ec);
bool type_present(directory_entry const & e);

Checks if file type information is present.

Parameters:

`e`	Directory entry.
`ec`	Error code returned in case of failure.

Returns:

e.file_type(ec) != filesystem::status_error or e.file_type() != filesystem::status_error, respectively.

bool status_known(directory_entry const & e, system::error_code & ec);
bool status_known(directory_entry const & e);

Checks if file status information is known.

Parameters:

`e`	Directory entry.
`ec`	Error code returned in case of failure.

Returns:

filesystem::status_known(e.status(ec)) or filesystem::status_known(e.status()), respectively.

```
bool exists(directory_entry const & e, system::error_code & ec);
bool exists(directory_entry const & e);
```
Checks if the file exists.

Parameters:

e

Directory entry.

ec

Error code returned in case of failure.

Returns:

e.exists(ec) or e.exists(), respectively.
```
bool is_regular_file(directory_entry const & e, system::error_code & ec);
bool is_regular_file(directory_entry const & e);
```
Checks if the file is a regular file.

Parameters:

e

Directory entry.

ec

Error code returned in case of failure.

Returns:

e.is_regular_file(ec) or e.is_regular_file(), respectively.
```
bool is_directory(directory_entry const & e, system::error_code & ec);
bool is_directory(directory_entry const & e);
```
Checks if the file is a directory.

Parameters:

e

Directory entry.

ec

Error code returned in case of failure.

Returns:

e.is_directory(ec) or e.is_directory(), respectively.
```
bool is_symlink(directory_entry const & e, system::error_code & ec);
bool is_symlink(directory_entry const & e);
```
Checks if the file is a symbolic link.

Parameters:

e

Directory entry.

ec

Error code returned in case of failure.

Returns:

e.is_symlink(ec) or e.is_symlink(), respectively.
```
bool is_block_file(directory_entry const & e, system::error_code & ec);
bool is_block_file(directory_entry const & e);
```
Checks if the file is a block special file.

Parameters:

e

Directory entry.

ec

Error code returned in case of failure.

Returns:

e.is_block_file(ec) or e.is_block_file(), respectively.
```
bool is_character_file(directory_entry const & e, system::error_code & ec);
bool is_character_file(directory_entry const & e);
```
Checks if the file is a character special file.

Parameters:

e

Directory entry.

ec

Error code returned in case of failure.

Returns:

e.is_character_file(ec) or e.is_character_file(), respectively.
```
bool is_fifo(directory_entry const & e, system::error_code & ec);
bool is_fifo(directory_entry const & e);
```
Checks if the file is a FIFO or pipe file.

Parameters:

e

Directory entry.

ec

Error code returned in case of failure.

Returns:

e.is_fifo(ec) or e.is_fifo(), respectively.
```
bool is_socket(directory_entry const & e, system::error_code & ec);
bool is_socket(directory_entry const & e);
```
Checks if the file is a socket file.

Parameters:

e

Directory entry.

ec

Error code returned in case of failure.

Returns:

e.is_socket(ec) or e.is_socket(), respectively.
```
bool is_reparse_file(directory_entry const & e, system::error_code & ec);
bool is_reparse_file(directory_entry const & e);
```
Checks if the file is a reparse file.

Parameters:

e

Directory entry.

ec

Error code returned in case of failure.

Returns:

e.is_reparse_file(ec) or e.is_reparse_file(), respectively.
```
bool is_other(directory_entry const & e, system::error_code & ec);
bool is_other(directory_entry const & e);
```
Checks if the file is of an unknown or other type.

Parameters:

e

Directory entry.

ec

Error code returned in case of failure.

Returns:

e.is_other(ec) or e.is_other(), respectively.

Range Accessors and Range-based Loop Support

```
directory_iterator const & begin(directory_iterator const & iter);
```
Returns beginning of the range.

Parameters:

iter

Directory iterator representing the iteration range.

Returns:

iter.
```
directory_iterator end(directory_iterator const &);
```
Returns ending of the range.

Returns:

directory_iterator().
```
directory_iterator const & cbegin(directory_iterator const & iter);
```
Returns beginning of the immutable range.

Parameters:

iter

Directory iterator representing the iteration range.

Returns:

iter.
```
directory_iterator cend(directory_iterator const &);
```
Returns ending of the immutable range.

Returns:

directory_iterator().
```
directory_iterator & range_begin(directory_iterator & iter);
directory_iterator range_begin(directory_iterator const & iter);
```
Returns beginning of the iteration range.

Note

This function is part of integration with BOOST_FOREACH.

Parameters:

iter

Directory iterator representing the iteration range.

Returns:

iter.
```
directory_iterator range_end(directory_iterator &);
directory_iterator range_end(directory_iterator const &);
```
Returns ending of the iteration range.

Note

This function is part of integration with BOOST_FOREACH.

Returns:

directory_iterator().
```
recursive_directory_iterator const & 
begin(recursive_directory_iterator const & iter);
```
Returns beginning of the range.

Parameters:

iter

Recursive directory iterator representing the iteration range.

Returns:

iter.

recursive_directory_iterator end(recursive_directory_iterator const &);

Returns ending of the range.

Returns:

recursive_directory_iterator().

```
recursive_directory_iterator const & 
cbegin(recursive_directory_iterator const & iter);
```
Returns beginning of the immutable range.

Parameters:

iter

Directory iterator representing the iteration range.

Returns:

iter.
```
recursive_directory_iterator cend(recursive_directory_iterator const &);
```
Returns ending of the immutable range.

Returns:

recursive_directory_iterator().
```
recursive_directory_iterator & 
range_begin(recursive_directory_iterator & iter);
recursive_directory_iterator 
range_begin(recursive_directory_iterator const & iter);
```
Returns beginning of the iteration range.

Note

This function is part of integration with BOOST_FOREACH.

Parameters:

iter

Recursive directory iterator representing the iteration range.

Returns:

iter.

recursive_directory_iterator range_end(recursive_directory_iterator &);
recursive_directory_iterator range_end(recursive_directory_iterator const &);

Returns ending of the iteration range.

	Note
	This function is part of integration with `BOOST_FOREACH`.

Returns:

recursive_directory_iterator().

File Status

Header <boost/filesystem/file_status.hpp>

Header <boost/filesystem/file_status.hpp>

namespace boost {
  namespace filesystem {
    class file_status;

    enum file_type;
    enum perms;
    bool type_present(file_status);
    bool permissions_present(file_status);
    bool status_known(file_status);
    bool exists(file_status);
    bool is_regular_file(file_status);
    bool is_directory(file_status);
    bool is_symlink(file_status);
    bool is_block_file(file_status);
    bool is_character_file(file_status);
    bool is_fifo(file_status);
    bool is_socket(file_status);
    bool is_reparse_file(file_status);
    bool is_other(file_status);
  }
}

Exceptions

Header <boost/filesystem/exception.hpp>

Header <boost/filesystem/exception.hpp>

namespace boost {
  namespace filesystem {
    class filesystem_error;
  }
}

I/O Utilities

Header <boost/filesystem/cstdio.hpp>
Header <boost/filesystem/fstream.hpp>

Header <boost/filesystem/cstdio.hpp>

namespace boost {
  namespace filesystem {
    std::FILE * fopen(filesystem::path const &, const char *);
  }
}

Header <boost/filesystem/fstream.hpp>

namespace boost {
  namespace filesystem {
    template<typename Char, typename Traits = std::char_traits< Char > > 
      class basic_filebuf;
    template<typename Char, typename Traits = std::char_traits< Char > > 
      class basic_fstream;
    template<typename Char, typename Traits = std::char_traits< Char > > 
      class basic_ifstream;
    template<typename Char, typename Traits = std::char_traits< Char > > 
      class basic_ofstream;

    typedef basic_filebuf< char > filebuf;
    typedef basic_ifstream< char > ifstream;
    typedef basic_ofstream< char > ofstream;
    typedef basic_fstream< char > fstream;
    typedef basic_filebuf< wchar_t > wfilebuf;
    typedef basic_ifstream< wchar_t > wifstream;
    typedef basic_ofstream< wchar_t > wofstream;
    typedef basic_fstream< wchar_t > wfstream;
  }
}

	Note
	The generic format is required to ensure lexicographical comparison works correctly.

	Note
	The effects ensure that the path can safely round-trip with `operator>>`, even if the path contains spaces, double-quotes and '&' characters.

	Note
	May return `true` for some names not considered valid by the operating system under all conditions (particularly on operating systems which support multiple file systems.)

	Note
	For example, Windows `ERROR_SHARING_VIOLATION` errors. For ISO/IEC 9945, the case never arises.

	Note
	A postcondition of `last_write_time(p) == new_time` is not specified since it might not hold for file systems with coarse time granularity.