Working Draft, Standard for Programming Language C++ (N4713, 2017 year)

30.9.5

Class template basic_fstream

[fstream]

namespace std {

template<class charT, class traits = char_traits<charT>>

class basic_fstream : public basic_iostream<charT, traits> {

public:

using char_type

= charT;

using int_type

= typename traits::int_type;

using pos_type

= typename traits::pos_type;

using off_type

= typename traits::off_type;

using traits_type = traits;

// 30.9.5.1, constructors

basic_fstream();

explicit basic_fstream(

const char* s,

ios_base::openmode mode = ios_base::in | ios_base::out);

explicit basic_fstream(

const filesystem::path::value_type* s,

ios_base::openmode mode = ios_base::in|ios_base::out);

// wide systems only; see

30.9.1

explicit basic_fstream(

const string& s,

ios_base::openmode mode = ios_base::in | ios_base::out);

explicit basic_fstream(

const filesystem::path& s,

ios_base::openmode mode = ios_base::in | ios_base::out);

basic_fstream(const basic_fstream& rhs) = delete;

basic_fstream(basic_fstream&& rhs);

// 30.9.5.2, assign and swap

basic_fstream& operator=(const basic_fstream& rhs) = delete;

basic_fstream& operator=(basic_fstream&& rhs);

void swap(basic_fstream& rhs);

// 30.9.5.3, members

basic_filebuf<charT, traits>* rdbuf() const;

bool is_open() const;

void open(

const char* s,

ios_base::openmode mode = ios_base::in | ios_base::out);

void open(

const filesystem::path::value_type* s,

ios_base::openmode mode = ios_base::in|ios_base::out);

// wide systems only; see

30.9.1

void open(

const string& s,

ios_base::openmode mode = ios_base::in | ios_base::out);

void open(

const filesystem::path& s,

ios_base::openmode mode = ios_base::in | ios_base::out);

void close();

private:

basic_filebuf<charT, traits> sb; // exposition only

};

template<class charT, class traits>

void swap(basic_fstream<charT, traits>& x,

basic_fstream<charT, traits>& y);

}

The class template basic_fstream<charT, traits> supports reading and writing from named files. It uses

a basic_filebuf<charT, traits> object to control the associated sequences. For the sake of exposition,

the maintained data is presented here as:

(1.1)

—

sb, the basic_filebuf object.

§ 30.9.5

1102

30.9.5.1

basic_fstream constructors

[fstream.cons]

basic_fstream();

Effects: Constructs an object of class basic_fstream<charT, traits>, initializing the base class with

basic_iostream<charT, traits>(&sb) (30.7.4.6.1) and initializing sb with basic_filebuf<charT,

traits>().

explicit basic_fstream(

const char* s,

ios_base::openmode mode = ios_base::in | ios_base::out);

explicit basic_fstream(

const filesystem::path::value_type* s,

ios_base::openmode mode = ios_base::in | ios_base::out);

// wide systems only; see 30.9.1

Effects: Constructs an object of class basic_fstream<charT, traits>, initializing the base class with

basic_iostream<charT, traits>(&sb) (30.7.4.6.1) and initializing sb with basic_filebuf<charT,

traits>(). Then calls rdbuf()->open(s, mode). If that function returns a null pointer, calls

setstate(failbit).

explicit basic_fstream(

const string& s,

ios_base::openmode mode = ios_base::in | ios_base::out);

explicit basic_fstream(

const filesystem::path& s,

ios_base::openmode mode = ios_base::in | ios_base::out);

Effects: The same as basic_fstream(s.c_str(), mode).

basic_fstream(basic_fstream&& rhs);

Effects: Move constructs from the rvalue rhs. This is accomplished by move constructing the base

class, and the contained basic_filebuf. Next basic_istream<charT, traits>::set_rdbuf(&sb)

is called to install the contained basic_filebuf.

30.9.5.2

Assign and swap

[fstream.assign]

basic_fstream& operator=(basic_fstream&& rhs);

Effects: Move assigns the base and members of *this from the base and corresponding members of

rhs.

Returns: *this.

void swap(basic_fstream& rhs);

Effects: Exchanges the state of *this and rhs by calling basic_iostream<charT,traits>::swap(rhs)

and sb.swap(rhs.sb).

template<class charT, class traits>

void swap(basic_fstream<charT, traits>& x,

basic_fstream<charT, traits>& y);

Effects: As if by x.swap(y).

30.9.5.3

Member functions

[fstream.members]

basic_filebuf<charT, traits>* rdbuf() const;

Returns: const_cast<basic_filebuf<charT, traits>*>(&sb).

bool is_open() const;

Returns: rdbuf()->is_open().

void open(

const char* s,

ios_base::openmode mode = ios_base::in | ios_base::out);

§ 30.9.5.3

1103

void open(

const filesystem::path::value_type* s,

ios_base::openmode mode = ios_base::in | ios_base::out);

// wide systems only; see 30.9.1

Effects: Calls rdbuf()->open(s, mode). If that function does not return a null pointer calls clear(),

otherwise calls setstate(failbit) (which may throw ios_base::failure) (30.5.5.4).

void open(

const string& s,

ios_base::openmode mode = ios_base::in | ios_base::out);

void open(

const filesystem::path& s,

ios_base::openmode mode = ios_base::in | ios_base::out);

Effects: Calls open(s.c_str(), mode).

void close();

Effects: Calls rdbuf()->close() and, if that function returns a null pointer, calls setstate(failbit)

(which may throw ios_base::failure) (30.5.5.4).

30.10

Synchronized output streams

[syncstream]

30.10.1

Header <syncstream> synopsis

[syncstream.syn]

namespace std {

template<class charT, class traits, class Allocator>

class basic_syncbuf;

using syncbuf = basic_syncbuf<char>;

using wsyncbuf = basic_syncbuf<wchar_t>;

template<class charT, class traits, class Allocator>

class basic_osyncstream;

using osyncstream = basic_osyncstream<char>;

using wosyncstream = basic_osyncstream<wchar_t>;

}

The header <syncstream> provides a mechanism to synchronize execution agents writing to the same stream.

30.10.2

Class template basic_syncbuf

[syncstream.syncbuf]

30.10.2.1

Overview

[syncstream.syncbuf.overview]

namespace std {

template<class charT, class traits, class Allocator>

class basic_syncbuf : public basic_streambuf<charT, traits> {

public:

using char_type

= charT;

using int_type

= typename traits::int_type;

using pos_type

= typename traits::pos_type;

using off_type

= typename traits::off_type;

using traits_type

= traits;

using allocator_type = Allocator;

using streambuf_type = basic_streambuf<charT, traits>;

// 30.10.2.2, construction and destruction

explicit basic_syncbuf(streambuf_type* obuf = nullptr)

: basic_syncbuf(obuf, Allocator()) {}

basic_syncbuf(streambuf_type*, const Allocator&);

basic_syncbuf(basic_syncbuf&&);

~basic_syncbuf();

// 30.10.2.3, assignment and swap

basic_syncbuf& operator=(basic_syncbuf&&);

void swap(basic_syncbuf&);

§ 30.10.2.1

1104

// 30.10.2.4, member functions

bool emit();

streambuf_type* get_wrapped() const noexcept;

allocator_type get_allocator() const noexcept;

void set_emit_on_sync(bool) noexcept;

protected:

// 30.10.2.5, overridden virtual functions

int sync() override;

private:

streambuf_type* wrapped;

// exposition only

bool emit_on_sync{};

// exposition only

};

// 30.10.2.6, specialized algorithms

template<class charT, class traits, class Allocator>

void swap(basic_syncbuf<charT, traits, Allocator>&,

basic_syncbuf<charT, traits, Allocator>&);

}

Class template basic_syncbuf stores character data written to it, known as the associated output, into

internal buffers allocated using the object’s allocator. The associated output is transferred to the wrapped

stream buffer object *wrapped when emit() is called or when the basic_syncbuf object is destroyed. Such

transfers are atomic with respect to transfers by other basic_syncbuf objects with the same wrapped stream

buffer object.

30.10.2.2

Construction and destruction

[syncstream.syncbuf.cons]

basic_syncbuf(streambuf_type* obuf, const Allocator& allocator);

Effects: Constructs the basic_syncbuf object and sets wrapped to obuf.

Remarks: A copy of allocator is used to allocate memory for internal buffers holding the associated

output.

Throws: Nothing unless an exception is thrown by the construction of a mutex or by memory allocation.

Postconditions: get_wrapped() == obuf and get_allocator() == allocator are true.

basic_syncbuf(basic_syncbuf&& other);

Effects: Move constructs from other (Table 23).

Postconditions: The value returned by this->get_wrapped() is the value returned by other.get_-

wrapped() prior to calling this constructor. Output stored in other prior to calling this construc-

tor will be stored in *this afterwards. other.rdbuf()->pbase() == other.rdbuf()->pptr() and

other.get_wrapped() == nullptr are true.

Remarks: This constructor disassociates other from its wrapped stream buffer, ensuring destruction of

other produces no output.

~basic_syncbuf();

Effects: Calls emit().

Throws: Nothing. If an exception is thrown from emit(), the destructor catches and ignores that

exception.

30.10.2.3

Assignment and swap

[syncstream.syncbuf.assign]

basic_syncbuf& operator=(basic_syncbuf&& rhs) noexcept;

Effects: Calls emit() then move assigns from rhs. After the move assignment *this has the observable

state it would have had if it had been move constructed from rhs (30.10.2.2).

Returns: *this.

Postconditions:

(3.1)

—

rhs.get_wrapped() == nullptr is true.

§ 30.10.2.3

1105

(3.2)

—

this->get_allocator() == rhs.get_allocator() is true when

allocator_traits<Allocator>::propagate_on_container_move_assignment::value

is true; otherwise, the allocator is unchanged.

Remarks: This assignment operator disassociates rhs from its wrapped stream buffer, ensuring

destruction of rhs produces no output.

void swap(basic_syncbuf& other) noexcept;

Requires: Either allocator_traits<Allocator>::propagate_on_container_swap::value is true

or this->get_allocator() == other.get_allocator() is true.

Effects: Exchanges the state of *this and other.

30.10.2.4

Member functions

[syncstream.syncbuf.members]

bool emit();

Effects: Atomically transfers the associated output of *this to the stream buffer *wrapped, so that it

appears in the output stream as a contiguous sequence of characters. wrapped->pubsync() is called if

and only if a call was made to sync() since the most recent call to emit(), if any.

Returns: true if all of the following conditions hold; otherwise false:

(2.1)

—

wrapped == nullptr is false.

(2.2)

—

All of the characters in the associated output were successfully transferred.

(2.3)

—

The call to wrapped->pubsync() (if any) succeeded.

Postconditions: On success, the associated output is empty.

Synchronization: All emit() calls transferring characters to the same stream buffer object appear to

execute in a total order consistent with the “happens before” relation (6.8.2.1), where each emit() call

synchronizes with subsequent emit() calls in that total order.

Remarks: May call member functions of wrapped while holding a lock uniquely associated with wrapped.

streambuf_type* get_wrapped() const noexcept;

Returns: wrapped.

allocator_type get_allocator() const noexcept;

Returns: A copy of the allocator that was set in the constructor or assignment operator.

void set_emit_on_sync(bool b) noexcept;

Effects: emit_on_sync = b.

30.10.2.5

Overridden virtual functions

[syncstream.syncbuf.virtuals]

int sync() override;

Effects: Records that the wrapped stream buffer is to be flushed. Then, if emit_on_sync is true, calls

emit(). [ Note: If emit_on_sync is false, the actual flush is delayed until a call to emit().

— end

note ]

Returns: If emit() was called and returned false, returns -1; otherwise 0.

30.10.2.6

Specialized algorithms

[syncstream.syncbuf.special]

template<class charT, class traits, class Allocator>

void swap(basic_syncbuf<charT, traits, Allocator>& a,

basic_syncbuf<charT, traits, Allocator>& b) noexcept;

Effects: Equivalent to a.swap(b).

30.10.3

Class template basic_osyncstream

[syncstream.osyncstream]

30.10.3.1

Overview

[syncstream.osyncstream.overview]

namespace std {

template<class charT, class traits, class Allocator>

§ 30.10.3.1

1106

class basic_osyncstream : public basic_ostream<charT, traits> {

public:

using char_type

= charT;

using int_type

= typename traits::int_type;

using pos_type

= typename traits::pos_type;

using off_type

= typename traits::off_type;

using traits_type = traits;

using allocator_type = Allocator;

using streambuf_type = basic_streambuf<charT, traits>;

using syncbuf_type

= basic_syncbuf<charT, traits, Allocator>;

// 30.10.3.2, construction and destruction

basic_osyncstream(streambuf_type*, const Allocator&);

explicit basic_osyncstream(streambuf_type* obuf)

: basic_osyncstream(obuf, Allocator()) {}

basic_osyncstream(basic_ostream<charT, traits>& os, const Allocator&

allocator)

: basic_osyncstream(os.rdbuf(), allocator) {}

explicit basic_osyncstream(basic_ostream<charT, traits>& os)

: basic_osyncstream(os, Allocator()) {}

basic_osyncstream(basic_osyncstream&&) noexcept;

~basic_osyncstream();

// 30.10.3.3, assignment

basic_osyncstream& operator=(basic_osyncstream&&) noexcept;

// 30.10.3.4, member functions

void emit();

streambuf_type* get_wrapped() const noexcept;

syncbuf_type* rdbuf() const noexcept { return &sb ; }

private:

syncbuf_type sb;

// exposition only

};

}

Allocator shall meet the allocator requirements (20.5.3.5).

[ Example: A named variable can be used within a block statement for streaming.

{

osyncstream bout(cout);

bout << "Hello, ";

bout << "World!";

bout << endl; // flush is noted

bout << "and more!\n";

}

// characters are transferred and cout is flushed

— end example ]

[ Example: A temporary object can be used for streaming within a single statement.

osyncstream(cout) << "Hello, " << "World!" << ’\n’;

In this example, cout is not flushed.

— end example ]

30.10.3.2

Construction and destruction

[syncstream.osyncstream.cons]

basic_osyncstream(streambuf_type* buf, const Allocator& allocator);

Effects: Initializes sb from buf and allocator. Initializes the base class with basic_ostream(&sb).

[ Note: The member functions of the provided stream buffer might be called from emit() while a lock

is held. Care should be taken to ensure that this does not result in deadlock.

— end note ]

Postconditions: get_wrapped() == buf is true.

§ 30.10.3.2

1107

basic_osyncstream(basic_osyncstream&& other) noexcept;

Effects: Move constructs the base class and sb from the corresponding subobjects of other, and calls

basic_ostream<charT, traits>::set_rdbuf(&sb).

Postconditions: The value returned by get_wrapped() is the value returned by os.get_wrapped()

prior to calling this constructor. nullptr == other.get_wrapped() is true.

~basic_osyncstream();

Effects: Calls emit(). If an exception is thrown from emit(), that exception is caught and ignored.

30.10.3.3

Assignment

[syncstream.osyncstream.assign]

basic_osyncstream& operator=(basic_osyncstream&& rhs) noexcept;

Effects: First, calls emit(). If an exception is thrown from emit(), that exception is caught and

ignored. Move assigns sb from rhs.sb. [ Note: This disassociates rhs from its wrapped stream buffer

ensuring destruction of rhs produces no output.

— end note ]

Postconditions: nullptr == rhs.get_wrapped() is true. get_wrapped() returns the value previously

returned by rhs.get_wrapped().

30.10.3.4

Member functions

[syncstream.osyncstream.members]

void emit();

Effects: Calls sb.emit(). If that call returns false, calls setstate(ios::badbit).

[ Example: A flush on a basic_osyncstream does not flush immediately:

{

osyncstream bout(cout);

bout << "Hello," << ’\n’;

// no flush

bout.emit();

// characters transferred; cout not flushed

bout << "World!" << endl;

// flush noted; cout not flushed

bout.emit();

// characters transferred; cout flushed

bout << "Greetings." << ’\n’; // no flush

}

// characters transferred; cout not flushed

— end example ]

[Example: The function emit() can be used to handle exceptions from operations on the underlying

stream.

{

osyncstream bout(cout);

bout << "Hello, " << "World!" << ’\n’;

try {

bout.emit();

} catch (...) {

// handle exception

}

— end example ]

streambuf_type* get_wrapped() const noexcept;

Returns: sb.get_wrapped().

[Example: Obtaining the wrapped stream buffer with get_wrapped() allows wrapping it again with

an osyncstream. For example,

{

osyncstream bout1(cout);

bout1 << "Hello, ";

{

osyncstream(bout1.get_wrapped()) << "Goodbye, " << "Planet!" << ’\n’;

}

bout1 << "World!" << ’\n’;

}

§ 30.10.3.4

1108

produces the uninterleaved output

Goodbye, Planet!

Hello, World!

— end example ]

30.11

File systems

[filesystems]

30.11.1

General

[fs.general]

This subclause describes operations on file systems and their components, such as paths, regular files, and

directories.

A file system is a collection of files and their attributes.

A file is an object within a file system that holds user or system data. Files 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.

A directory is a file within a file system that acts as a container of directory entries that contain information

about other files, possibly including other directory files. The parent directory of a directory is the directory

that both contains a directory entry for the given directory and is represented by the filename dot-dot in the

given directory. The parent directory of other types of files is a directory containing a directory entry for the

file under discussion.

A link is an object that associates a filename with a file. Several links can associate names with the same

file. A hard link is 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. — end note ] A symbolic link is a type of file with the property

that when the file is encountered during pathname resolution (30.11.7), a string stored by the file is used to

modify the pathname resolution. [Note: Symbolic links are often called symlinks. 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. — end note ]

30.11.2

Conformance

[fs.conformance]

Conformance is specified in terms of behavior. Ideal behavior is not always implementable, so the conformance

subclauses take that into account.

30.11.2.1

POSIX conformance

[fs.conform.9945]

Some behavior is specified by reference to POSIX (30.11.3). How such behavior is actually implemented is

unspecified. [ Note: This constitutes an “as if” rule allowing implementations to call native operating system

or other APIs.

— end note ]

Implementations should provide such behavior as it is defined by POSIX. Implementations shall document

any behavior that differs from the behavior defined by POSIX. Implementations that do not support exact

POSIX behavior should provide behavior as close to POSIX 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 as specified in 30.11.6.

[Note: This allows users to rely on an

exception being thrown or an error code being set when an implementation cannot provide any reasonable

behavior. — end note ]

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

[Example: The FAT file system used by some memory cards, camera memory, and floppy disks does not

support hard links, symlinks, and many other features of more capable file systems, so implementations are

not required to support those features on the FAT file system but instead are required to report an error as

described above.

— end example ]

30.11.2.2

Operating system dependent behavior conformance

[fs.conform.os]

Behavior that is specified as being operating system dependent is dependent upon the behavior and character-

istics of an operating system. The operating 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 underlying operating system.

§ 30.11.2.2

1109

30.11.2.3

File system race behavior

[fs.race.behavior]

A file system race is the condition that occurs when multiple threads, processes, or computers interleave

access and modification of the same object within a file system. Behavior is undefined if calls to functions

provided by this subclause introduce a file system race.

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 herein, Requires: is not specified for the function. [Note: As a design practice,

preconditions are not specified when it is unreasonable for a program to detect them prior to calling the

function.

— end note ]

30.11.3

Normative references

[fs.norm.ref]

This subclause mentions commercially available operating systems for purposes of exposition.³³¹

30.11.4

Requirements

[fs.req]

Throughout this subclause, char, wchar_t, char16_t, and char32_t are collectively called encoded character

types.

Functions with template parameters named EcharT shall not participate in overload resolution unless EcharT

is one of the encoded character types.

Template parameters named InputIterator shall meet the input iterator requirements (27.2.3) and shall

have a value type that is one of the encoded character types.

[Note: Use of an encoded character type implies an associated character set and encoding. Since signed

char and unsigned char have no implied character set and encoding, they are not included as permitted

types.

— end note ]

Template parameters named Allocator shall meet the Allocator requirements (20.5.3.5).

30.11.4.1

Namespaces and headers

[fs.req.namespace]

Unless otherwise specified, references to entities described in this subclause are assumed to be qualified with

::std::filesystem::.

30.11.5

Header <filesystem> synopsis

[fs.filesystem.syn]

namespace std::filesystem {

// 30.11.7, paths

class path;

// 30.11.7.6, path non-member functions

void swap(path& lhs, path& rhs) noexcept;

size_t hash_value(const path& p) noexcept;

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

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

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

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

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

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

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

// 30.11.7.6.1, path inserter and extractor

template<class charT, class traits>

basic_ostream<charT, traits>&

operator<<(basic_ostream<charT, traits>& os, const path& p);

template<class charT, class traits>

basic_istream<charT, traits>&

operator>>(basic_istream<charT, traits>& is, path& p);

331) POSIX® is a registered trademark of The IEEE. Windows® is a registered trademark of Microsoft Corporation. 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.

§ 30.11.5

1110

// 30.11.7.6.2, path factory functions

template<class Source>

path u8path(const Source& source);

template<class InputIterator>

path u8path(InputIterator first, InputIterator last);

// 30.11.8, filesystem errors

class filesystem_error;

// 30.11.11, directory entries

class directory_entry;

// 30.11.12, directory iterators

class directory_iterator;

// 30.11.12.2, range access for directory iterators

directory_iterator begin(directory_iterator iter) noexcept;

directory_iterator end(const directory_iterator&) noexcept;

// 30.11.13, recursive directory iterators

class recursive_directory_iterator;

// 30.11.13.2, range access for recursive directory iterators

recursive_directory_iterator begin(recursive_directory_iterator iter)

noexcept;

recursive_directory_iterator end(const recursive_directory_iterator&)

noexcept;

// 30.11.10, file status

class file_status;

struct space_info {

uintmax_t capacity;

uintmax_t free;

uintmax_t available;

};

// 30.11.9, enumerations

enum class file_type;

enum class perms;

enum class perm_options;

enum class copy_options;

enum class directory_options;

using file_time_type = chrono::time_point<trivial-clock >;

// 30.11.14, filesystem operations

path absolute(const path& p);

path absolute(const path& p, error_code& ec);

path canonical(const path& p);

path canonical(const path& p, error_code& ec);

void copy(const path& from, const path& to);

void copy(const path& from, const path& to, error_code& ec) noexcept;

void copy(const path& from, const path& to, copy_options options);

void copy(const path& from, const path& to, copy_options options,

error_code& ec) noexcept;

bool copy_file(const path& from, const path& to);

bool copy_file(const path& from, const path& to, error_code& ec) noexcept;

bool copy_file(const path& from, const path& to, copy_options option);

bool copy_file(const path& from, const path& to, copy_options option,

error_code& ec) noexcept;

§ 30.11.5

1111

void

copy_symlink(const path& existing_symlink, const path& new_symlink);

void

copy_symlink(const path& existing_symlink, const path& new_symlink,

error_code& ec) noexcept;

bool

create_directories(const path& p);

bool

create_directories(const path& p, error_code& ec) noexcept;

bool

create_directory(const path& p);

bool

create_directory(const path& p, error_code& ec) noexcept;

bool

create_directory(const path& p, const path& attributes);

bool

create_directory(const path& p, const path& attributes,

error_code& ec) noexcept;

void

create_directory_symlink(const path& to, const path& new_symlink);

void

create_directory_symlink(const path& to, const path& new_symlink,

error_code& ec) noexcept;

void

create_hard_link(const path& to, const path& new_hard_link);

void

create_hard_link(const path& to, const path& new_hard_link,

error_code& ec) noexcept;

void

create_symlink(const path& to, const path& new_symlink);

void

create_symlink(const path& to, const path& new_symlink,

error_code& ec) noexcept;

path

current_path();

path

current_path(error_code& ec);

void

current_path(const path& p);

void

current_path(const path& p, error_code& ec) noexcept;

bool

equivalent(const path& p1, const path& p2);

bool

equivalent(const path& p1, const path& p2, error_code& ec) noexcept;

bool

exists(file_status s) noexcept;

bool

exists(const path& p);

bool

exists(const path& p, error_code& ec) noexcept;

uintmax_t file_size(const path& p);

uintmax_t file_size(const path& p, error_code& ec) noexcept;

uintmax_t hard_link_count(const path& p);

uintmax_t hard_link_count(const path& p, error_code& ec) noexcept;

bool is_block_file(file_status s) noexcept;

bool is_block_file(const path& p);

bool is_block_file(const path& p, error_code& ec) noexcept;

bool is_character_file(file_status s) noexcept;

bool is_character_file(const path& p);

bool is_character_file(const path& p, error_code& ec) noexcept;

bool is_directory(file_status s) noexcept;

bool is_directory(const path& p);

bool is_directory(const path& p, error_code& ec) noexcept;

bool is_empty(const path& p);

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

bool is_fifo(file_status s) noexcept;

bool is_fifo(const path& p);

bool is_fifo(const path& p, error_code& ec) noexcept;

§ 30.11.5

1112

bool is_other(file_status s) noexcept;

bool is_other(const path& p);

bool is_other(const path& p, error_code& ec) noexcept;

bool is_regular_file(file_status s) noexcept;

bool is_regular_file(const path& p);

bool is_regular_file(const path& p, error_code& ec) noexcept;

bool is_socket(file_status s) noexcept;

bool is_socket(const path& p);

bool is_socket(const path& p, error_code& ec) noexcept;

bool is_symlink(file_status s) noexcept;

bool is_symlink(const path& p);

bool is_symlink(const path& p, error_code& ec) noexcept;

file_time_type last_write_time(const path& p);

file_time_type last_write_time(const path& p, error_code& ec) noexcept;

void last_write_time(const path& p, file_time_type new_time);

void last_write_time(const path& p, file_time_type new_time,

error_code& ec) noexcept;

void permissions(const path& p, perms prms, perm_options opts=perm_options::replace);

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

void permissions(const path& p, perms prms, perm_options opts, error_code&

ec);

path proximate(const path& p, error_code& ec);

path proximate(const path& p, const path& base = current_path());

path proximate(const path& p, const path& base, error_code& ec);

path read_symlink(const path& p);

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

path relative(const path& p, error_code& ec);

path relative(const path& p, const path& base = current_path());

path relative(const path& p, const path& base, error_code& ec);

bool remove(const path& p);

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

uintmax_t remove_all(const path& p);

uintmax_t remove_all(const path& p, error_code& ec) noexcept;

void rename(const path& from, const path& to);

void rename(const path& from, const path& to, error_code& ec) noexcept;

void resize_file(const path& p, uintmax_t size);

void resize_file(const path& p, uintmax_t size, error_code& ec) noexcept;

space_info space(const path& p);

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

file_status status(const path& p);

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

bool status_known(file_status s) noexcept;

file_status symlink_status(const path& p);

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

path temp_directory_path();

path temp_directory_path(error_code& ec);

§ 30.11.5

1113

path weakly_canonical(const path& p);

path weakly_canonical(const path& p, error_code& ec);

}

trivial-clock is an implementation-defined type that satisfies the TrivialClock requirements (23.17.3)

and that is capable of representing and measuring file time values. Implementations should ensure that the

resolution and range of file_time_type reflect the operating system dependent resolution and range of file

time values.

30.11.6

Error reporting

[fs.err.report]

Filesystem library functions often provide two overloads, one that throws an exception to report file system

errors, and another that sets an error_code. [ Note: This supports two common use cases:

(1.1)

—

Uses where file system errors are truly exceptional and indicate a serious failure. Throwing an exception

is an appropriate response.

(1.2)

—

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.

— end note ]

Functions not having an argument of type error_code& handle errors as follows, unless otherwise specified:

—

(2.1)

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 shall be thrown. For functions with a single path argument, that argument shall be passed

to the filesystem_error constructor with a single path argument. For functions with two path

arguments, the first of these arguments shall be passed to the filesystem_error constructor as the

path1 argument, and the second shall be passed as the path2 argument. The filesystem_error

constructor’s error_code argument is set as appropriate for the specific operating system dependent

error.

(2.2)

—

Failure to allocate storage is reported by throwing an exception as described in 20.5.5.12.

(2.3)

—

Destructors throw nothing.

Functions having an argument of type error_code& handle errors as follows, unless otherwise specified:

(3.1)

—

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 error_code& argument is set as appropriate

for the specific operating system dependent error. Otherwise, clear() is called on the error_code&

argument.

30.11.7

Class path

[fs.class.path]

An object of class path represents a path and contains a pathname. Such an object is concerned only with

the lexical and syntactic aspects of a path. The path does not necessarily exist in external storage, and the

pathname is not necessarily valid for the current operating system or for a particular file system.

[Note: Class path is used to support the differences between the string types used by different operating

systems to represent pathnames, and to perform conversions between encodings when necessary.

— end

note ]

A path is 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 (30.11.7.1). The maximum number of

elements in the sequence is operating system dependent (30.11.2.2).

An absolute path is 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. A relative path is a path that is not absolute, and as such, 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: Pathnames “.” and “..” are relative paths.

— end

note ]

A pathname is a character string that represents the name of a path. Pathnames are formatted according to

the generic pathname format grammar (30.11.7.1) or according to an operating system dependent native

pathname format accepted by the host operating system.

§ 30.11.7

1114

Pathname resolution is the operating system dependent mechanism for resolving a pathname to a particular

file in a file hierarchy. There may be multiple pathnames that resolve to the same file. [ Example: POSIX

specifies the mechanism in section 4.11, Pathname resolution.

— end example ]

namespace std::filesystem {

class path {

public:

using value_type

= see below ;

using string_type = basic_string<value_type>;

static constexpr value_type preferred_separator = see below ;

// 30.11.9.1, enumeration format

enum format;

// 30.11.7.4.1, constructors and destructor

path() noexcept;

path(const path& p);

path(path&& p) noexcept;

path(string_type&& source, format fmt = auto_format);

template<class Source>

path(const Source& source, format fmt = auto_format);

template<class InputIterator>

path(InputIterator first, InputIterator last, format fmt = auto_format);

template<class Source>

path(const Source& source, const locale& loc, format fmt = auto_format);

template<class InputIterator>

path(InputIterator first, InputIterator last, const locale&

loc,

format

fmt

auto_format);

~path();

// 30.11.7.4.2, assignments

path& operator=(const path& p);

path& operator=(path&& p) noexcept;

path& operator=(string_type&& source);

path& assign(string_type&& source);

template<class Source>

path& operator=(const Source& source);

template<class Source>

path& assign(const Source& source);

template<class InputIterator>

path& assign(InputIterator first, InputIterator last);

// 30.11.7.4.3, appends

path& operator/=(const path& p);

template<class Source>

path& operator/=(const Source& source);

template<class Source>

path& append(const Source& source);

template<class InputIterator>

path& append(InputIterator first, InputIterator last);

// 30.11.7.4.4, concatenation

path& operator+=(const path& x);

path& operator+=(const string_type& x);

path& operator+=(basic_string_view<value_type> x);

path& operator+=(const value_type* x);

path& operator+=(value_type x);

template<class Source>

path& operator+=(const Source& x);

template<class EcharT>

path& operator+=(EcharT x);

template<class Source>

path& concat(const Source& x);

template<class InputIterator>

path& concat(InputIterator first, InputIterator last);

30.11.7

1115

// 30.11.7.4.5, modifiers

void clear() noexcept;

path& make_preferred();

path& remove_filename();

path& replace_filename(const path& replacement);

path& replace_extension(const path& replacement = path());

void swap(path& rhs) noexcept;

// 30.11.7.4.6, native format observers

const string_type& native() const noexcept;

const value_type* c_str() const noexcept;

operator string_type() const;

template<class EcharT, class traits = char_traits<EcharT>,

class Allocator = allocator<EcharT>>

basic_string<EcharT, traits, Allocator>

string(const Allocator& a = Allocator()) const;

std::string

string() const;

std::wstring

wstring() const;

std::string

u8string() const;

std::u16string u16string() const;

std::u32string u32string() const;

// 30.11.7.4.7, generic format observers

template<class EcharT, class traits = char_traits<EcharT>,

class Allocator = allocator<EcharT>>

basic_string<EcharT, traits, Allocator>

generic_string(const Allocator& a = Allocator())

const;

std::string

generic_string() const;

std::wstring

generic_wstring() const;

std::string

generic_u8string() const;

std::u16string generic_u16string() const;

std::u32string generic_u32string() const;

// 30.11.7.4.8, compare

int compare(const path& p) const noexcept;

int compare(const string_type& s) const;

int compare(basic_string_view<value_type> s)

const;

int compare(const value_type* s) const;

// 30.11.7.4.9, decomposition

path root_name() const;

path root_directory() const;

path root_path() const;

path relative_path() const;

path parent_path() const;

path filename() const;

path stem() const;

path extension() const;

// 30.11.7.4.10, query

[[nodiscard]] bool empty() const noexcept;

bool has_root_name() const;

bool has_root_directory() const;

bool has_root_path() const;

bool has_relative_path() const;

bool has_parent_path() const;

bool has_filename() const;

bool has_stem() const;

bool has_extension() const;

bool is_absolute() const;

bool is_relative() const;

§ 30.11.7

1116

// 30.11.7.4.11, generation

path lexically_normal() const;

path lexically_relative(const path& base) const;

path lexically_proximate(const path& base) const;

// 30.11.7.5, iterators

class iterator;

using const_iterator = iterator;

iterator begin() const;

iterator end() const;

};

}

value_type is a typedef for the operating system dependent encoded character type used to represent

pathnames.

The value of the preferred_separator member is the operating system dependent preferred-separator

character (30.11.7.1).

[ Example: For POSIX-based operating systems, value_type is char and preferred_separator is the slash

character (’/’). For Windows-based operating systems, value_type is wchar_t and preferred_separator

is the backslash character (L’\\’).

— end example ]

30.11.7.1

Generic pathname format

[fs.path.generic]

pathname:

root-nameopt root-directoryopt relative-path

root-name:

operating system dependent sequences of characters

implementation-defined sequences of characters

root-directory:

directory-separator

relative-path:

filename

filename directory-separator relative-path

an empty path

filename:

non-empty sequence of characters other than directory-separator characters

directory-separator:

preferred-separator directory-separatoropt

fallback-separator directory-separatoropt

preferred-separator:

operating system dependent directory separator character

fallback-separator:

/, if preferred-separator is not /

A filename is the name of a file. Filenames dot and dot-dot, consisting solely of one and two period characters

respectively, have special meaning. The following characteristics of filenames are operating system dependent:

(1.1)

—

The permitted characters. [Example: Some operating systems prohibit the ASCII control characters

(0x00 - 0x1F) in filenames.

— end example ]

[Note: For wide portability, users may wish to limit

filename characters to the POSIX Portable Filename Character Set:

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

a b c d e f g h i j k l m n o p q r s t u v w x y z

0 1 2 3 4 5 6 7 8 9 .

_ - —end note ]

(1.2)

—

The maximum permitted length.

(1.3)

—

Filenames that are not permitted.

(1.4)

—

Filenames that have special meaning.

(1.5)

—

Case awareness and sensitivity during path resolution.

(1.6)

—

Special rules that may apply to file types other than regular files, such as directories.

§ 30.11.7.1

1117

Except in a root-name, multiple successive directory-separator characters are considered to be the same as

one directory-separator character.

The filename dot is treated as a reference to the current directory. The filename dot-dot is treated as a reference

to the parent directory. What the filename dot-dot refers to relative to root-directory is implementation-defined.

Specific filenames may have special meanings for a particular operating system.

A root-name identifies the starting location for pathname resolution (30.11.7). If there are no operating

system dependent root-names, at least one implementation-defined root-name is required.

[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 disk drive.

— end note ]

If a root-name is otherwise ambiguous, the possibility with the longest sequence of characters is chosen.

[ Note: On a POSIX-like operating system, it is impossible to have a root-name and a relative-path without

an intervening root-directory element.

— end note ]

Normalization of a generic format pathname means:

1. If the path is empty, stop.

2. Replace each slash character in the root-name with a preferred-separator.

3. Replace each directory-separator with a preferred-separator. [ Note: The generic pathname grammar

(30.11.7.1) defines directory-separator as one or more slashes and preferred-separator s.

— end note ]

4. Remove each dot filename and any immediately following directory-separator.

5. As long as any appear, remove a non-dot-dot filename immediately followed by a directory-separator

and a dot-dot filename, along with any immediately following directory-separator.

6. If there is a root-directory, remove all dot-dot filenames and any directory-separator s immediately

following them.

[Note: These dot-dot filenames attempt to refer to nonexistent parent directories.

— end note ]

7. If the last filename is dot-dot, remove any trailing directory-separator.

8. If the path is empty, add a dot.

The result of normalization is a path in normal form, which is said to be normalized.

30.11.7.2

path conversions

[fs.path.cvt]

30.11.7.2.1

path argument format conversions

[fs.path.fmt.cvt]

[ Note: The format conversions described in this subclause are not applied on POSIX-based operating systems

because on these systems:

(1.1)

—

The generic format is acceptable as a native path.

(1.2)

—

There is no need to distinguish between native format and generic format in function arguments.

(1.3)

—

Paths for regular files and paths for directories share the same syntax.

— end note ]

Several functions are defined to accept detected-format arguments, which are character sequences. A detected-

format argument represents a path using either a pathname in the generic format (30.11.7.1) or a pathname

in the native format (30.11.7). Such an argument is taken to be in the generic format if and only if it matches

the generic format and is not acceptable to the operating system as a native path.

[Note: Some operating systems may have no unambiguous way 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. An implementation for an operating system where disambiguation is required is permitted

to distinguish between the formats.

— end note ]

Pathnames are converted as needed between the generic and native formats in an operating-system-dependent

manner. Let G(n) and N(g) in a mathematical sense be the implementation’s functions that convert native-

to-generic and generic-to-native formats respectively. If g=G(n) for some n, then G(N(g))=g; if n=N(g) for

some g, then N(G(n))=n. [ Note: Neither G nor N need be invertible.

— end note ]

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 its last element is a directory-separator, otherwise it shall be

treated as a path to a regular file.

§ 30.11.7.2.1

1118

[Note: A path stores a native format pathname (30.11.7.4.6) and acts as if it also stores a generic format

pathname, related as given below. The implementation may generate the generic format pathname based on

the native format pathname (and possibly other information) when requested.

— end note ]

When a path is constructed from or is assigned a single representation separate from any path, the other

representation is selected by the appropriate conversion function (G or N ).

When the (new) value p of one representation of a path is derived from the representation of that or another

path, a value q is chosen for the other representation. The value q converts to p (by G or N as appropriate)

if any such value does so; q is otherwise unspecified. [ Note: If q is the result of converting any path at all, it

is the result of converting p.

— end note ]

30.11.7.2.2

path type and encoding conversions

[fs.path.type.cvt]

The native encoding of a narrow character string is the operating system dependent current encoding for

pathnames (30.11.7). The native encoding for wide character strings is the implementation-defined execution

wide-character set encoding (5.3).

For member function arguments that take character sequences representing paths and for member functions

returning strings, value type and encoding conversion is performed if the value type of the argument or return

value differs from path::value_type. For the argument or return value, the method of conversion and the

encoding to be converted to is determined by its value type:

—

(2.1)

char: The encoding is the native narrow encoding. The method of conversion, if any, is operating

system dependent.

[Note: For POSIX-based operating systems path::value_type is char so no

conversion from char value type arguments or to char value type return values is performed. For

Windows-based operating systems, the native narrow encoding is determined by calling a Windows API

function.

— end note ] [ Note: This results in behavior identical to other C and C++ standard library

functions that perform file operations using narrow character strings to identify paths. Changing this

behavior would be surprising and error prone.

— end note ]

(2.2)

—

wchar_t: The encoding is the native wide encoding. The method of conversion is unspecified. [ Note:

For Windows-based operating systems path::value_type is wchar_t so no conversion from wchar_t

value type arguments or to wchar_t value type return values is performed.

— end note ]

(2.3)

—

char16_t: The encoding is UTF-16. The method of conversion is unspecified.

(2.4)

—

char32_t: The encoding is UTF-32. The method of conversion is unspecified.

If the encoding being converted to has no representation for source characters, the resulting converted

characters, if any, are unspecified. Implementations should not modify member function arguments if already

of type path::value_type.

30.11.7.3

path requirements

[fs.path.req]

In addition to the requirements (30.11.4), function template parameters named Source shall be one of:

(1.1)

—

basic_string<EcharT, traits, Allocator>. A function argument const Source& source shall

have an effective range [source.begin(), source.end()).

(1.2)

—

basic_string_view<EcharT, traits>. A function argument const Source& source shall have an

effective range [source.begin(), source.end()).

—

(1.3)

A type meeting the input iterator requirements that iterates over a NTCTS. The value type shall

be an encoded character type. A function argument const Source& source shall have an effective

range [source, end) where end is the first iterator value with an element value equal to iterator_-

traits<Source>::value_type().

—

(1.4)

A character array that after array-to-pointer decay results in a pointer to the start of a NTCTS. The

value type shall be an encoded character type. A function argument const Source& source shall have

an effective range [source, end) where end is the first iterator value with an element value equal to

iterator_traits<decay_t<Source>>::value_type().

Functions taking template parameters named Source shall not participate in overload resolution unless either

(2.1)

—

Source is a specialization of basic_string or basic_string_view, or

(2.2)

—

the qualified-id iterator_traits<decay_t<Source>>::value_type is valid and denotes a possibly

const encoded character type (17.9.2).

§ 30.11.7.3

1119

[Note: See path conversions (30.11.7.2) for how the value types above and their encodings convert to

path::value_type and its encoding. — end note ]

Arguments of type Source shall not be null pointers.

30.11.7.4

path members

[fs.path.member]

30.11.7.4.1

path constructors

[fs.path.construct]

path() noexcept;

Effects: Constructs an object of class path.

Postconditions: empty() == true.

path(const path& p);

path(path&& p) noexcept;

Effects: Constructs an object of class path having the same pathname in the native and generic formats,

respectively, as the original value of p. In the second form, p is left in a valid but unspecified state.

path(string_type&& source, format fmt = auto_format);

Effects: Constructs an object of class path for which the pathname in the detected-format of source

has the original value of source (30.11.7.2.1), converting format if required (30.11.7.2.1). source is

left in a valid but unspecified state.

template<class Source>

path(const Source& source, format fmt = auto_format);

template<class InputIterator>

path(InputIterator first, InputIterator last, format fmt = auto_format);

Effects: Let s be the effective range of source (30.11.7.3) or the range [first, last), with the

encoding converted if required (30.11.7.2). Finds the detected-format of s (30.11.7.2.1) and constructs

an object of class path for which the pathname in that format is s.

template<class Source>

path(const Source& source, const locale& loc, format fmt = auto_format);

template<class InputIterator>

path(InputIterator first, InputIterator last, const locale& loc, format fmt = auto_format);

Requires: The value type of Source and InputIterator is char.

Effects: Let s be the effective range of source or the range [first, last), after converting the

encoding as follows:

(7.1)

—

If value_type is wchar_t, converts to the native wide encoding (30.11.7.2.2) using the codecvt<

wchar_t, char, mbstate_t> facet of loc.

(7.2)

—

Otherwise a conversion is performed using the codecvt<wchar_t, char, mbstate_t> facet of

loc, and then a second conversion to the current narrow encoding.

Finds the detected-format of s (30.11.7.2.1) and constructs an object of class path for which the

pathname in that format is s.

[Example: A string is to be read from a database that is encoded in ISO/IEC 8859-1, and used to

create a directory:

namespace fs = std::filesystem;

std::string latin1_string = read_latin1_data();

codecvt_8859_1<wchar_t> latin1_facet;

std::locale latin1_locale(std::locale(), latin1_facet);

fs::create_directory(fs::path(latin1_string, latin1_locale));

For POSIX-based operating systems, the path is constructed by first using latin1_facet to convert

ISO/IEC 8859-1 encoded latin1_string to a wide character string in the native wide encoding

(30.11.7.2.2). The resulting wide string is then converted to a narrow character pathname string in the

current native narrow encoding. If the native wide encoding is UTF-16 or UTF-32, and the current

native narrow encoding is UTF-8, all of the characters in the ISO/IEC 8859-1 character set will be

converted to their Unicode representation, but for other native narrow encodings some characters may

have no representation.

30.11.7.4.1

1120

For Windows-based operating systems, the path is constructed by using latin1_facet to convert

ISO/IEC 8859-1 encoded latin1_string to a UTF-16 encoded wide character pathname string. All of

the characters in the ISO/IEC 8859-1 character set will be converted to their Unicode representation.

— end example ]

30.11.7.4.2

path assignments

[fs.path.assign]

path& operator=(const path& p);

Effects: If *this and p are the same object, has no effect. Otherwise, sets both respective pathnames

of *this to the respective pathnames of p.

Returns: *this.

path& operator=(path&& p) noexcept;

Effects: If *this and p are the same object, has no effect. Otherwise, sets both respective pathnames

of *this to the respective pathnames of p. p is left in a valid but unspecified state. [Note: A valid

implementation is swap(p).

— end note ]

Returns: *this.

path& operator=(string_type&& source);

path& assign(string_type&& source);

Effects: Sets the pathname in the detected-format of source to the original value of source. source

is left in a valid but unspecified state.

Returns: *this.

template<class Source>

path& operator=(const Source& source);

template<class Source>

path& assign(const Source& source);

template<class InputIterator>

path& assign(InputIterator first, InputIterator last);

Effects: Let s be the effective range of source (30.11.7.3) or the range [first, last), with the

encoding converted if required (30.11.7.2). Finds the detected-format of s (30.11.7.2.1) and sets the

pathname in that format to s.

Returns: *this.

30.11.7.4.3

path appends

[fs.path.append]

The append operations use operator/= to denote their semantic effect of appending preferred-separator

when needed.

path& operator/=(const path& p);

Effects: If p.is_absolute() || (p.has_root_name() && p.root_name() != root_name()), then

operator=(p).

Otherwise, modifies *this as if by these steps:

(3.1)

—

If p.has_root_directory(), then removes any root directory and relative path from the generic

format pathname. Otherwise, if !has_root_directory() && is_absolute() is true or if has_-

filename() is true, then appends path::preferred_separator to the generic format pathname.

(3.2)

—

Then appends the native format pathname of p, omitting any root-name from its generic format

pathname, to the native format pathname.

[Example: Even if //host is interpreted as a root-name, both of the paths path("//host")/"foo"

and path("//host/")/"foo" equal "//host/foo".

Expression examples:

// On POSIX,

path("foo") / "";

// yields "foo/"

path("foo") / "/bar"; // yields "/bar"

// On Windows, backslashes replace slashes in the above yields

§ 30.11.7.4.3

1121

// On Windows,

path("foo") / "c:/bar";

// yields "c:/bar"

path("foo") / "c:";

// yields "c:"

path("c:") / "";

// yields "c:"

path("c:foo") / "/bar";

// yields "c:/bar"

path("c:foo") / "c:bar"; // yields "c:foo/bar"

— end example ]

Returns: *this.

template<class Source>

path& operator/=(const Source& source);

template<class Source>

path& append(const Source& source);

Effects: Equivalent to: return operator/=(path(source));

template<class InputIterator>

path& append(InputIterator first, InputIterator last);

Effects: Equivalent to: return operator/=(path(first, last));

30.11.7.4.4

path concatenation

[fs.path.concat]

path& operator+=(const path& x);

path& operator+=(const string_type& x);

path& operator+=(basic_string_view<value_type> x);

path& operator+=(const value_type* x);

path& operator+=(value_type x);

template<class Source>

path& operator+=(const Source& x);

template<class EcharT>

path& operator+=(EcharT x);

template<class Source>

path& concat(const Source& x);

Effects: Appends path(x).native() to the pathname in the native format.

[Note: This directly

manipulates the value of native() and may not be portable between operating systems.

— end note ]

Returns: *this.

template<class InputIterator>

path& concat(InputIterator first, InputIterator last);

Effects: Equivalent to: return *this += path(first, last);

30.11.7.4.5

path modifiers

[fs.path.modifiers]

void clear() noexcept;

Postconditions: empty() == true.

path& make_preferred();

Effects: Each directory-separator of the pathname in the generic format is converted to preferred-

separator.

Returns: *this.

[ Example:

path p("foo/bar");

std::cout << p << ’\n’;

p.make_preferred();

std::cout << p << ’\n’;

On an operating system where preferred-separator is a slash, the output is:

"foo/bar"

On an operating system where preferred-separator is a backslash, the output is:

§ 30.11.7.4.5

1122

"foo/bar"

"foo\bar"

— end example ]

path& remove_filename();

Postconditions: !has_filename().

Effects: Remove the generic format pathname of filename() from the generic format pathname.

Returns: *this.

[ Example:

path("foo/bar").remove_filename(); // yields "foo/"

path("foo/").remove_filename();

// yields "foo/"

path("/foo").remove_filename();

// yields "/"

path("/").remove_filename();

// yields "/"

— end example ]

path& replace_filename(const path& replacement);

Effects: Equivalent to:

remove_filename();

operator/=(replacement);

Returns: *this.

[ Example:

path("/foo").replace_filename("bar");

// yields "/bar" on POSIX

path("/").replace_filename("bar");

// yields "/bar" on POSIX

— end example ]

path& replace_extension(const path& replacement = path());

Effects:

(12.1)

—

Any existing extension()(30.11.7.4.9) is removed from the pathname in the generic format, then

(12.2)

—

If replacement is not empty and does not begin with a dot character, a dot character is appended

to the pathname in the generic format, then

(12.3)

—

operator+=(replacement);.

Returns: *this.

void swap(path& rhs) noexcept;

Effects: Swaps the contents (in all formats) of the two paths.

Complexity: Constant time.

30.11.7.4.6

path native format observers

[fs.path.native.obs]

The string returned by all native format observers is in the native pathname format (30.11.7).

const string_type& native() const noexcept;

Returns: The pathname in the native format.

const value_type* c_str() const noexcept;

Effects: Equivalent to: return native().c_str();

operator string_type() const;

Returns: native().

[Note: Conversion to string_type is provided so that an object of class path can be given as an

argument to existing standard library file stream constructors and open functions.

— end note ]

§ 30.11.7.4.6

1123

template<class EcharT, class traits = char_traits<EcharT>,

class Allocator = allocator<EcharT>>

basic_string<EcharT, traits, Allocator>

string(const Allocator& a = Allocator()) const;

Returns: native().

Remarks: All memory allocation, including for the return value, shall be performed by a. Conversion,

if any, is specified by 30.11.7.2.

std::string string() const;

std::wstring wstring() const;

std::string u8string() const;

std::u16string u16string() const;

std::u32string u32string() const;

Returns: native().

Remarks: Conversion, if any, is performed as specified by 30.11.7.2. The encoding of the string returned

by u8string() is always UTF-8.

30.11.7.4.7

path generic format observers

[fs.path.generic.obs]

Generic format observer functions return strings formatted according to the generic pathname format

(30.11.7.1). A single slash (’/’) character is used as the directory-separator.

[ Example: On an operating system that uses backslash as its preferred-separator,

path("foo\\bar").generic_string()

returns "foo/bar".

— end example ]

template<class EcharT, class traits = char_traits<EcharT>,

class Allocator = allocator<EcharT>>

basic_string<EcharT, traits, Allocator>

generic_string(const Allocator& a = Allocator()) const;

Returns: The pathname in the generic format.

Remarks: All memory allocation, including for the return value, shall be performed by a. Conversion,

if any, is specified by 30.11.7.2.

std::string generic_string() const;

std::wstring generic_wstring() const;

std::string generic_u8string() const;

std::u16string generic_u16string() const;

std::u32string generic_u32string() const;

Returns: The pathname in the generic format.

Remarks: Conversion, if any, is specified by 30.11.7.2. The encoding of the string returned by generic_-

u8string() is always UTF-8.

30.11.7.4.8

path compare

[fs.path.compare]

int compare(const path& p) const noexcept;

Returns:

(1.1)

—

A value less than 0, if native() for the elements of *this are lexicographically less than native()

for the elements of p; otherwise,

(1.2)

—

a value greater than 0, if native() for the elements of *this are lexicographically greater than

native() for the elements of p; otherwise,

(1.3)

—

Remarks: The elements are determined as if by iteration over the half-open range [begin(), end())

for *this and p.

int compare(const string_type& s) const

int compare(basic_string_view<value_type> s) const;

Returns: compare(path(s)).

§ 30.11.7.4.8

1124

int compare(const value_type* s) const

Returns: compare(path(s)).

30.11.7.4.9

path decomposition

[fs.path.decompose]

path

root_name() const;

Returns: root-name, if the pathname in the generic format includes root-name, otherwise path().

path

root_directory() const;

Returns: root-directory, if the pathname in the generic format includes root-directory, otherwise path().

path

root_path() const;

Returns: root_name() / root_directory().

path

relative_path() const;

Returns: A path composed from the pathname in the generic format, if empty() is false, beginning

with the first filename after root-path. Otherwise, path().

path

parent_path() const;

Returns: *this if has_relative_path() is false, otherwise a path whose generic format pathname

is the longest prefix of the generic format pathname of *this that produces one fewer element in its

iteration.

path

filename() const;

Returns: relative_path().empty() ? path() :

*--end().

[ Example:

path("/foo/bar.txt").filename();

// yields "bar.txt"

path("/foo/bar").filename();

// yields "bar"

path("/foo/bar/").filename();

// yields ""

path("/").filename();

// yields ""

path("//host").filename();

// yields ""

path(".").filename();

// yields "."

path("..").filename();

// yields ".."

— end example ]

path

stem() const;

Returns: Let f be the generic format pathname of filename(). Returns a path whose pathname in

the generic format is

(8.1)

—

f, if it contains no periods other than a leading period or consists solely of one or two periods;

(8.2)

—

otherwise, the prefix of f ending before its last period.

[ Example:

std::cout << path("/foo/bar.txt").stem(); // outputs "bar"

path p = "foo.bar.baz.tar";

for (; !p.extension().empty(); p = p.stem())

std::cout << p.extension() << ’\n’;

// outputs: .tar

// .baz

// .bar

— end example ]

path

extension() const;

Returns: A path whose pathname in the generic format is the suffix of filename() not included in

stem().

[ Example:

path("/foo/bar.txt").extension();

// yields ".txt" and stem() is "bar"

path("/foo/bar").extension();

// yields "" and stem() is "bar"

§ 30.11.7.4.9

1125

path("/foo/.profile").extension(); // yields "" and stem() is ".profile"

path(".bar").extension();

// yields "" and stem() is ".bar"

path("..bar").extension();

// yields ".bar" and stem() is "."

— end example ]

[Note: The period is included in the return value so that it is possible to distinguish between no

extension and an empty extension.

— end note ]

[Note: On non-POSIX operating systems, for a path p, it may not be the case that p.stem() +

p.extension() == p.filename(), even though the generic format pathnames are the same. — end

note ]

30.11.7.4.10

path query

[fs.path.query]

[[nodiscard]] bool empty() const noexcept;

Returns: true if the pathname in the generic format is empty, else false.

bool

has_root_path() const;

Returns: !root_path().empty().

bool

has_root_name() const;

Returns: !root_name().empty().

bool

has_root_directory() const;

Returns: !root_directory().empty().

bool

has_relative_path() const;

Returns: !relative_path().empty().

bool

has_parent_path() const;

Returns: !parent_path().empty().

bool

has_filename() const;

Returns: !filename().empty().

bool

has_stem() const;

Returns: !stem().empty().

bool

has_extension() const;

Returns: !extension().empty().

bool

is_absolute() const;

Returns: true if the pathname in the native format contains an absolute path (30.11.7), else false.

[Example: path("/").is_absolute() is true for POSIX-based operating systems, and false for

Windows-based operating systems.

— end example ]

bool

is_relative() const;

Returns: !is_absolute().

30.11.7.4.11

path generation

[fs.path.gen]

path lexically_normal() const;

Returns: A path whose pathname in the generic format is the normal form (30.11.7.1) of the pathname

in the generic format of *this.

[ Example:

assert(path("foo/./bar/..").lexically_normal() == "foo/");

assert(path("foo/.///bar/../").lexically_normal() == "foo/");

The above assertions will succeed. On Windows, the returned path’s directory-separator characters will

be backslashes rather than slashes, but that does not affect path equality.

— end example ]

§ 30.11.7.4.11

1126

path

lexically_relative(const path& base) const;

Returns: *this made relative to base. Does not resolve (30.11.7) symlinks. Does not first normalize

(30.11.7.1) *this or base.

Effects: If root_name() != base.root_name() is true or is_absolute() != base.is_absolute()

is true or !has_root_directory() && base.has_root_directory() is true, returns path(). De-

termines the first mismatched element of *this and base as if by:

auto [a, b] = mismatch(begin(), end(), base.begin(), base.end());

Then,

(4.1)

—

if a

== end() and b == base.end(), returns path("."); otherwise

(4.2)

—

let n be the number of filename elements in [b, base.end()) that are not dot or dot-dot minus

the number that are dot-dot. If n<0, returns path(); otherwise

(4.3)

—

returns an object of class path that is default-constructed, followed by

(4.3.1)

—

application of operator/=(path("..")) n times, and then

(4.3.2)

—

application of operator/= for each element in [a, end()).

[ Example:

assert(path("/a/d").lexically_relative("/a/b/c") == "../../d");

assert(path("/a/b/c").lexically_relative("/a/d") == "../b/c");

assert(path("a/b/c").lexically_relative("a") == "b/c");

assert(path("a/b/c").lexically_relative("a/b/c/x/y") == "../..");

assert(path("a/b/c").lexically_relative("a/b/c") == ".");

assert(path("a/b").lexically_relative("c/d") == "../../a/b");

The above assertions will succeed. On Windows, the returned path’s directory-separator characters will

be backslashes rather than slashes, but that does not affect path equality.

— end example ]

[Note: If symlink following semantics are desired, use the operational function relative().

— end

note ]

[Note: If normalization (30.11.7.1) is needed to ensure consistent matching of elements, apply

lexically_normal() to *this, base, or both. — end note ]

path

lexically_proximate(const path& base) const;

Returns: If the value of lexically_relative(base) is not an empty path, return it. Otherwise return

*this.

[Note: If symlink following semantics are desired, use the operational function proximate().

— end

note ]

[Note: If normalization (30.11.7.1) is needed to ensure consistent matching of elements, apply

lexically_normal() to *this, base, or both. — end note ]

30.11.7.5

path iterators

[fs.path.itr]

Path iterators iterate over the elements of the pathname in the generic format (30.11.7.1).

A path::iterator is a constant iterator satisfying all the requirements of a bidirectional iterator (27.2.6)

except that, for dereferenceable iterators a and b of type path::iterator with a == b, there is no requirement

that *a and *b are bound to the same object. Its value_type is path.

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

object.

For the elements of the pathname in the generic format, the forward traversal order is as follows:

(4.1)

—

The root-name element, if present.

(4.2)

—

The root-directory element, if present. [ Note: The generic format is required to ensure lexicographical

comparison works correctly.

— end note ]

(4.3)

—

Each successive filename element, if present.

(4.4)

—

An empty element, if a trailing non-root directory-separator is present.

The backward traversal order is the reverse of forward traversal.

§ 30.11.7.5

1127

iterator begin() const;

Returns: An iterator for the first present element in the traversal list above. If no elements are present,

the end iterator.

iterator end() const;

Returns: The end iterator.

30.11.7.6

path non-member functions

[fs.path.nonmember]

void swap(path& lhs, path& rhs) noexcept;

Effects: Equivalent to lhs.swap(rhs).

size_t hash_value (const path& p) noexcept;

Returns: A hash value for the path p. If for two paths, p1 ==

p2 then hash_value(p1) == hash_-

value(p2).

bool

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

Returns: lhs.compare(rhs) < 0.

bool

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

Returns: !(rhs < lhs).

bool

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

Returns: rhs < lhs.

bool

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

Returns: !(lhs < rhs).

bool

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

Returns: !(lhs < rhs) && !(rhs < lhs).

[ Note: Path equality and path equivalence have different semantics.

(8.1)

—

Equality is determined by the path non-member operator==, which considers the two path’s

lexical representations only. [ Example: path("foo") == "bar" is never true.

— end example ]

(8.2)

—

Equivalence is determined by the equivalent() non-member function, which determines if two

paths resolve (30.11.7) to the same file system entity.

[Example: equivalent("foo", "bar")

will be true when both paths resolve to the same file.

— end example ]

Programmers wishing to determine if two paths are “the same” must decide if “the same” means

“the same representation” or “resolve to the same actual file”, and choose the appropriate function

accordingly.

— end note ]

bool

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

Returns: !(lhs == rhs).

path

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

Effects: Equivalent to: return path(lhs) /= rhs;

30.11.7.6.1

path inserter and extractor

[fs.path.io]

template<class charT, class traits>

basic_ostream<charT, traits>&

operator<<(basic_ostream<charT, traits>& os, const path& p);

Effects: Equivalent to os << quoted(p.string<charT, traits>()). [ Note: The quoted function is

described in 30.7.8.

— end note ]

Returns: os.

§ 30.11.7.6.1

1128

template<class charT, class traits>

basic_istream<charT, traits>&

operator>>(basic_istream<charT, traits>& is, path& p);

Effects: Equivalent to:

basic_string<charT, traits> tmp;

is >> quoted(tmp);

p = tmp;

Returns: is.

30.11.7.6.2

path factory functions

[fs.path.factory]

template<class Source>

path u8path(const Source& source);

template<class InputIterator>

path u8path(InputIterator first, InputIterator last);

Requires: The source and [first, last) sequences are UTF-8 encoded. The value type of Source

and InputIterator is char.

Returns:

(2.1)

—

If value_type is char and the current native narrow encoding (30.11.7.2.2) is UTF-8, return

path(source) or path(first, last); otherwise,

(2.2)

—

if value_type is wchar_t and the native wide encoding is UTF-16, or if value_type is char16_t

or char32_t, convert source or [first, last) to a temporary, tmp, of type string_type and

return path(tmp); otherwise,

(2.3)

—

convert source or [first, last) to a temporary, tmp, of type u32string and return path(tmp).

Remarks: Argument format conversion (30.11.7.2.1) applies to the arguments for these functions. How

Unicode encoding conversions are performed is unspecified.

[Example: A string is to be read from a database that is encoded in UTF-8, and used to create a

directory using the native encoding for filenames:

namespace fs = std::filesystem;

std::string utf8_string = read_utf8_data();

fs::create_directory(fs::u8path(utf8_string));

For POSIX-based operating systems with the native narrow encoding set to UTF-8, no encoding or

type conversion occurs.

For POSIX-based operating systems with the native narrow encoding not set to UTF-8, a conversion

to UTF-32 occurs, followed by a conversion to the current native narrow encoding. Some Unicode

characters may have no native character set representation.

For Windows-based operating systems a conversion from UTF-8 to UTF-16 occurs. — end example ]

30.11.8

Class filesystem_error

[fs.class.filesystem_error]

namespace std::filesystem {

class filesystem_error : public system_error {

public:

filesystem_error(const string& what_arg, error_code ec);

filesystem_error(const string& what_arg,

const path& p1, error_code ec);

filesystem_error(const string& what_arg,

const path& p1, const path& p2, error_code ec);

const path& path1() const noexcept;

const path& path2() const noexcept;

const char* what() const noexcept override;

};

}

The class filesystem_error defines the type of objects thrown as exceptions to report file system errors

from functions described in this subclause.

§ 30.11.8

1129

30.11.8.1

filesystem_error members

[fs.filesystem_error.members]

Constructors are provided that store zero, one, or two paths associated with an error.

filesystem_error(const string& what_arg, error_code ec);

Postconditions: The postconditions of this function are indicated in Table 119.

Table 119 — filesystem_error(const string&, error_code) effects

Expression

Value

runtime_error::what() what_arg.c_str()

code()

path1().empty()

true

path2().empty()

true

filesystem_error(const string& what_arg, const path& p1, error_code ec);

Postconditions: The postconditions of this function are indicated in Table 120.

Table 120 — filesystem_error(const string&, const path&, error_code) effects

Expression

Value

runtime_error::what() what_arg.c_str()

code()

path1()

Reference to stored copy of p1

path2().empty()

true

filesystem_error(const string& what_arg, const path& p1, const path& p2, error_code ec);

Postconditions: The postconditions of this function are indicated in Table 121.

Table 121 — filesystem_error(const string&, const path&, const path&, error_code) effects

Expression

Value

runtime_error::what() what_arg.c_str()

code()

path1()

Reference to stored copy of p1

path2()

Reference to stored copy of p2

const path& path1() const noexcept;

Returns: A reference to the copy of p1 stored by the constructor, or, if none, an empty path.

const path& path2() const noexcept;

Returns: A reference to the copy of p2 stored by the constructor, or, if none, an empty path.

const char* what() const noexcept override;

Returns: A string containing runtime_error::what(). The exact format is unspecified. Implementa-

tions should include the system_error::what() string and the pathnames of path1 and path2 in the

native format in the returned string.

30.11.9

Enumerations

[fs.enum]

30.11.9.1

Enum path::format

[fs.enum.path.format]

This enum specifies constants used to identify the format of the character sequence, with the meanings listed

in Table 122.

30.11.9.2

Enum class file_type

[fs.enum.file_type]

This enum class specifies constants used to identify file types, with the meanings listed in Table 123.

§ 30.11.9.2

1130

Table 122 — Enum path::format

Name

Meaning

native_format

The native pathname format.

generic_format

The generic pathname format.

auto_format

The interpretation of the format of the character sequence is

implementation-defined. The implementation may inspect the con-

tent of the character sequence to determine the format. [ Note: For

POSIX-based systems, native and generic formats are equivalent

and the character sequence should always be interpreted in the

same way. — end note ]

Table 123 — Enum class file_type

Constant

Meaning

none

The type of the file has not been determined or an error occurred while

trying to determine the type.

not_found

Pseudo-type indicating the file was not found. [ Note: The file not being

found is not considered an error while determining the type of a file.

— end

note ]

regular

Regular file

Working Draft, Standard for Programming Language C++ (N4713, 2017 year) - page 38