-spec ensure_dir(Name) -> ok | {error, Reason}
                    when Name :: filename_all() | dirname_all(), Reason :: file:posix().

確保指定的檔案或目錄名稱 Name 的所有父目錄都存在，並在必要時嘗試建立它們。

如果所有父目錄已存在或可以建立，則傳回 ok。如果某些父目錄不存在且無法建立，則傳回 {error, Reason}。

-spec ensure_path(Path) -> ok | {error, Reason} when Path :: dirname_all(), Reason :: file:posix().

確保指定路徑 Path 的所有父目錄都存在，並在必要時嘗試建立它們。

與 ensure_dir/1 不同的是，此函式會嘗試將所有路徑區段都建立為目錄，包括最後一個區段。

如果所有父目錄已存在或可以建立，則傳回 ok。如果某些父目錄不存在且無法建立，則傳回 {error, Reason}。

-spec file_size(Filename) -> non_neg_integer() when Filename :: filename_all().

傳回指定檔案的大小。

-spec find_file(Filename :: filename(), Dir :: filename()) -> {ok, filename()} | {error, not_found}.

等同於 find_file(Filename, Dir, [])。

-spec find_file(filename(), filename(), [find_file_rule()]) -> {ok, filename()} | {error, not_found}.

透過將後綴規則套用至給定的目錄路徑，來尋找具有給定名稱的檔案。

例如，規則 {"ebin", "src"} 表示，如果目錄路徑以 "ebin" 結尾，則應搜尋以 "src" 結尾的對應路徑。

如果省略 Rules 或它是個空清單，則會使用預設系統規則。另請參閱 Kernel 應用程式參數 source_search_rules。

-spec find_source(filename()) -> {ok, filename()} | {error, not_found}.

等同於 find_source(Base, Dir)，其中 Dir 為 filename:dirname(FilePath)，而 Base 為 filename:basename(FilePath)。

-spec find_source(filename(), filename()) -> {ok, filename()} | {error, not_found}.

等同於 find_source(Filename, Dir, [])。

-spec find_source(filename(), filename(), [find_source_rule()]) -> {ok, filename()} | {error, not_found}.

套用檔案副檔名專屬規則，以尋找相對於物件目錄的給定物件檔案的來源檔案。

例如，對於副檔名為 .beam 的檔案，預設規則是透過將物件目錄路徑的後綴 "ebin" 替換為 "src" 或 "src/*"，來尋找具有對應副檔名 .erl 的檔案。檔案搜尋會透過 find_file/3 來完成。物件檔案的目錄始終在規則指定的任何其他目錄之前嘗試。

如果省略 Rules 或它是個空清單，則會使用預設系統規則。另請參閱 Kernel 應用程式參數 source_search_rules。

-spec fold_files(Dir, RegExp, Recursive, Fun, AccIn) -> AccOut
                    when
                        Dir :: dirname(),
                        RegExp :: string(),
                        Recursive :: boolean(),
                        Fun :: fun((F :: file:filename(), AccIn) -> AccOut),
                        AccIn :: term(),
                        AccOut :: term().

將函式 Fun 摺疊到目錄 Dir 中所有（一般）檔案 F 上，這些檔案的檔名（例如，"foo/bar/baz.erl" 中的 "baz.erl"）與正規表示式 RegExp 相符（如需允許的正規表示式的說明，請參閱 re 模組）。

如果 Recursive 為 true，則會處理 Dir 的所有子目錄。正規表示式比對只會在檔名上完成，而不包含目錄部分。

如果 Unicode 檔名轉換生效，且檔案系統是透明的，則可能會遇到無法解譯為 Unicode 的檔名，在這種情況下，fun() 必須準備好處理原始檔名（也就是二進位檔案）。如果正規表示式包含的碼點 > 255，則它不會比對不符合預期字元編碼的檔名（也就是，不是以有效的 UTF-8 編碼）。

關於原始檔名的詳細資訊，請參閱 file 模組。

-spec is_dir(Name) -> boolean() when Name :: filename_all() | dirname_all().

如果 Name 指的是目錄，則傳回 true，否則傳回 false。

-spec is_file(Name) -> boolean() when Name :: filename_all() | dirname_all().

如果 Name 指的是檔案或目錄，則傳回 true，否則傳回 false。

-spec is_regular(Name) -> boolean() when Name :: filename_all().

如果 Name 指的是（一般）檔案，則傳回 true，否則傳回 false。

-spec last_modified(Name) -> file:date_time() | 0 when Name :: filename_all() | dirname_all().

傳回指定的檔案或目錄上次修改的日期和時間，如果檔案不存在，則傳回 0。

-spec safe_relative_path(Filename, Cwd) -> unsafe | SafeFilename
                            when
                                Filename :: filename_all(),
                                Cwd :: filename_all(),
                                SafeFilename :: filename_all().

透過消除「..」和「.」元件來清除相對路徑，以防止目錄遍歷攻擊。

如果路徑不安全，則傳回已清除的路徑名稱或原子 unsafe。在下列情況下，該路徑被認為是不安全的：

• 該路徑不是相對路徑。
• 「..」元件會爬升到相對路徑的根目錄之上。
• 路徑中的符號連結指向相對路徑的根目錄之上。

範例

1> {ok, Cwd} = file:get_cwd().
...
2> filelib:safe_relative_path("dir/sub_dir/..", Cwd).
"dir"
3> filelib:safe_relative_path("dir/..", Cwd).
[]
4> filelib:safe_relative_path("dir/../..", Cwd).
unsafe
5> filelib:safe_relative_path("/abs/path", Cwd).
unsafe

-spec wildcard(Wildcard) -> [file:filename()] when Wildcard :: filename() | dirname().

傳回符合 Unix 樣式萬用字元字串 Wildcard 的所有檔案清單。

萬用字元字串看起來像是一般的檔名，但下列「萬用字元」會以特殊方式解譯：

• ? - 比對一個字元。

• * - 比對任何數量的字元，直到檔名結尾、下一個點或下一個斜線為止。

• ** - 兩個相鄰的 * 用作單一模式，比對所有檔案和零個或多個目錄及子目錄。

• [Character1,Character2,...] - 比對列出的任何字元。由連字號分隔的兩個字元會比對字元範圍。範例：[A-Z] 比對任何大寫字母。

• {Item,...} - 替代。比對其中一個替代方案。

其他字元代表它們本身。只有在相同位置具有完全相同字元的檔名才會比對。比對區分大小寫，例如，「a」不會比對「A」。

目錄分隔符號必須始終寫成 /，即使在 Windows 上也是如此。

以 \ 開頭的字元會失去其特殊含義。請注意，在字串常值中，\ 必須寫成 \\。例如，"\\?*" 將會比對任何以 ? 開頭的檔名。

請注意，允許多個「*」字元 (如同 Unix 萬用字元，但與 Windows/DOS 萬用字元相反)。

範例

以下範例假設目前目錄是 Erlang/OTP 安裝的頂層目錄。

若要尋找所有應用程式中的所有 .beam 檔案，請使用以下行：

filelib:wildcard("lib/*/ebin/*.beam").

若要尋找所有應用程式 src 目錄中的 .erl 或 .hrl 檔案，請使用以下任一行：

filelib:wildcard("lib/*/src/*.?rl")

filelib:wildcard("lib/*/src/*.{erl,hrl}")

若要尋找 src 或 include 目錄中的所有 .hrl 檔案：

filelib:wildcard("lib/*/{src,include}/*.hrl").

若要尋找 src 或 include 目錄中的所有 .erl 或 .hrl 檔案：

filelib:wildcard("lib/*/{src,include}/*.{erl,hrl}")

若要尋找任何子目錄中的所有 .erl 或 .hrl 檔案：

filelib:wildcard("lib/**/*.{erl,hrl}")

-spec wildcard(Wildcard, Cwd) -> [file:filename()]
                  when Wildcard :: filename() | dirname(), Cwd :: dirname().

與 wildcard/1 相同，不同之處在於會使用 Cwd 來代替工作目錄。