`<filesystem>` 函式

C++17 <filesystem> 標頭中的這些自由函式可對路徑、檔案、符號連結、目錄與卷執行修改與查詢操作。如需詳細資訊與程式碼範例，請參閱檔案系統巡覽 (C++)。

Note

本文記錄了 C++17 std::filesystem 的函式。關於 MSVC 在中提供的 <experimental/filesystem>歷史前標準函數，請參見 <experimental/filesystem> 函數。

Requirements

標頭：<filesystem>

命名空間：std::filesystem

`absolute`

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

函式組成一條絕對路徑，根據作業系統語意，指向與 pval相同的檔案系統位置。如果發生錯誤，承受的 ec 過載會回來 path() 。

`begin`

directory_iterator begin(directory_iterator iter) noexcept;
recursive_directory_iterator begin(recursive_directory_iterator iter) noexcept;

兩個函式都會傳回 iter。與 end一起，它們使基於範圍 for 的迴圈在或 directory_iteratorrecursive_directory_iterator上成為可能。

`canonical`

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

函式會將必須存在的轉換 pval成指向同一檔案系統物件且無符號連結、點或點點元素的絕對路徑。如果發生錯誤，承受的 ec 過載會回來 path() 。

`copy`

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 opts);
void copy(const path& from, const path& to, copy_options opts, error_code& ec) noexcept;

函式全都可以將位於的一或多個檔案從複製或連結至受控制opts之下，這會做copy_options::none為沒有opts參數的多載。 opts 最多應該包含其中一個：

skip_existing、 overwrite_existing或 update_existing
copy_symlinks 或 skip_symlinks
directories_only、 create_symlinks或 create_hard_links

函數首先決定 file_status從和t到的值f。當包含、 copy_options::skip_symlinks、或 copy_options::copy_symlinks，根據來源或目的點的需要，它們會使用symlink_status。copy_options::create_symlinksopts 否則，他們會使用 status。

如果 !exists(f) || equivalent(f, t) || is_other(f) || is_other(t) || is_directory(f)&& is_regular_file(t)為，則報告錯誤（且不會執行其他動作）。

否則，如果 is_symlink(f) 為：

如果 options & copy_options::skip_symlinks為，則不會執行任何動作。
否則，如果 !exists(t) && options & copy_options::copy_symlinks為，則 copy_symlink(from, to)為。
否則，請報告錯誤。

否則，如果 is_regular_file(f)為，則：

如果 opts & copy_options::directories_only為，則不會執行任何動作。
否則，如果 opts & copy_options::create_symlinks為，則 create_symlink(from, to)為。
否則，如果 opts & copy_options::create_hard_links為，則 create_hard_link(from, to)為。
否則，如果 is_directory(t)為，則 copy_file(from, to / from.filename(), opts)為。
否則為 copy_file(from, to, opts)。

否則，如果 is_directory(f) && (opts & copy_options::recursive || !opts)為，則：

if (!exists(t))
{  // copy directory contents recursively
    create_directory(to, from, ec);

    for (directory_iterator next(from), end; ec == error_code() && next != end; ++next)
    {
        copy(next->path(), to / next->path().filename(), opts, ec);
    }
}

否則，不執行任何作業。

`copy_file`

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 opts);
bool copy_file(const path& from, const path& to, copy_options opts, error_code& ec) noexcept;

函式全都可以將位於的檔案從複製到，opts以做copy_options::none為沒有opts參數的多載。 opts最多應包含、或skip_existing的overwrite_existingupdate_existing其中一個。

如果 exists(to) && !(opts & (copy_options::skip_existing | copy_options::overwrite_existing | copy_options::update_existing))為，則回報為檔案已經存在的錯誤。

否則，如果!exists(to) || opts & copy_options::overwrite_existing || opts & copy_options::update_existing&& last_write_time(to) < last_write_time(from) || !(opts & (copy_options::skip_existing | copy_options::overwrite_existing | copy_options::update_existing))為，則嘗試將檔案的內容和屬性從 複製到檔案。如果複製嘗試失敗，則報告錯誤。

如果嘗試複製且成功，則函式會傳回 true ，否則 false為。

`copy_symlink`

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

如果 is_directory(from)為，則函式會呼叫 create_directory_symlink(from, to)。否則，它會呼叫 create_symlink(from, to)。

`create_directories`

bool create_directories(const path& pval);
bool create_directories(const path& pval, error_code& ec) noexcept;

對於之類的 a\/b\/c路徑名稱，函式會視需要建立目錄 a ， a\/b 以便視需要建立目錄 a\/b\/c 。只有當它實際建立目錄true時，才會傳pval回。

`create_directory`

bool create_directory(const path& pval);

bool create_directory(const path& pval, error_code& ec) noexcept;
bool create_directory(const path& pval, const path& attr);
bool create_directory(const path& pval, const path& attr, error_code& ec) noexcept;

函式會視需要建立目錄 pval。只有當它實際建立目錄時，才會傳回 true ，在此情況下，它會從現有的檔案pval複製許可權，或針對沒有attr參數的多載使用 perms::all 。attr

`create_directory_symlink`

void create_directory_symlink(const path& to, const path& link);
void create_directory_symlink(const path& to, const path& link, error_code& ec) noexcept;

函式會將連結建立為目錄的符號連結。

`create_hard_link`

void create_hard_link(const path& to,  const path& link);
void create_hard_link(const path& to, const path& link, error_code& ec) noexcept;

函式會將連結建立為目錄或檔案的硬連結。

`create_symlink`

void create_symlink(const path& to, const path& link);

void create_symlink(const path& to, const path& link, error_code& ec) noexcept;

函式會link建立為檔案的符號連結。

`current_path`

path current_path();
path current_path(error_code& ec);
void current_path(const path& pval);
void current_path(const path& pval, error_code& ec) noexcept;

不含參數 pval 的函式會傳回目前目錄的路徑名稱。其餘的函式會將目前的目錄設為 pval。

`end`

directory_iterator end(const directory_iterator&) noexcept;
recursive_directory_iterator end(const recursive_directory_iterator&) noexcept;

第一個函數返回 directory_iterator() ，第二個函數返回 recursive_directory_iterator()。

`equivalent`

bool equivalent(const path& left, const path& right);
bool equivalent(const path& left, const path& right, error_code& ec) noexcept;

只有在向左和向右選擇相同的檔系統實體時，函式才會傳回true。

`exists`

bool exists(file_status stat) noexcept;
bool exists(const path& pval);
bool exists(const path& pval, error_code& ec) noexcept;

第一個函式會傳回 status_known(stat) && stat.type() != file_type::not_found。第二個和第三個函式會傳回 exists(status(pval))。

`file_size`

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

函式會傳回所 pval選擇檔案的位元元組大小，如果 exists(pval) && is_regular_file(pval) 和檔案大小可以決定。否則會回報錯誤並傳回 uintmax_t(-1)。

`hard_link_count`

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

如果發生錯誤，函式會傳回的硬式連結 pval數目，或 -1。

`hash_value`

size_t hash_value(const path& pval) noexcept;

函式會傳回的 pval.native()哈希值。

`is_block_file`

bool is_block_file(file_status stat) noexcept;
bool is_block_file(const path& pval);
bool is_block_file(const path& pval, error_code& ec) noexcept;

第一個函式會傳回 stat.type() == file_type::block。其餘函式會傳回 is_block_file(status(pval))。

`is_character_file`

bool is_character_file(file_status stat) noexcept;
bool is_character_file(const path& pval);
bool is_character_file(const path& pval, error_code& ec) noexcept;

第一個函式會傳回 stat.type() == file_type::character。其餘函式會傳回 is_character_file(status(pval))。

`is_directory`

bool is_directory(file_status stat) noexcept;
bool is_directory(const path& pval);
bool is_directory(const path& pval, error_code& ec) noexcept;

第一個函式會傳回 stat.type() == file_type::directory。其餘函式會傳回 is_directory(status(pval))。

`is_empty`

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

如果 is_directory(pval)為，則函式會傳 directory_iterator(pval) == directory_iterator()回，否則會傳 file_size(pval) == 0回。

`is_fifo`

bool is_fifo(file_status stat) noexcept;
bool is_fifo(const path& pval);
bool is_fifo(const path& pval, error_code& ec) noexcept;

第一個函式會傳回 stat.type() == file_type::fifo。其餘函式會傳回 is_fifo(status(pval))。

`is_other`

bool is_other(file_status stat) noexcept;
bool is_other(const path& pval);
bool is_other(const path& pval, error_code& ec) noexcept;

第一個函式會傳回 exists(stat) && !is_regular_file(stat) && !is_directory(stat) && !is_symlink(stat)。其餘函式會傳回 is_other(status(pval))。

`is_regular_file`

bool is_regular_file(file_status stat) noexcept;
bool is_regular_file(const path& pval);
bool is_regular_file(const path& pval, error_code& ec) noexcept;

第一個函式會傳回 stat.type() == file_type::regular。其餘函式會傳回 is_regular_file(status(pval))。

`is_socket`

bool is_socket(file_status stat) noexcept;
bool is_socket(const path& pval);
bool is_socket(const path& pval, error_code& ec) noexcept;

第一個函式會傳回 stat.type() == file_type::socket。其餘函式會傳回 is_socket(status(pval))。

`is_symlink`

bool is_symlink(file_status stat) noexcept;
bool is_symlink(const path& pval);
bool is_symlink(const path& pval, error_code& ec) noexcept;

第一個函式會傳回 stat.type() == file_type::symlink。其餘函式會傳回 is_symlink(status(pval))。

`last_write_time`

file_time_type last_write_time(const path& pval);
file_time_type last_write_time(const path& pval, error_code& ec) noexcept;
void last_write_time(const path& pval, file_time_type new_time);
void last_write_time(const path& pval, file_time_type new_time, error_code& ec) noexcept;

前兩個函式會傳回上次修改 pval資料的時間，如果 file_time_type(-1) 發生錯誤則傳回。最後兩個函式會將上次修改資料 pval 的時間設定為 new_time。

`permissions`

void permissions(const path& pval, perms mask, perm_options opts = perm_options::replace);
void permissions(const path& pval, perms mask, error_code& ec) noexcept;
void permissions(const path& pval, perms mask, perm_options opts, error_code& ec);

函式會將選擇pval之pathname的權限設定為，mask & perms::mask以opts控制。 opts 必須恰好包含一個 perm_options::replace、 perm_options::add或 perm_options::remove，且可選地 perm_options::nofollow。沒有opts參數的過載行為如opts同。perm_options::replace

如果 opts & perm_options::add為，函式會將權限設定為 status(pval).permissions() | (mask & perms::mask)。否則，如果 opts & perm_options::remove為，函式會將權限設定為 status(pval).permissions() & ~(mask & perms::mask)。否則，函式會將權限設定為 mask & perms::mask。若 opts & perm_options::nofollow 和 pval 命名符號連結，函式會改變符號連結本身的權限，而非其解析的檔案。

`proximate`

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);

第一次過載返回 proximate(p, current_path(), ec)。其他過載則返回應用於弱典範形式的pbase結果lexically_proximate。如果發生錯誤，承受的 ec 過載會回來 path() 。

`read_symlink`

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

函式會報告錯誤，如果傳回，則傳path()回 !is_symlink(pval) 。否則，函數會傳回包含符號連結的 path 類型物件。

`relative`

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);

第一次過載返回 relative(p, current_path(), ec)。其他過載則返回應用於弱典範形式的pbase結果lexically_relative。如果發生錯誤，承受的 ec 過載會回來 path() 。

`remove`

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

只有在已成功移除和檔案時true，函式才會傳回 exists(symlink_status(pval)) 。符號連結本身已移除，而不是它選擇的檔案。

`remove_all`

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

如果 pval 是目錄，這些函式會以遞迴方式移除所有目錄項目，再移除項目本身。否則，函式會呼叫 remove。它們會傳回成功移除的所有元素計數。

`rename`

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

函式會從 重新命名為。符號連結本身會重新命名，而不是它選擇的檔案。

`resize_file`

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

函式會改變檔案大小，使得 file_size(pval) == size。

`space`

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

函式會傳回所選擇 pval之磁碟區的相關信息，其結構為類型 space_info。結構包含 uintmax_t(-1) 任何無法判斷的值。

`status`

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

函式會傳回與相關聯的 pval路徑名稱狀態、檔類型和許可權。符號連結本身不會經過測試，但它選擇的檔案。

`status_known`

bool status_known(file_status stat) noexcept;

函式會傳回 stat.type() != file_type::none

`swap`

void swap(path& left, path& right) noexcept;

函式會交換左右的內容。

`symlink_status`

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

函式會傳回與相關聯的 pvalpathname符號連結狀態、檔案類型和許可權。函式的行為與 status(pval) 相同，不同之處在於符號連結本身已經過測試，而不是它選擇的檔案。

`temp_directory_path`

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

函式會傳回適合包含暫存檔的目錄路徑名稱。

`u8path`

template <class Source>
path u8path(const Source& source);

template <class InIt>
path u8path(InIt first, InIt last);

第一個函式的行為與相同 path(source) ，而第二個函式的行為與相同 path(first, last) ，不同之處在於每個案例中所選的來源會被視為編碼為 UTF-8 的 char 元素序列，無論文件系統為何。

`weakly_canonical`

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

這些函數以典範形式回傳路徑，就像函數一樣 canonical ，但路徑不必存在。

參見

標頭檔參考
 <filesystem>
檔案系統導航（C++）

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-08-31

<filesystem> 函式

Requirements

absolute

begin

canonical

copy

copy_file

copy_symlink

create_directories

create_directory

create_directory_symlink

create_hard_link

create_symlink

current_path

end

equivalent

exists

file_size

hard_link_count

hash_value

is_block_file

is_character_file

is_directory

is_empty

is_fifo

is_other

is_regular_file

is_socket

is_symlink

last_write_time

permissions

proximate

read_symlink

relative

remove

remove_all

rename

resize_file

space

status

status_known

swap

symlink_status

temp_directory_path

u8path

weakly_canonical

參見