| Defined in header <filesystem>
|
||
| bool create_directory( const std::filesystem::path& p ); |
(1) | (since C++17) |
| bool create_directory( const std::filesystem::path& p, std::error_code& ec ) noexcept; |
(2) | (since C++17) |
| bool create_directory( const std::filesystem::path& p, const std::filesystem::path& existing_p ); |
(3) | (since C++17) |
| bool create_directory( const std::filesystem::path& p, const std::filesystem::path& existing_p, std::error_code& ec ) noexcept; |
(4) | (since C++17) |
| bool create_directories( const std::filesystem::path& p ); |
(5) | (since C++17) |
| bool create_directories( const std::filesystem::path& p, std::error_code& ec ); |
(6) | (since C++17) |
p as if by POSIX mkdir() with a second argument of static_cast<int>(std::filesystem::perms::all) (the parent directory must already exist). If the function fails because p resolves to an existing directory, no error is reported. Otherwise on failure an error is reported.existing_p (which must be a directory that exists). It is OS-dependent which attributes are copied: on POSIX systems, the attributes are copied as if by
stat(existing_p.c_str(), &attributes_stat)
mkdir(p.c_str(), attributes_stat.st_mode)existing_p are copied.p that does not already exist. If p already exists, the function does nothing (this condition is not treated as an error).Parameters
| p | - | the path to the new directory to create |
| existing_p | - | the path to a directory to copy the attributes from |
| ec | - | out-parameter for error reporting in the non-throwing overload |
Return value
true if a directory was newly created for the directory p resolves to, false otherwise.
Exceptions
Any overload not marked noexcept may throw std::bad_alloc if memory allocation fails.
p as the first path argument and the OS error code as the error code argument.std::error_code& parameter to the OS API error code if an OS API call fails, and executes ec.clear() if no errors occur.p as the first path argument, existing_p as the second path argument, and the OS error code as the error code argument.std::error_code& parameter to the OS API error code if an OS API call fails, and executes ec.clear() if no errors occur.Notes
The attribute-preserving overload (3,4) is implicitly invoked by copy() when recursively copying directories. Its equivalent in boost.filesystem is copy_directory (with argument order reversed).
Example
#include <cassert>
#include <cstdlib>
#include <filesystem>
int main()
{
std::filesystem::current_path(std::filesystem::temp_directory_path());
// Basic usage
std::filesystem::create_directories("sandbox/1/2/a");
std::filesystem::create_directory("sandbox/1/2/b");
// Directory already exists (false returned, no error)
assert(!std::filesystem::create_directory("sandbox/1/2/b"));
// Permissions copying usage
std::filesystem::permissions(
"sandbox/1/2/b",
std::filesystem::perms::others_all,
std::filesystem::perm_options::remove
);
std::filesystem::create_directory("sandbox/1/2/c", "sandbox/1/2/b");
std::system("ls -l sandbox/1/2");
std::system("tree sandbox");
std::filesystem::remove_all("sandbox");
}drwxr-xr-x 2 user group 4096 Apr 15 09:33 a
drwxr-x--- 2 user group 4096 Apr 15 09:33 b
drwxr-x--- 2 user group 4096 Apr 15 09:33 c
sandbox
└── 1
└── 2
├── a
├── b
└── cDefect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
| DR | Applied to | Behavior as published | Correct behavior |
|---|---|---|---|
| LWG 2935 | C++17 | error if target already exists but is not a directory | not error |
| LWG 3014 | C++17 | error_code overload of create_directories marked noexcept but can allocate memory
|
noexcept removed |
| P1164R1 | C++17 | creation failure caused by an existing non-directory file is not an error | made error |
See also
| (C++17)(C++17) |
creates a symbolic link (function) |
| (C++17) |
copies files or directories (function) |
| (C++17) |
identifies file system permissions (enum) |
Content from this page on cppreference.com, licensed under CC-BY-SA 3.0 and GFDL. Modified: restyled, site navigation removed, code windows added. Offline snapshot of 9 February 2025.