ISO/IEC TS 18822:2015

Programming languages - C++ - File System Technical Specification

ISO/IEC TS 18822:2015 specifies requirements for implementations of an interface that computer programs written in the C++ programming language may use to perform operations on file systems and their components, such as paths, regular files, and directories. This Technical Specification is applicable to information technology systems that can access hierarchical file systems, such as those with operating systems that conform to the POSIX (3) interface. This Technical Specification is applicable only to vendors who wish to provide the interface it describes.

Languages de programmation — C++ — Spécification technique de système de fichiers

General Information

• Status: Withdrawn
• Publication Date: 17-Jun-2015
• Withdrawal Date: 17-Jun-2015
• ICS: 35.060 - Languages used in information technology
• Technical Committee: ISO/IEC JTC 1/SC 22 - Programming languages, their environments and system software interfaces
• Drafting Committee: ISO/IEC JTC 1/SC 22/WG 21 - C++
• Current Stage: 9599 - Withdrawal of International Standard
• Start Date: 14-Feb-2019
• Completion Date: 30-Oct-2025

Relations

• Consolidated By: ISO 25197:2020 - Small craft - Electrical/electronic control systems for steering, shift and throttle
• Effective Date: 06-Jun-2022

Standards Content (Sample)

TECHNICAL ISO/IEC
SPECIFICATION TS
First edition
2015-07-01
Programming languages — C++ — File
System Technical Specification
Languages de programmation — C++ — Spécification technique de
système de fichiers
Reference number
©
ISO/IEC 2015
©  ISO/IEC 2015
All rights reserved. Unless otherwise specified, no part of this publication may be reproduced or utilized otherwise in any form or by any
means, electronic or mechanical, including photocopying, or posting on the internet or an intranet, without prior written permission.
Permission can be requested from either ISO at the address below or ISO’s member body in the country of the requester.
ISO copyright office
Case postale 56  CH-1211 Geneva 20
Tel. + 41 22 749 01 11
Fax + 41 22 749 09 47
E-mail [e-mail]
Web www.iso.org
Published in Switzerland
ii © ISO/IEC 2015 – All rights reserved

Foreword
ISO (the International Organization for Standardization) and IEC (the International Electrotechnical
Commission) form the specialized system for worldwide standardization. National bodies that are members of
ISO or IEC participate in the development of International Standards through technical committees
established by the respective organization to deal with particular fields of technical activity. ISO and IEC
technical committees collaborate in fields of mutual interest. Other international organizations, governmental
and non-governmental, in liaison with ISO and IEC, also take part in the work. In the field of information
technology, ISO and IEC have established a joint technical committee, ISO/IEC JTC 1.
International Standards are drafted in accordance with the rules given in the ISO/IEC Directives, Part 2.
The main task of the joint technical committee is to prepare International Standards. Draft International
Standards adopted by the joint technical committee are circulated to national bodies for voting. Publication as
an International Standard requires approval by at least 75 % of the national bodies casting a vote.
In other circumstances, particularly when there is an urgent market requirement for such documents, the joint
technical committee may decide to publish other types of document:
— an ISO/IEC Publicly Available Specification (ISO/IEC PAS) represents an agreement between technical
experts in an ISO/IEC working group and is accepted for publication if it is approved by more than 50 %
of the members of the parent committee casting a vote;
— an ISO/IEC Technical Specification (ISO/IEC TS) represents an agreement between the members of the
joint technical committee and is accepted for publication if it is approved by 2/3 of the members of the
committee casting a vote.
An ISO/IEC PAS or ISO/IEC TS is reviewed after three years in order to decide whether it will be confirmed for
a further three years, revised to become an International Standard, or withdrawn. If the ISO/IEC PAS or
ISO/IEC TS is confirmed, it is reviewed again after a further three years, at which time it must either be
transformed into an International Standard or be withdrawn.
Attention is drawn to the possibility that some of the elements of this document may be the subject of patent
rights. ISO and IEC shall not be held responsible for identifying any or all such patent rights.
ISO/IEC TS 18822 was prepared by Joint Technical Committee ISO/IEC JTC 1, Information technology,
Subcommittee SC 22, Programming languages, their environments and system software interfaces.

© ISO/IEC 2015 – All rights reserved iii

© ISO/IEC N4100
Contents
Contents
1 Scope
2 Conformance
2.1 POSIX conformance
2.2 Operating system dependent behavior conformance
2.3 File system race behavior
3 Normative references
4 Terms and definitions
4.1 absolute path
4.2 canonical path
4.3 directory
4.4 file
4.5 file system
4.6 file system race
4.7 filename
4.8 hard link
4.9 link
4.10 native encoding
4.11 native pathname format
4.12 NTCTS
4.13 operating system dependent behavior
4.14 parent directory
4.15 path
4.16 pathname
4.17 pathname resolution
4.18 relative path
4.19 symbolic link
5 Requirements
5.1 Namespaces and headers
5.2 Feature test macros
6 Header synopsis
7 Error reporting
8 Classpath
8.1path generic pathname format grammar
8.2path conversions
8.2.1path argument format conversions
8.2.2path type and encoding conversions
8.3path requirements
8.4path members
8.4.1path constructors
8.4.2path assignments
iii
© ISO/IEC 2015 – All rights reserved

© ISO/IEC N4100
8.4.3path appends
8.4.4path concatenation
8.4.5path modifiers
8.4.6path native format observers
8.4.7path generic format observers
8.4.8path compare
8.4.9path decomposition
8.4.10path query
8.5path iterators
8.6path non-member functions
8.6.1path inserter and extractor
8.6.2path factory functions
9 Classfilesystem_error
9.1filesystem_error members
10 Enumerations
10.1 Enum classfile_type
10.2 Enum classcopy_options
10.3 Enum classperms
10.4 Enum classdirectory_options
11 Classfile_status
11.1file_status constructors
11.2file_status observers
11.3file_status modifiers
12 Classdirectory_entry
12.1directory_entry constructors
12.2directory_entry modifiers
12.3directory_entry observers
13 Classdirectory_iterator
13.1directory_iterator members
13.2directory_iterator non-member functions
14 Classrecursive_directory_iterator
14.1recursive_directory_iterator members
14.2recursive_directory_iterator non-member functions
15 Operational functions
15.1 Absolute
15.2 Canonical
15.3 Copy
15.4 Copy file
15.5 Copy symlink
15.6 Create directories
15.7 Create directory
15.8 Create directory symlink
15.9 Create hard link
15.10 Create symlink
iv
© ISO/IEC 2015 – All rights reserved

© ISO/IEC N4100
15.11 Current path
15.12 Exists
15.13 Equivalent
15.14 File size
15.15 Hard link count
15.16 Is block file
15.17 Is character file
15.18 Is directory
15.19 Is empty
15.20 Is fifo
15.21 Is other
15.22 Is regular file
15.23 Is socket
15.24 Is symlink
15.25 Last write time
15.26 Permissions
15.27 Read symlink
15.28 Remove
15.29 Remove all
15.30 Rename
15.31 Resize file
15.32 Space
15.33 Status
15.34 Status known
15.35 Symlink status
15.36 System complete
15.37 Temporary directory path
v
© ISO/IEC 2015 – All rights reserved

© ISO/IEC N4100
1 Scope [fs.scope]
This Technical Specification specifies requirements for implementations of an interface that computer
programs written in the C++ programming language may use to perform operations on file systems and
their components, such as paths, regular files, and directories. This Technical Specification is applicable
to information technology systems that can access hierarchical file systems, such as those with operating
systems that conform to the POSIX (3) interface. This Technical Specification is applicable only to
vendors who wish to provide the interface it describes.
2 Conformance [fs.conformance]
Conformance is specified in terms of behavior. Ideal behavior is not always implementable, so the
conformance sub-clauses take that into account.
2.1 POSIX conformance [fs.conform.9945]
Some behavior is specified by reference to POSIX (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 API's. —end note]
Implementations are encouraged to 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 are encouraged to 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 § 7.
[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 discs
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. —end
example]
2.2 Operating system dependent behavior conformance [fs.conform.os]
Some behavior is specified as being operating system dependent (4.13). The operating system an
implementation is dependent upon is implementation defined.
© ISO/IEC 2015 – All rights reserved

© ISO/IEC N4100
It is permissible for an implementation to be dependent upon an operating system emulator rather than
the actual underlying operating system.
2.3 File system race behavior [fs.race.behavior]
Behavior is undefined if calls to functions provided by this Technical Specification introduce a file
system race (4.6).
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]
3 Normative references [fs.norm.ref]
The following referenced documents are indispensable for the application of this document. For dated
references, only the edition cited applies. For undated references, the latest edition of the referenced
document (including any amendments) applies.
• ISO/IEC 14882, Programming Language C++
• ISO/IEC 9945, Information Technology — Portable Operating System Interface (POSIX)
[Note: The programming language and library described in ISO/IEC 14882 is herein called the C++
Standard. References to clauses within the C++ Standard are written as "C++14 §3.2". Section
references are relative to N3936.
The operating system interface described in ISO/IEC 9945 is herein called POSIX. —end note]
This Technical Specification mentions commercially available operating systems for purposes of
[footnote]
exposition.
Unless otherwise specified, the whole of the C++ Standard's Library introduction (C++14 §17) is
included into this Technical Specification by reference.
[footnote]
POSIX® is a registered trademark of The IEEE. MAC OS® is a registered trademark
of Apple Inc. 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.
© ISO/IEC 2015 – All rights reserved

© ISO/IEC N4100
4 Terms and definitions [fs.definitions]
For the purposes of this document, the terms and definitions given in the C++ Standard and the
following apply.
4.1 absolute path [fs.def.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.
4.2 canonical path [fs.def.canonical-path]
An absolute path that has no elements that are symbolic links, and no dot or dot-dot elements (8.1).
4.3 directory [fs.def.directory]
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.
4.4 file [fs.def.file]
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.
4.5 file system [fs.def.filesystem]
A collection of files and certain of their attributes.
4.6 file system race [fs.def.race]
The condition that occurs when multiple threads, processes, or computers interleave access and
modification of the same object within a file system.
4.7 filename [fs.def.filename]
The name of a file. Filenames dot and dot-dot have special meaning. The following characteristics of
filenames are operating system dependent:
• The permitted characters. [Example: Some operating systems prohibit the ASCII control
characters (0x00-0x1F) in filenames. —end example].
• The maximum permitted length.
• Filenames that are not permitted.
© ISO/IEC 2015 – All rights reserved

© ISO/IEC N4100
• 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.
4.8 hard link [fs.def.hardlink]
A link (4.9) 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]
4.9 link [fs.def.link]
A directory entry that associates a filename with a file. A link is either a hard link (4.8) or a symbolic
link (4.19).
4.10 native encoding [fs.def.native.encode]
For narrow character strings, the operating system dependent current encoding for path names. For wide
character strings, the implementation defined execution wide-character set encoding (C++14 §2.3).
4.11 native pathname format [fs.def.native]
The operating system dependent pathname format accepted by the host operating system.
4.12 NTCTS [fs.def.ntcts]
Acronym for "null-terminated character-type sequence". Describes a sequence of values of a given
encoded character type terminated by that type's null character. If the encoded character type is EcharT,
the null character can be constructed by EcharT().
4.13 operating system dependent behavior [fs.def.osdep]
Behavior that is dependent upon the behavior and characteristics of an operating system. See
[fs.conform.os].
4.14 parent directory [fs.def.parent]
When discussing a given directory, the directory that both contains a directory entry for the given
directory and is represented by the filename dot-dot in the given directory.
When discussing other types of files, a directory containing a directory entry for the file under
discussion.
© ISO/IEC 2015 – All rights reserved

© ISO/IEC N4100
This concept does not apply to dot and dot-dot.
4.15 path [fs.def.path]
A sequence of elements that identify the location of a file within a filesystem. The elements are the root-
name , root-directory , and an optional sequence of filenames. The maximum number of elements in
opt opt
the sequence is operating system dependent.
4.16 pathname [fs.def.pathname]
A character string that represents the name of a path. Pathnames are formatted according to the generic
pathname format grammar (8.1) or an operating system dependent native pathname format.
4.17 pathname resolution [fs.def.pathres]
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]
4.18 relative path [fs.def.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: Pathnames"." and"." are relative paths. —end note]
4.19 symbolic link [fs.def.symlink]
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: 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]
5 Requirements [fs.req]
Throughout this Technical Specification, char,wchar_t,char16_t, andchar32_t are collectively
called encoded character types.
Template parameters named EcharT shall be one of the encoded character types.
Template parameters named InputIterator shall meet the C++ Standard's library input iterator
requirements (C++14 §24.2.3) and shall have a value type that is one of the encoded character types.
© ISO/IEC 2015 – All rights reserved

© ISO/IEC N4100
[Note: Use of an encoded character type implies an associated encoding. Since signed char
andunsigned char have no implied encoding, they are not included as permitted types. —end
note]
Template parameters named Allocator shall meet the C++ Standard's library Allocator requirements
(C++14 §17.6.3.5).
5.1 Namespaces and headers [fs.req.namespace]
The components described in this technical specification are experimental and not part of the C++
standard library. All components described in this technical specification are declared in namespace
std::experimental::filesystem::v1 or a sub-namespace thereof unless otherwise specified. The
header described in this technical specification shall import the contents of
std::experimental::filesystem::v1 intostd::experimental::filesystem as if by
namespace std {
namespace experimental {
namespace filesystem {
inline namespace v1 {}
}
}
}
Unless otherwise specified, references to other entities described in this technical specification are
assumed to be qualified with std::experimental::filesystem::v1::, and references to entities
described in the C++ standard are assumed to be qualified with std::.
5.2 Feature test macros [fs.req.macros]
This macro allows users to determine which version of this Technical Specification is supported by
header.
Header shall supply the following macro definition:
#define __cpp_lib_experimental_filesystem   201406
[Note: The value of macro __cpp_lib_experimental_filesystem is yyyymm where yyyy is the year
and mm the month when the version of the Technical Specification was completed. — end note]
6 Header synopsis
[fs.filesystem.synopsis]
namespace std { namespace experimental { namespace filesystem { inline namespace v1 {
class path;
© ISO/IEC 2015 – All rights reserved

© ISO/IEC N4100
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);
template
basic_ostream&
operator<<(basic_ostream& os, const path& p);
template
basic_istream&
operator>>(basic_istream& is, path& p);
template
path u8path(const Source& source);
template
path u8path(InputIterator first, InputIterator last);
class filesystem_error;
class directory_entry;
class directory_iterator;
// enable directory_iterator range-based for statements
directory_iterator begin(directory_iterator iter) noexcept;
directory_iterator end(const directory_iterator&) noexcept;
class recursive_directory_iterator;
// enable recursive_directory_iterator range-based for statements
recursive_directory_iterator begin(recursive_directory_iterator iter) noexcept;
recursive_directory_iterator end(const recursive_directory_iterator&) noexcept;
class file_status;
struct space_info
{
uintmax_t capacity;
uintmax_t free;
uintmax_t available;
};
enum class file_type;
enum class perms;
enum class copy_options;
enum class directory_options;
typedef chrono::time_point file_time_type;
© ISO/IEC 2015 – All rights reserved

© ISO/IEC N4100
// operational functions
path absolute(const path& p, const path& base=current_path());
path canonical(const path& p, const path& base = current_path());
path canonical(const path& p, error_code& ec);
path canonical(const path& p, const path& base, 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;
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 exists(file_status s) noexcept;
bool exists(const path& p);
bool exists(const path& p, error_code& ec) noexcept;
bool equivalent(const path& p1, const path& p2);
© ISO/IEC 2015 – All rights reserved

© ISO/IEC N4100
bool equivalent(const path& p1, const path& p2, 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;
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);
void permissions(const path& p, perms prms, error_code& ec) noexcept;
path read_symlink(const path& p);
path read_symlink(const path& p, error_code& ec);
bool remove(const path& p);
© ISO/IEC 2015 – All rights reserved

© ISO/IEC N4100
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 system_complete(const path& p);
path system_complete(const path& p, error_code& ec);
path temp_directory_path();
path temp_directory_path(error_code& ec);
} } } } // namespaces std::experimental::filesystem::v1
trivial-clock is an implementation-defined type that satisfies the TrivialClock requirements
(C++14 §20.12.3) and that is capable of representing and measuring file time values. Implementations
should ensure that the resolution and range offile_time_type reflect the operating system
dependent resolution and range of file time values.
7 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:
• 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.
© ISO/IEC 2015 – All rights reserved

© ISO/IEC N4100
—end note]
Functions not having an argument of typeerror_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 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. Thefilesystem_error constructor'serror_code argument is set as
appropriate for the specific operating system dependent error.
• Failure to allocate storage is reported by throwing an exception as described in C++14
§17.6.5.12.
• Destructors throw nothing.
Functions having an argument of typeerror_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 error_code& argument is
set as appropriate for the specific operating system dependent error. Otherwise,clear() is
called on the error_code& argument.
8 Classpath [class.path]
An object of class path represents a path (4.15) and contains a pathname (4.16). 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.
namespace std { namespace experimental { namespace filesystem { inline namespace v1 {
class path
{
public:
typedef see below value_type;
typedef basic_string    string_type;
static constexpr value_type      preferred_separator = see below;
// constructors and destructor
path() noexcept;
path(const path& p);
path(path&& p) noexcept;
template
© ISO/IEC 2015 – All rights reserved

© ISO/IEC N4100
path(const Source& source);
template
path(InputIterator first, InputIterator last);
template
path(const Source& source, const locale& loc);
template
path(InputIterator first, InputIterator last, const locale& loc);
~path();
// assignments
path& operator=(const path& p);
path& operator=(path&& p) noexcept;
template
path& operator=(const Source& source);
template
path& assign(const Source& source)
template
path& assign(InputIterator first, InputIterator last);
// appends
path& operator/=(const path& p);
template
path& operator/=(const Source& source);
template
path& append(const Source& source);
template
path& append(InputIterator first, InputIterator last);
// concatenation
path& operator+=(const path& x);
path& operator+=(const string_type& x);
path& operator+=(const value_type* x);
path& operator+=(value_type x);
template
path& operator+=(const Source& x);
template
path& operator+=(EcharT x);
template
path& concat(const Source& x);
template
path& concat(InputIterator first, InputIterator last);
// 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;
// native format observers
const string_type& native() const noexcept;
const value_type* c_str() const noexcept;
operator string_type() const;
template ,
© ISO/IEC 2015 – All rights reserved

© ISO/IEC N4100
class Allocator = allocator >
basic_string
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;
// generic format observers
template ,
class Allocator = allocator >
basic_string
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;
// compare
int compare(const path& p) const noexcept;
int compare(const string_type& s) const;
int compare(const value_type* s) const;
// 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;
// query
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;
// iterators
class iterator;
typedef iterator const_iterator;
iterator begin() const;
iterator end() const;
private:
© ISO/IEC 2015 – All rights reserved

© ISO/IEC N4100
string_type pathname; // exposition only
};
} } } } // namespaces std::experimental::filesystem::v1
value_type is atypedef for the operating system dependent encoded character type used to represent
pathnames.
The value ofpreferred_separator is the operating system dependent preferred-separator character
(8.1).
[Example: For POSIX based operating systems, value_type ischar and
preferred_separator is the slash character (/). For Windows based operating systems,
value_type iswchar_t andpreferred_separator is the backslash character (\). —end
example]
8.1path generic pathname format grammar [path.generic]
pathname:
root-name root-directory relative-path
opt opt
root-directory relative-path
opt
relative-path
root-name:
An operating system dependent name that identifies the starting location for absolute paths.
[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. —end
note]
root-directory:
directory-separator
relative-path:
filename
relative-path directory-separator
relative-path directory-separator filename
filename:
name
dot
dot-dot
© ISO/IEC 2015 – All rights reserved

© ISO/IEC N4100
name:
A sequence of characters other than directory-separator characters.
[Note: Operating systems often place restrictions on the characters that may be used
in a filename. 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]
dot:
The filename consisting solely of a single period character (.).
dot-dot:
The filename consisting solely of two period characters (.).
directory-separator:
slash
slash directory-separator
preferred-separator
preferred-separator directory-separator
preferred-separator:
An operating system dependent directory separator character. May be a synonym for slash.
slash:
The slash character (/).
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.
8.2path conversions [path.cvt]
8.2.1path argument format conversions [path.fmt.cvt]
[Note: The format conversions described in this section are not applied on POSIX or Windows
based operating systems because on these systems:
© ISO/IEC 2015 – All rights reserved

© ISO/IEC N4100
• The generic format is acceptable as a native path.
• There is no need to distinguish between native format and generic format arguments.
• Paths for regular files and paths for directories share the same syntax.
—end note]
Functions arguments that take character sequences representing paths may use the generic pathname
format grammar (8.1) or the native pathname format (4.11). If and only if 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.
[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 as an extension to distinguish between the formats.
—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 last element is directory-separator, otherwise it shall be
treated as a regular file path.
8.2.2path type and encoding conversions [path.type.cvt]
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 differs frompath::value_type. Encoding and method of conversion for the
argument or return value to be converted to is determined by its value type:
• char: Encoding is the native narrow encoding (4.10). Conversion, if any, is operating
system dependent.
[Note: For POSIX based operating systems path::value_type ischar so no
conversion fromchar value type arguments or tochar value type returns 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]
• wchar_t: Encoding is the native wide encoding (4.10). Conversion method is
unspecified.
© ISO/IEC 2015 – All rights reserved

© ISO/IEC N4100
[Note: For Windows based operating systems path::value_type iswchar_t so no
conversion fromwchar_t value type arguments or towchar_t value type returns is
performed. —end note]
• char16_t: Encoding is UTF-16. Conversion method is unspecified.
• char32_t: Encoding is UTF-32. Conversion method is unspecified.
If the encoding being converted to has no representation for source characters, the resulting converted
characters, if any, are unspecified.
8.3path requirements [path.req]
In addition to the requirements (5), function template parameters named Source shall be one of:
• basic_string. A function argumentconst Source&
source shall have an effective range [source.begin(),source.end()).
• A type meeting the input iterator requirements that iterates over a NTCTS. The value type shall
be an encoded character type. A function argumentconst Source&source shall have an
effective range [source,end) whereend is the first iterator value with an element value equal
toiterator_traits::value_type().
• 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 argumentconst Source&
source shall have an effective range [source,end) whereend is the first iterator value with an
element value equal to iterator_traits::type>::value_type().
[Note: See path conversions (8.2) for how these value types and their encodings convert to
path::value_type and its encoding. —end note]
Arguments of typeSource shall not be null pointers.
8.4path members [path.member]
8.4.1path constructors [path.construct]
path() noexcept;
Effects: Constructs an object of class path.
Postconditions: empty().
path(const path& p);
path(path&& p) noexcept;
© ISO/IEC 2015 – All rights reserved

© ISO/IEC N4100
Effects: Constructs an object of class path withpathname having the original value of
p.pathname. In the second form,p is left in a valid but unspecified state.
template
path(const Source& source);
template
path(InputIterator first, InputIterator last);
Effects: Constructs an object of class path, storing the effective range of source (8.3) or the
range [first,last) inpathname, converting format and encoding if required (8.2.1).
template
path(const Source& source, const locale& loc);
template
path(InputIterator first, InputIterator last, const locale& loc);
Requires: The value type of Source andInputIterator ischar.
Effects: Constructs an object of class path, storing the effective range of source or the range
[first,last) inpathname, after converting format if required and after converting the
encoding as follows:
Ifvalue_type iswchar_t, converts to the native wide encoding (4.10) using the
codecvt facet ofloc. Otherwise a conversion is
performed using the codecvt facet ofloc, and then
a second conversion to the current narrow encoding.
[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::experimental::filesystem;
std::string latin1_string = read_latin1_data();
codecvt_8859_1 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 (4.10). 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.
© ISO/IEC 2015 – All rights reserved

© ISO/IEC N4100
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]
8.4.2path assignments [path.assign]
path& operator=(const path& p);
Effects: If*this andp are the same object, has no effect. Otherwise, modifies pathname to
have the original value of p.pathname.
Returns:*this
path& operator=(path&& p) noexcept;
Effects: If*this andp are the same object, has no effect. Otherwise, modifies pathname to
have the original value of p.pathname. p is left in a valid but unspecified state. [Note: A valid
implementation is swap(p). —end note]
Returns:*this
template
path& operator=(const Source& source);
template
path& assign(const Source& source);
template
path& assign(InputIterator first, InputIterator last);
Effects: Stores the effective range of source (8.3) or the range [first,last) inpathname,
converting format and encoding if required (8.2.1).
Returns:*this
8.4.3path appends [path.append]
The append operations use operator/= to denote their semantic effect of appending preferred-
separator when needed.
path& operator/=(const path& p);
Effects:
Appendspath::preferred_separator topathname unless:
© ISO/IEC 2015 – All rights reserved

© ISO/IEC N4100
• an added separator would be redundant, or
• would change a relative path to an absolute path [Note: An empty path is
relative. — end note], or
...