Difference between revisions of "cpp/filesystem"
From cppreference.com
< cpp
m |
m (→Notes: {{c}} → box{{tt}} for compiler options.) |
||
| (11 intermediate revisions by 6 users not shown) | |||
| Line 1: | Line 1: | ||
| − | {{title|Filesystem library}} | + | {{title|Filesystem library {{mark since c++17}}}} |
{{cpp/filesystem/navbar}} | {{cpp/filesystem/navbar}} | ||
The Filesystem library provides facilities for performing operations on file systems and their components, such as paths, regular files, and directories. | The Filesystem library provides facilities for performing operations on file systems and their components, such as paths, regular files, and directories. | ||
| − | The filesystem library was originally developed as [ | + | The filesystem library was originally developed as [https://www.boost.org/doc/libs/release/libs/filesystem/doc/index.htm boost.filesystem], was published as [[cpp/experimental/fs|the technical specification ISO/IEC TS 18822:2015]], and finally merged to ISO C++ as of C++17. The boost implementation is currently available on more compilers and platforms than the C++17 library. |
The filesystem library facilities may be unavailable if a hierarchical file system is not accessible to the implementation, or if it does not provide the necessary capabilities. Some features may not be available if they are not supported by the underlying file system (e.g. the FAT filesystem lacks symbolic links and forbids multiple hardlinks). In those cases, errors must be reported. | The filesystem library facilities may be unavailable if a hierarchical file system is not accessible to the implementation, or if it does not provide the necessary capabilities. Some features may not be available if they are not supported by the underlying file system (e.g. the FAT filesystem lacks symbolic links and forbids multiple hardlinks). In those cases, errors must be reported. | ||
| Line 9: | Line 9: | ||
The behavior is [[cpp/language/ub|undefined]] if the calls to functions in this library introduce a ''file system race'', that is, when multiple threads, processes, or computers interleave access and modification to the same object in a file system. | The behavior is [[cpp/language/ub|undefined]] if the calls to functions in this library introduce a ''file system race'', that is, when multiple threads, processes, or computers interleave access and modification to the same object in a file system. | ||
| − | ====Library-wide definitions ==== | + | ====Library-wide definitions==== |
* ''file'': a file system object that holds data, can be written to, read from, or both. Files have names, attributes, one of which is file type: | * ''file'': a file system object that holds data, can be written to, read from, or both. Files have names, attributes, one of which is file type: | ||
:* ''directory'': a file that acts as a container of directory entries, which identify other files (some of which may be other, nested directories). When discussing a particular file, the directory in which it appears as an entry is its ''parent directory''. The parent directory can be represented by the relative pathname {{c|".."}}. | :* ''directory'': a file that acts as a container of directory entries, which identify other files (some of which may be other, nested directories). When discussing a particular file, the directory in which it appears as an entry is its ''parent directory''. The parent directory can be represented by the relative pathname {{c|".."}}. | ||
| − | :* '' | + | :* ''regular file'': a directory entry that associates a name with an existing file (i.e. a ''hard link''). If multiple hard links are supported, the file is removed after the last hard link to it is removed. |
| − | :* ''symbolic link'': a directory entry that associates a name with a path, which may or may not exist. | + | :* ''symbolic link'': a directory entry that associates a name with a path, which may or may not exist. |
| − | :* '' | + | :* other special file types: ''block'', ''character'', ''fifo'', ''socket''. |
* ''file name'': a string of characters that names a file. Permissible characters, case sensitivity, maximum length, and the disallowed names are implementation-defined. Names {{c|"."}} (dot) and {{c|".."}} (dot-dot) have special meaning at library level. | * ''file name'': a string of characters that names a file. Permissible characters, case sensitivity, maximum length, and the disallowed names are implementation-defined. Names {{c|"."}} (dot) and {{c|".."}} (dot-dot) have special meaning at library level. | ||
* ''path'': sequence of elements that identifies a file. It begins with an optional {{spar|root-name}} (e.g. {{c|"C:"}} or {{c|"//server"}} on Windows), followed by an optional {{spar|root-directory}} (e.g. {{c|"/"}} on Unix), followed by a sequence of zero or more file names (all but last of which have to be directories or links to directories). The native format (e.g. which characters are used as separators) and character encoding of the string representation of a path (the ''pathname'') is implementation-defined, this library provides portable representation of paths. | * ''path'': sequence of elements that identifies a file. It begins with an optional {{spar|root-name}} (e.g. {{c|"C:"}} or {{c|"//server"}} on Windows), followed by an optional {{spar|root-directory}} (e.g. {{c|"/"}} on Unix), followed by a sequence of zero or more file names (all but last of which have to be directories or links to directories). The native format (e.g. which characters are used as separators) and character encoding of the string representation of a path (the ''pathname'') is implementation-defined, this library provides portable representation of paths. | ||
| Line 22: | Line 22: | ||
{{dsc begin}} | {{dsc begin}} | ||
| − | {{dsc h1 | Classes}} | + | {{dsc h1|Classes}} |
{{dsc header|filesystem}} | {{dsc header|filesystem}} | ||
{{dsc namespace|std::filesystem}} | {{dsc namespace|std::filesystem}} | ||
| − | {{dsc inc | cpp/filesystem/dsc path}} <!-- including | + | {{dsc inc|cpp/filesystem/dsc path}}<!--including swap, hash_value, comparisons, /, <<, >>, and u8path--> |
| − | {{dsc inc | cpp/filesystem/dsc filesystem_error}} | + | {{dsc inc|cpp/filesystem/dsc filesystem_error}} |
| − | {{dsc inc | cpp/filesystem/dsc directory_entry}} | + | {{dsc inc|cpp/filesystem/dsc directory_entry}} |
| − | {{dsc inc | cpp/filesystem/dsc directory_iterator}} <!-- including begin,end --> | + | {{dsc inc|cpp/filesystem/dsc directory_iterator}}<!--including begin,end--> |
| − | {{dsc inc | cpp/filesystem/dsc recursive_directory_iterator}} <!-- including begin,end --> | + | {{dsc inc|cpp/filesystem/dsc recursive_directory_iterator}}<!--including begin,end--> |
| − | {{dsc inc | cpp/filesystem/dsc file_status}} | + | {{dsc inc|cpp/filesystem/dsc file_status}} |
| − | {{dsc inc | cpp/filesystem/dsc space_info}} | + | {{dsc inc|cpp/filesystem/dsc space_info}} |
| − | {{dsc inc | cpp/filesystem/dsc file_type}} | + | {{dsc inc|cpp/filesystem/dsc file_type}} |
| − | {{dsc inc | cpp/filesystem/dsc perms}} | + | {{dsc inc|cpp/filesystem/dsc perms}} |
| − | {{dsc inc | cpp/filesystem/dsc perm_options}} | + | {{dsc inc|cpp/filesystem/dsc perm_options}} |
| − | {{dsc inc | cpp/filesystem/dsc copy_options}} | + | {{dsc inc|cpp/filesystem/dsc copy_options}} |
| − | {{dsc inc | cpp/filesystem/dsc directory_options}} | + | {{dsc inc|cpp/filesystem/dsc directory_options}} |
| − | {{dsc inc | cpp/filesystem/dsc file_time_type}} | + | {{dsc inc|cpp/filesystem/dsc file_time_type}} |
| − | {{dsc h1 | Non-member functions}} | + | {{dsc h1|Non-member functions}} |
{{dsc header|filesystem}} | {{dsc header|filesystem}} | ||
{{dsc namespace|std::filesystem}} | {{dsc namespace|std::filesystem}} | ||
| − | {{dsc inc | cpp/filesystem/dsc absolute}}<!-- including system_complete --> | + | {{dsc inc|cpp/filesystem/dsc absolute}}<!--including system_complete--> |
| − | {{dsc inc | cpp/filesystem/dsc canonical}}<!-- including weakly_canonical --> | + | {{dsc inc|cpp/filesystem/dsc canonical}}<!--including weakly_canonical--> |
| − | {{dsc inc | cpp/filesystem/dsc relative}}<!-- including proximate --> | + | {{dsc inc|cpp/filesystem/dsc relative}}<!--including proximate--> |
| − | {{dsc inc | cpp/filesystem/dsc copy}} | + | {{dsc inc|cpp/filesystem/dsc copy}} |
| − | {{dsc inc | cpp/filesystem/dsc copy_file}} | + | {{dsc inc|cpp/filesystem/dsc copy_file}} |
| − | {{dsc inc | cpp/filesystem/dsc copy_symlink}} | + | {{dsc inc|cpp/filesystem/dsc copy_symlink}} |
| − | {{dsc inc | cpp/filesystem/dsc create_directory}} <!-- including create_directories --> | + | {{dsc inc|cpp/filesystem/dsc create_directory}}<!--including create_directories--> |
| − | {{dsc inc | cpp/filesystem/dsc create_hard_link}} | + | {{dsc inc|cpp/filesystem/dsc create_hard_link}} |
| − | {{dsc inc | cpp/filesystem/dsc create_symlink}} <!-- including create_directory_symlink --> | + | {{dsc inc|cpp/filesystem/dsc create_symlink}}<!--including create_directory_symlink--> |
| − | {{dsc inc | cpp/filesystem/dsc current_path}} | + | {{dsc inc|cpp/filesystem/dsc current_path}} |
| − | {{dsc inc | cpp/filesystem/dsc exists}} | + | {{dsc inc|cpp/filesystem/dsc exists}} |
| − | {{dsc inc | cpp/filesystem/dsc equivalent}} | + | {{dsc inc|cpp/filesystem/dsc equivalent}} |
| − | {{dsc inc | cpp/filesystem/dsc file_size}} | + | {{dsc inc|cpp/filesystem/dsc file_size}} |
| − | {{dsc inc | cpp/filesystem/dsc hard_link_count}} | + | {{dsc inc|cpp/filesystem/dsc hard_link_count}} |
| − | {{dsc inc | cpp/filesystem/dsc last_write_time}} | + | {{dsc inc|cpp/filesystem/dsc last_write_time}} |
| − | {{dsc inc | cpp/filesystem/dsc permissions}} | + | {{dsc inc|cpp/filesystem/dsc permissions}} |
| − | {{dsc inc | cpp/filesystem/dsc read_symlink}} | + | {{dsc inc|cpp/filesystem/dsc read_symlink}} |
| − | {{dsc inc | cpp/filesystem/dsc remove}} <!-- including remove_all --> | + | {{dsc inc|cpp/filesystem/dsc remove}}<!--including remove_all--> |
| − | {{dsc inc | cpp/filesystem/dsc rename}} | + | {{dsc inc|cpp/filesystem/dsc rename}} |
| − | {{dsc inc | cpp/filesystem/dsc resize_file}} | + | {{dsc inc|cpp/filesystem/dsc resize_file}} |
| − | {{dsc inc | cpp/filesystem/dsc space}} | + | {{dsc inc|cpp/filesystem/dsc space}} |
| − | {{dsc inc | cpp/filesystem/dsc status}} <!-- including symlink_status --> | + | {{dsc inc|cpp/filesystem/dsc status}}<!--including symlink_status--> |
| − | {{dsc inc | cpp/filesystem/dsc temp_directory_path}} | + | {{dsc inc|cpp/filesystem/dsc temp_directory_path}} |
| − | {{dsc h2 | File types}} | + | {{dsc h2|File types}} |
| − | {{dsc inc | cpp/filesystem/dsc is_block_file}} | + | {{dsc inc|cpp/filesystem/dsc is_block_file}} |
| − | {{dsc inc | cpp/filesystem/dsc is_character_file}} | + | {{dsc inc|cpp/filesystem/dsc is_character_file}} |
| − | {{dsc inc | cpp/filesystem/dsc is_directory}} | + | {{dsc inc|cpp/filesystem/dsc is_directory}} |
| − | {{dsc inc | cpp/filesystem/dsc is_empty}} | + | {{dsc inc|cpp/filesystem/dsc is_empty}} |
| − | {{dsc inc | cpp/filesystem/dsc is_fifo}} | + | {{dsc inc|cpp/filesystem/dsc is_fifo}} |
| − | {{dsc inc | cpp/filesystem/dsc is_other}} | + | {{dsc inc|cpp/filesystem/dsc is_other}} |
| − | {{dsc inc | cpp/filesystem/dsc is_regular_file}} | + | {{dsc inc|cpp/filesystem/dsc is_regular_file}} |
| − | {{dsc inc | cpp/filesystem/dsc is_socket}} | + | {{dsc inc|cpp/filesystem/dsc is_socket}} |
| − | {{dsc inc | cpp/filesystem/dsc is_symlink}} | + | {{dsc inc|cpp/filesystem/dsc is_symlink}} |
| − | {{dsc inc | cpp/filesystem/dsc status_known}} | + | {{dsc inc|cpp/filesystem/dsc status_known}} |
{{dsc end}} | {{dsc end}} | ||
===Notes=== | ===Notes=== | ||
| − | Using this library may require additional compiler/linker options. GNU implementation prior to 9.1 requires linking with {{ | + | Using this library may require additional compiler/linker options. GNU implementation prior to 9.1 requires linking with {{box|{{tt|-lstdc++fs}}}} and LLVM implementation prior to LLVM 9.0 requires linking with {{box|{{tt|-lc++fs}}}}. |
| + | |||
| + | {{feature test macro|__cpp_lib_filesystem|std=C++17|value=201703L|Filesystem library|value=201703L|std=C++17}} | ||
===See also=== | ===See also=== | ||
{{dsc begin}} | {{dsc begin}} | ||
| − | {{dsc see cpp | cpp/experimental/fs | File System TS}} | + | {{dsc see cpp|cpp/experimental/fs|File System TS|nomono=true}} |
{{dsc end}} | {{dsc end}} | ||
| − | {{langlinks|es|ja|zh}} | + | {{langlinks|es|ja|ru|zh}} |
Latest revision as of 07:54, 9 June 2024
The Filesystem library provides facilities for performing operations on file systems and their components, such as paths, regular files, and directories.
The filesystem library was originally developed as boost.filesystem, was published as the technical specification ISO/IEC TS 18822:2015, and finally merged to ISO C++ as of C++17. The boost implementation is currently available on more compilers and platforms than the C++17 library.
The filesystem library facilities may be unavailable if a hierarchical file system is not accessible to the implementation, or if it does not provide the necessary capabilities. Some features may not be available if they are not supported by the underlying file system (e.g. the FAT filesystem lacks symbolic links and forbids multiple hardlinks). In those cases, errors must be reported.
The behavior is undefined if the calls to functions in this library introduce a file system race, that is, when multiple threads, processes, or computers interleave access and modification to the same object in a file system.
Contents |
[edit] Library-wide definitions
- file: a file system object that holds data, can be written to, read from, or both. Files have names, attributes, one of which is file type:
- directory: a file that acts as a container of directory entries, which identify other files (some of which may be other, nested directories). When discussing a particular file, the directory in which it appears as an entry is its parent directory. The parent directory can be represented by the relative pathname "..".
- regular file: a directory entry that associates a name with an existing file (i.e. a hard link). If multiple hard links are supported, the file is removed after the last hard link to it is removed.
- symbolic link: a directory entry that associates a name with a path, which may or may not exist.
- other special file types: block, character, fifo, socket.
- file name: a string of characters that names a file. Permissible characters, case sensitivity, maximum length, and the disallowed names are implementation-defined. Names "." (dot) and ".." (dot-dot) have special meaning at library level.
- path: sequence of elements that identifies a file. It begins with an optional root-name (e.g. "C:" or "//server" on Windows), followed by an optional root-directory (e.g. "/" on Unix), followed by a sequence of zero or more file names (all but last of which have to be directories or links to directories). The native format (e.g. which characters are used as separators) and character encoding of the string representation of a path (the pathname) is implementation-defined, this library provides portable representation of paths.
- absolute path: a path that unambiguously identifies the location of a file.
- canonical path: an absolute path that includes no symlinks, "." or ".." elements.
- relative path: a path that identifies the location of a file relative to some location on the file system. The special path names "." (dot, "current directory") and ".." (dot-dot, "parent directory") are relative paths.
Classes | |
| Defined in header
<filesystem> | |
| Defined in namespace
std::filesystem | |
| (C++17) |
represents a path (class) |
| (C++17) |
an exception thrown on file system errors (class) |
| (C++17) |
a directory entry (class) |
| (C++17) |
an iterator to the contents of the directory (class) |
| (C++17) |
an iterator to the contents of a directory and its subdirectories (class) |
| (C++17) |
represents file type and permissions (class) |
| (C++17) |
information about free and available space on the filesystem (class) |
| (C++17) |
the type of a file (enum) |
| (C++17) |
identifies file system permissions (enum) |
| (C++17) |
specifies semantics of permissions operations (enum) |
| (C++17) |
specifies semantics of copy operations (enum) |
| (C++17) |
options for iterating directory contents (enum) |
| (C++17) |
represents file time values (typedef) |
Non-member functions | |
| Defined in header
<filesystem> | |
| Defined in namespace
std::filesystem | |
| (C++17) |
composes an absolute path (function) |
| (C++17) |
composes a canonical path (function) |
| (C++17) |
composes a relative path (function) |
| (C++17) |
copies files or directories (function) |
| (C++17) |
copies file contents (function) |
| (C++17) |
copies a symbolic link (function) |
| (C++17)(C++17) |
creates new directory (function) |
| (C++17) |
creates a hard link (function) |
| (C++17)(C++17) |
creates a symbolic link (function) |
| (C++17) |
returns or sets the current working directory (function) |
| (C++17) |
checks whether path refers to existing file system object (function) |
| (C++17) |
checks whether two paths refer to the same file system object (function) |
| (C++17) |
returns the size of a file (function) |
| (C++17) |
returns the number of hard links referring to the specific file (function) |
| (C++17) |
gets or sets the time of the last data modification (function) |
| (C++17) |
modifies file access permissions (function) |
| (C++17) |
obtains the target of a symbolic link (function) |
| (C++17)(C++17) |
removes a file or empty directory removes a file or directory and all its contents, recursively (function) |
| (C++17) |
moves or renames a file or directory (function) |
| (C++17) |
changes the size of a regular file by truncation or zero-fill (function) |
| (C++17) |
determines available free space on the file system (function) |
| (C++17)(C++17) |
determines file attributes determines file attributes, checking the symlink target (function) |
| (C++17) |
returns a directory suitable for temporary files (function) |
File types | |
| (C++17) |
checks whether the given path refers to block device (function) |
| (C++17) |
checks whether the given path refers to a character device (function) |
| (C++17) |
checks whether the given path refers to a directory (function) |
| (C++17) |
checks whether the given path refers to an empty file or directory (function) |
| (C++17) |
checks whether the given path refers to a named pipe (function) |
| (C++17) |
checks whether the argument refers to an other file (function) |
| (C++17) |
checks whether the argument refers to a regular file (function) |
| (C++17) |
checks whether the argument refers to a named IPC socket (function) |
| (C++17) |
checks whether the argument refers to a symbolic link (function) |
| (C++17) |
checks whether file status is known (function) |
[edit] Notes
Using this library may require additional compiler/linker options. GNU implementation prior to 9.1 requires linking with -lstdc++fs and LLVM implementation prior to LLVM 9.0 requires linking with -lc++fs.
| Feature-test macro | Value | Std | Feature |
|---|---|---|---|
__cpp_lib_filesystem |
201703L | (C++17) | Filesystem library |
[edit] See also
| C++ documentation for File System TS
|
