<experimental/filesystem> 函式

Important

<experimental/filesystem>標頭與std::experimental::filesystem命名空間提供了檔案系統技術規範(TS)的預先實作。 此文件保留用於針對 MSVC 原始檔案系統實作撰寫的程式碼,該實作自 MSVC 版本 14.51 起被移除。 新程式碼則改用 C++17 <filesystem> 標頭和 std::filesystem 命名空間。 關於這些函數的標準等價函數,請參見 <filesystem> 函數。

標頭中的 <experimental/filesystem> 這些自由函式可對路徑、檔案、符號連結、目錄和卷進行修改與查詢操作。 欲了解更多資訊與程式碼範例,請參閱檔案系統導航(C++)。

Requirements

標頭:<experimental/filesystem>

命名空間:std::experimental::filesystem

absolute

path absolute(const path& pval, const path& base = current_path());

該函數回傳相對於路徑名稱 base的pval絕對路徑名稱:

  1. 若 pval.has_root_name() && pval.has_root_directory() 函數返回 pval。

  2. 若pval.has_root_name() && !pval.has_root_directory()函數返回 / pval.root_name() / / absolute(base).relative_path()absolute(base).root_directory()pval.relative_path() 。

  3. 若!pval.has_root_name() && pval.has_root_directory()函數返回 / absolute(base).root_name()pval 。

  4. 若!pval.has_root_name() && !pval.has_root_directory()函數返回 / absolute(base)pval 。

begin

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

兩個函數都會返回 iter。

canonical

path canonical(const path& pval, const path& base = current_path());
path canonical(const path& pval, error_code& ec);
path canonical(const path& pval, const path& base, error_code& ec);

這些函數皆形成絕對路徑名稱 pabs = absolute(pval, base) (或 pabs = absolute(pval) 超載時無基參數),然後依以下步驟將其簡化為典範形式:

  1. 將每個 的is_symlink(X)true路徑分量X替換為 read_symlink(X)。

  2. 移除所有路徑元件 . (dot 是先前路徑元件建立的當前目錄)。

  3. 移除每一對路徑元件 X/.. (dot-dot 是前一路徑元件建立的父目錄)。

函數隨後返回 pabs。

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;

這些函式都可能複製或連結一個或多個檔案 from ,控制 to 於 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了 和 fromt 的to值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;

這些函式都可能將檔案 from 複製到 to ,受 控制 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)),則嘗試將檔案 from 的內容與屬性複製到檔案 to。 如果複製失敗,請回報為錯誤。

如果複製成功false,函式會回傳true,否則。

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。 只有當它實際建立目錄 pval時才會回傳true。

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 。 只有當它實際建立目錄 pval時才會回傳true。 如果你指定參數, attr 函式會從現有檔案複製權限。 如果你不指定參數, attr 函數會使用 perms::all。

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

函式會建立 link 一個指向目錄 to的符號連結。

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

這個函式會建立 link 一個硬連結到目錄或檔案 to。

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

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

函式會建立 link 一個指向檔案 to的符號連結。

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;

若 exists(pval) && is_regular_file(pval) 且檔案大小可確定,函式會回傳由 pval選擇的檔案大小(位元組)。 否則他們會回報錯誤並退回 uintmax_t(-1)。

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

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;

前兩個函數回傳 ,pvalfile_time_type(-1)當發生錯誤時,回傳最後一次資料修改的時間。 最後兩個函數將最後 pval 一次資料修改時間設定為 new_time。

permissions

void permissions(const path& pval, perms mask);
void permissions(const path& pval, perms mask, error_code& ec) noexcept;

函式將所 pval 選路徑名稱的權限設定為 mask & perms::mask 受控制 perms & (perms::add_perms | perms::remove_perms)。 mask 包含最多一個 和 perms::add_permsperms::remove_perms。

若 mask & perms::add_perms,函式將權限設定為 status(pval).permissions() | mask & perms::mask。 否則,若 mask & perms::remove_perms,函式將權限設定為 status(pval).permissions() & ~(mask & perms::mask)。 否則,函式會將權限設定為 mask & perms::mask。

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

函數報告錯誤,若 !is_symlink(pval)則回傳。path() 否則,函式會回傳一個包含符號連結的物件 path 。

remove

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

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

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;

這些函數會重新命名 from 為 to。 符號連結本身會被重新命名,而不是它選擇的檔案。

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;

函數交換左與右的內容。

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

這些函式會回傳路徑名稱的符號連結狀態、檔案類型及權限,這些都與 pval相關聯。 函式的行為與 相同 status(pval) ,只是符號連結本身被測試,而非它選擇的檔案。

system_complete

Note

C++17 std::filesystem 沒有提供 system_complete。 對於目前的程式碼,請在它提供所需行為時使用 std::filesystem::absolute 。

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

函式會回傳一個絕對路徑名稱,視需要考慮與其根名稱相關的當前目錄。 對於 POSIX,函數回傳 absolute(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 編碼的字元元素序列,無論檔案系統為何。

參見

<experimental/filesystem>
<experimental/filesystem> 列舉
<experimental/filesystem> 操作員