@spec cd(Path.t()) :: :ok | {:error, posix()}

設定目前的工作目錄。

BEAM 全域設定目前工作目錄。如果多個程序同時變更目前工作目錄，可能會導致競爭條件。若要在特定目錄中執行外部命令，而不會變更全域目前工作目錄，請使用 System.cmd/3 和 Port.open/2 的 :cd 選項。

如果成功，則傳回 :ok，否則傳回 {:error, reason}。

@spec cd!(Path.t()) :: :ok

與 cd/1 相同，但如果失敗，會引發 File.Error 例外。

@spec cd!(Path.t(), (-> res)) :: res when res: var

將目前目錄變更為指定的 path，執行指定的函數，然後無論是否有例外，都回復到前一個路徑。

BEAM 全域暫時設定目前工作目錄。如果多個程序同時變更目前工作目錄，可能會導致競爭條件。若要在特定目錄中執行外部命令，而不會變更全域目前工作目錄，請使用 System.cmd/3 和 Port.open/2 的 :cd 選項。

如果擷取或變更目前目錄失敗，則會引發錯誤。

@spec chgrp(Path.t(), non_neg_integer()) :: :ok | {:error, posix()}

變更指定 file 的群組，群組由群組 ID gid 指定。成功時傳回 :ok，失敗時傳回 {:error, reason}。

@spec chgrp!(Path.t(), non_neg_integer()) :: :ok

與 chgrp/2 相同，但如果失敗會引發 File.Error 例外。否則 :ok。

@spec chmod(Path.t(), non_neg_integer()) :: :ok | {:error, posix()}

變更給定 file 的 mode。

如果成功，則傳回 :ok，否則傳回 {:error, reason}。

權限

檔案權限透過將下列八進位模式加總來指定

• 0o400 - 讀取權限：擁有者

• 0o200 - 寫入權限：擁有者

• 0o100 - 執行權限：擁有者

• 0o040 - 讀取權限：群組

• 0o020 - 寫入權限：群組

• 0o010 - 執行權限：群組

• 0o004 - 讀取權限：其他

• 0o002 - 寫入權限：其他

• 0o001 - 執行權限：其他

例如，設定模式 0o755 會給予擁有者寫入、讀取和執行權限，並給予群組和其他人讀取和執行權限。

@spec chmod!(Path.t(), non_neg_integer()) :: :ok

與 chmod/2 相同，但如果失敗會引發 File.Error 例外。否則 :ok。

@spec chown(Path.t(), non_neg_integer()) :: :ok | {:error, posix()}

變更給定 file 的擁有者，由使用者 ID uid 給定。如果成功，傳回 :ok，否則傳回 {:error, reason}。

@spec chown!(Path.t(), non_neg_integer()) :: :ok

與 chown/2 相同，但如果失敗會引發 File.Error 例外。否則 :ok。

@spec close(io_device()) :: :ok | {:error, posix() | :badarg | :terminated}

關閉 io_device 參考的檔案。它通常會傳回 :ok，但有些嚴重錯誤（例如記憶體不足）除外。

請注意，如果在開啟檔案時使用了 :delayed_write 選項，close/1 可能會傳回舊的寫入錯誤，甚至不會嘗試關閉檔案。請參閱 open/2 以取得更多資訊。

@spec copy(Path.t() | io_device(), Path.t() | io_device(), pos_integer() | :infinity) ::
  {:ok, non_neg_integer()} | {:error, posix()}

將 source 的內容複製到 destination。

兩個參數都可以是檔案名稱或使用 open/2 開啟的 IO 裝置。bytes_count 指定要複製的位元組數，預設為 :infinity。

如果檔案 destination 已存在，它會被 source 中的內容覆寫。

如果成功，則傳回 {:ok, bytes_copied}，否則傳回 {:error, reason}。

與 cp/3 相比，此函式層級較低，允許從裝置複製到裝置，並受限於位元組數。另一方面，cp/3 會對來源和目的地執行更廣泛的檢查，且在複製後也會保留檔案模式。

典型的錯誤原因與 open/2、read/1 和 write/3 中相同。

@spec copy!(Path.t() | io_device(), Path.t() | io_device(), pos_integer() | :infinity) ::
  non_neg_integer()

與 copy/3 相同，但如果失敗會引發 File.CopyError 例外。否則傳回 bytes_copied。

@spec cp(Path.t(), Path.t(), [{:on_conflict, on_conflict_callback()}]) ::
  :ok | {:error, posix()}

將 source_file 的內容複製到 destination_file，並保留其模式。

source_file 必須是檔案或指向檔案的符號連結。destination_file 必須是非現有檔案的路徑。如果任一為目錄，則會傳回 {:error, :eisdir}。

此函式在成功時傳回 :ok。否則，傳回 {:error, reason}。

如果您想從一個 IO 裝置複製內容到另一個裝置，或從來源直接複製到目的地而不保留模式，請改為查看 copy/3。

注意：類 Unix 系統中的 cp 指令會根據目的地是否為現有目錄而有不同的行為。我們選擇明確禁止複製到目的地目錄，且如果嘗試這麼做會傳回錯誤。

選項

• :on_conflict - (自 v1.14.0 起) 在目的地中已存在檔案時呼叫。此函式接收 source_file 和 destination_file 的引數。如果應覆寫現有檔案，則應傳回 true；否則傳回 false。預設的回呼傳回 true。在較早的版本中，此回呼可以作為第三個引數提供，但此行為現已不建議使用。

@spec cp!(Path.t(), Path.t(), [{:on_conflict, on_conflict_callback()}]) :: :ok

與 cp/3 相同，但如果失敗會引發 File.CopyError 例外。否則傳回 :ok。

@spec cp_r(Path.t(), Path.t(),
  on_conflict: on_conflict_callback(),
  dereference_symlinks: boolean()
) ::
  {:ok, [binary()]} | {:error, posix(), binary()}

將 source 中的內容遞迴複製到 destination，並維護來源目錄結構和模式。

如果 source 是檔案或指向檔案的符號連結，則 destination 必須是現有檔案的路徑、指向檔案的符號連結或非現有檔案的路徑。

如果 source 是目錄或指向目錄的符號連結，則 destination 必須是現有的 directory 或指向目錄的符號連結，或非現有目錄的路徑。

如果來源是一個檔案，它會複製 source 到 destination。如果 source 是目錄，它會複製來源目錄內的內容到 destination 目錄。

如果目的地中已存在檔案，它會呼叫以選項提供的 on_conflict 回呼函式。更多資訊請參閱「選項」。

這個函式在複製檔案時可能會失敗，在這種情況下，它會讓目的地目錄處於不乾淨的狀態，其中已複製的檔案不會被移除。

如果成功，函式會傳回 {:ok, files_and_directories}，files_and_directories 會列出所有已複製的檔案和目錄，順序不特定。否則，它會傳回 {:error, reason, file}。

注意：類 Unix 系統中的 cp 指令會根據 destination 是否為現有目錄而有不同的行為。我們選擇明確禁止這種行為。如果 source 是 file 而 destination 是目錄，將會傳回 {:error, :eisdir}。

選項

• :on_conflict - (自 v1.14.0 起) 在目的地中已存在檔案時呼叫。函式會接收 source 和 destination 的引數。如果現有檔案應該被覆寫，它應該傳回 true；否則傳回 false。預設的回呼函式傳回 true。在較早的版本中，這個回呼函式可以作為第三個引數提供，但這種行為現在已不建議使用。

• :dereference_symlinks - (自 v1.14.0 起) 預設情況下，這個函式會透過建立指向相同位置的符號連結來複製符號連結。如果將此選項設定為 true，它會強制符號連結被取消引用，並複製其內容。如果取消引用的檔案不存在，則操作會失敗。預設值為 false。

範例

# Copies file "a.txt" to "b.txt"
File.cp_r("a.txt", "b.txt")

# Copies all files in "samples" to "tmp"
File.cp_r("samples", "tmp")

# Same as before, but asks the user how to proceed in case of conflicts
File.cp_r("samples", "tmp", on_conflict: fn source, destination ->
  IO.gets("Overwriting #{destination} by #{source}. Type y to confirm. ") == "y\n"
end)

@spec cp_r!(Path.t(), Path.t(),
  on_conflict: on_conflict_callback(),
  dereference_symlinks: boolean()
) ::
  [binary()]

與 cp_r/3 相同，但如果失敗會引發 File.CopyError 例外。否則傳回已複製檔案的清單。

@spec cwd() :: {:ok, binary()} | {:error, posix()}

取得目前的作業目錄。

在罕見的情況下，這個函式可能會在類 Unix 系統上失敗。如果目前目錄的父目錄沒有讀取權限，可能會發生這種情況。因此，如果成功，它會傳回 {:ok, cwd}；否則傳回 {:error, reason}。

@spec cwd!() :: binary()

與 cwd/0 相同，但如果失敗，會引發 File.Error 例外。

@spec dir?(Path.t(), [dir_option]) :: boolean() when dir_option: :raw

如果給定的路徑是目錄，則傳回 true。

這個函式會追蹤符號連結，因此如果符號連結指向目錄，它會傳回 true。

選項

支援的選項為

• :raw - 單一原子，用於繞過檔案伺服器，只在本地端檢查檔案

範例

File.dir?("./test")
#=> true

File.dir?("test")
#=> true

File.dir?("/usr/bin")
#=> true

File.dir?("~/Downloads")
#=> false

"~/Downloads" |> Path.expand() |> File.dir?()
#=> true

@spec exists?(Path.t(), [exists_option]) :: boolean() when exists_option: :raw

如果給定的路徑存在，則傳回 true。

它可以是常規檔案、目錄、socket、符號連結、命名管線或裝置檔案。對於指向不存在目標的符號連結，會傳回 false。

選項

支援的選項為

• :raw - 單一原子，用於繞過檔案伺服器，只在本地端檢查檔案

範例

File.exists?("test/")
#=> true

File.exists?("missing.txt")
#=> false

File.exists?("/dev/null")
#=> true

@spec ln(Path.t(), Path.t()) :: :ok | {:error, posix()}

為檔案 existing

如果成功，會傳回 :ok；否則會傳回 {:error, reason}。如果作業系統不支援硬連結，會傳回 {:error, :enotsup}。

@spec ln!(Path.t(), Path.t()) :: :ok

與 ln/2 相同，但如果失敗，會引發 File.LinkError 例外。否則傳回 :ok。

@spec ln_s(Path.t(), Path.t()) :: :ok | {:error, posix()}

為檔案或目錄 existing

如果成功，會傳回 :ok；否則會傳回 {:error, reason}。如果作業系統不支援符號連結，會傳回 {:error, :enotsup}。

@spec ln_s!(Path.t(), Path.t()) :: :ok

與 ln_s/2 相同，但如果失敗，會引發 File.LinkError 例外。否則傳回 :ok。

@spec ls(Path.t()) :: {:ok, [binary()]} | {:error, posix()}

傳回給定目錄中的檔案清單。

不忽略隱藏檔案，且結果不會排序。

由於檔案系統將目錄視為檔案，因此目錄也會包含在傳回值中。

如果成功，會傳回 {:ok, files}；否則會傳回 {:error, reason}。

@spec ls!(Path.t()) :: [binary()]

與 ls/1 相同，但如果發生錯誤，會引發 File.Error 例外。

@spec lstat(Path.t(), stat_options()) :: {:ok, File.Stat.t()} | {:error, posix()}

傳回 path

如需更多詳細資訊，請參閱 :file.read_link_info/2。

選項

可接受的選項為

• :time - 設定如何傳回檔案時間戳記

:time 的值可以是

• :universal - 傳回 UTC 中的 {date, time} 組合 (預設)
• :local - 使用機器時間傳回 {date, time} 組合
• :posix - 以自紀元以來的整數秒傳回時間

注意：由於大多數作業系統會以 POSIX 時間格式儲存檔案時間，因此使用 time: :posix 選項擷取檔案資訊會比較快。

@spec lstat!(Path.t(), stat_options()) :: File.Stat.t()

與 lstat/2 相同，但直接傳回 File.Stat 結構，或者如果傳回錯誤，則引發 File.Error 例外。

@spec mkdir(Path.t()) :: :ok | {:error, posix()}

嘗試建立目錄 path

不會建立遺失的父目錄。如果成功，則傳回 :ok，如果發生錯誤，則傳回 {:error, reason}。

典型的錯誤原因是

• :eacces - 遺失 path 父目錄的搜尋或寫入權限
• :eexist - 已經有檔案或目錄命名為 path
• :enoent - path 的組成元件不存在
• :enospc - 裝置上沒有剩餘空間
• :enotdir - path 的組成元件不是目錄；在某些平台上，會傳回 :enoent

@spec mkdir!(Path.t()) :: :ok

與 mkdir/1 相同，但如果失敗，會引發 File.Error 例外。否則為 :ok

@spec mkdir_p(Path.t()) :: :ok | {:error, posix()}

嘗試建立目錄 path

會建立遺失的父目錄。如果成功，則傳回 :ok，如果發生錯誤，則傳回 {:error, reason}。

典型的錯誤原因是

• :eacces - 遺失 path 父目錄的搜尋或寫入權限
• :enospc - 裝置上沒有剩餘空間
• :enotdir - path 的組成元件不是目錄

@spec mkdir_p!(Path.t()) :: :ok

與 mkdir_p/1 相同，但如果失敗，會引發 File.Error 例外。否則為 :ok

@spec open(Path.t(), [mode() | :ram]) :: {:ok, io_device()} | {:error, posix()}

@spec open(Path.t(), (io_device() -> res)) :: {:ok, res} | {:error, posix()}
when res: var

開啟給定的 path

為了寫入和讀取檔案，必須使用 IO 模組中的函式。預設情況下，檔案會以 :binary 模式開啟，這需要函式 IO.binread/2 和 IO.binwrite/2 與檔案互動。開發人員可以在開啟檔案時傳遞 :utf8 作為選項，然後 IO 中的所有其他函式都會可用，因為它們會直接使用 Unicode 資料。

modes_or_function 可以是模式清單或函式。如果它是清單，則會視為模式清單（如下所述）。如果它是函式，則等於呼叫 open(path, [], modes_or_function)。請參閱 open/3 的文件以取得關於此函式的更多資訊。

允許的模式

• :binary - 以二進位模式開啟檔案，停用 Unicode 順序的特殊處理（預設模式）。

• :read - 必須存在的檔案會開啟以進行讀取。

• :write - 檔案會開啟以進行寫入。如果檔案不存在，則會建立檔案。

  如果檔案存在，而且寫入未與讀取結合，則會截斷檔案。

• :append - 檔案將開啟為寫入模式，如果檔案不存在則會建立。對以附加模式開啟的檔案的每次寫入操作都將在檔案結尾進行。

• :exclusive - 開啟寫入模式時，如果檔案不存在則會建立。如果檔案存在，開啟將傳回 {:error, :eexist}。

• :charlist - 給定此參數時，檔案的讀取操作將傳回字元清單，而非二進位資料。

• :compressed - 使得可以讀取或寫入 gzip 壓縮檔案。

  壓縮選項必須與讀取或寫入結合使用，但不能同時使用。請注意，使用 stat/1 取得的檔案大小很可能與可以從壓縮檔案讀取的位元組數不符。

• :utf8 - 此選項表示資料實際儲存在磁碟檔案中的方式，並使檔案自動將字元轉換為 UTF-8 和從 UTF-8 轉換。

  如果傳送至檔案的資料無法轉換為 UTF-8，或如果資料是由傳回無法處理資料字元範圍的格式的資料的函式所讀取，則會發生錯誤，且檔案將關閉。

• :delayed_write, :raw, :ram, :read_ahead, :sync, {:encoding, ...}, {:read_ahead, pos_integer}, {:delayed_write, non_neg_integer, non_neg_integer} - 有關這些選項的詳細資訊，請參閱 :file.open/2。

此函式傳回

• {:ok, io_device} - 檔案已在請求的模式中開啟。

  io_device 實際上是處理檔案的程序的 PID。此程序會監控最初開啟檔案的程序（擁有者程序）。如果擁有者程序終止，則檔案將關閉，且程序本身也會終止。如果連結至 io_device 的任何程序終止，則檔案將關閉，且程序本身將終止。

  從此呼叫傳回的 io_device 可用作 IO 模組函式的引數。

• {:error, reason} - 檔案無法開啟。

範例

{:ok, file} = File.open("foo.tar.gz", [:read, :compressed])
IO.read(file, :line)
File.close(file)

@spec open(Path.t(), [mode() | :ram], (io_device() -> res)) ::
  {:ok, res} | {:error, posix()}
when res: var

類似於 open/2，但預期最後一個引數為函式。

檔案開啟後，作為引數傳遞給函式，並在函式傳回後自動關閉，不論在執行函式時是否發生錯誤。

傳回 {:ok, function_result} 表示成功，否則傳回 {:error, reason}。

此函式預期檔案會成功關閉，通常情況下會如此，除非有提供 :delayed_write 選項。因此，我們不建議將 :delayed_write 傳遞給此函式。

範例

File.open("file.txt", [:read, :write], fn file ->
  IO.read(file, :line)
end)

請參閱 open/2 以取得可用 modes 清單。

@spec open!(Path.t(), [mode() | :ram]) :: io_device()

@spec open!(Path.t(), (io_device() -> res)) :: res when res: var

類似於 open/2，但如果檔案無法開啟，會引發 File.Error 例外。否則傳回 IO 裝置。

請參閱 open/2 以取得可用模式清單。

@spec open!(Path.t(), [mode() | :ram], (io_device() -> res)) :: res when res: var

類似於 open/3，但如果檔案無法開啟，會引發 File.Error 例外。

如果成功開啟檔案，它會在 IO 裝置上傳回 function 結果。

請參閱 open/2 以取得可用 modes 清單。

@spec read(Path.t()) :: {:ok, binary()} | {:error, posix()}

傳回 {:ok, binary}，其中 binary 是包含 path 內容的二進制資料物件，或如果發生錯誤，傳回 {:error, reason}。

常見錯誤原因

• :enoent - 檔案不存在
• :eacces - 沒有讀取檔案或搜尋其中一個父目錄的權限
• :eisdir - 指定的檔案是目錄
• :enotdir - 檔案名稱的組成部分不是目錄；在某些平台上，會傳回 :enoent
• :enomem - 沒有足夠的記憶體儲存檔案內容

您可以使用 :file.format_error/1 取得錯誤的描述字串。

@spec read!(Path.t()) :: binary()

傳回包含指定檔案名稱內容的二進制資料，或如果發生錯誤，引發 File.Error 例外。

@spec read_link(Path.t()) :: {:ok, binary()} | {:error, posix()}

讀取 path 的符號連結。

如果 path 存在且為符號連結，傳回 {:ok, target}，否則傳回 {:error, reason}。

更多詳細資訊，請參閱 :file.read_link/1。

典型的錯誤原因是

• :einval - 路徑不是符號連結
• :enoent - 路徑不存在
• :enotsup - 目前平台不支援符號連結

@spec read_link!(Path.t()) :: binary()

與 read_link/1 相同，但直接傳回目標，或如果傳回錯誤，引發 File.Error 例外。

@spec regular?(Path.t(), [regular_option]) :: boolean() when regular_option: :raw

如果路徑是常規檔案，傳回 true。

此函式會追蹤符號連結，因此如果符號連結指向一般檔案，會傳回 true。

選項

支援的選項為

• :raw - 單一原子，用於繞過檔案伺服器，只在本地端檢查檔案

範例

File.regular?(__ENV__.file)
#=> true

@spec rename(Path.t(), Path.t()) :: :ok | {:error, posix()}

將 source 檔案重新命名為 destination 檔案。它可用於在目錄之間移動檔案（和目錄）。如果移動檔案，您必須完全指定 destination 檔案名稱，僅指定其目錄是不夠的。

如果成功，傳回 :ok，否則傳回 {:error, reason}。

注意：類 Unix 系統中的 mv 指令會根據 source 是否為檔案，以及 destination 是否為現有目錄而有不同的行為。我們選擇明確禁止這種行為。

範例

# Rename file "a.txt" to "b.txt"
File.rename("a.txt", "b.txt")

# Rename directory "samples" to "tmp"
File.rename("samples", "tmp")

@spec rename!(Path.t(), Path.t()) :: :ok

與 rename/2 相同，但如果失敗，會引發 File.RenameError 例外。否則傳回 :ok。

@spec rm(Path.t()) :: :ok | {:error, posix()}

嘗試刪除檔案 path。

如果成功，傳回 :ok，如果發生錯誤，傳回 {:error, reason}。

請注意，即使在唯讀模式下，檔案也會被刪除。

典型的錯誤原因是

• :enoent - 檔案不存在
• :eacces - 缺少檔案或其父項目的權限
• :eperm - 檔案是目錄，而使用者不是超級使用者
• :enotdir - 檔案名稱的組成部分不是目錄；在某些平台上，會傳回 :enoent
• :einval - 檔案名稱的類型不正確，例如元組

範例

File.rm("file.txt")
#=> :ok

File.rm("tmp_dir/")
#=> {:error, :eperm}

@spec rm!(Path.t()) :: :ok

與 rm/1 相同，但在失敗時會引發 File.Error 例外。否則為 :ok。

@spec rm_rf(Path.t()) :: {:ok, [binary()]} | {:error, posix(), binary()}

在指定的 path 遞迴移除檔案和目錄。符號連結不會被追蹤，而是直接移除，不存在的檔案會直接忽略（即不會導致此函式失敗）。

傳回 {:ok, files_and_directories}，其中包含以特定順序移除的所有檔案和目錄，否則傳回 {:error, reason, file}。

範例

File.rm_rf("samples")
#=> {:ok, ["samples", "samples/1.txt"]}

File.rm_rf("unknown")
#=> {:ok, []}

@spec rm_rf!(Path.t()) :: [binary()]

與 rm_rf/1 相同，但在失敗時會引發 File.Error 例外，否則會傳回已移除檔案或目錄的清單。

@spec rmdir(Path.t()) :: :ok | {:error, posix()}

嘗試刪除 path 的目錄。

如果成功，傳回 :ok，如果發生錯誤，傳回 {:error, reason}。如果目錄不為空，則傳回 {:error, :eexist}。

範例

File.rmdir("tmp_dir")
#=> :ok

File.rmdir("non_empty_dir")
#=> {:error, :eexist}

File.rmdir("file.txt")
#=> {:error, :enotdir}

@spec rmdir!(Path.t()) :: :ok | {:error, posix()}

與 rmdir/1 相同，但如果失敗，會引發 File.Error 例外。否則為 :ok。

@spec stat(Path.t(), stat_options()) :: {:ok, File.Stat.t()} | {:error, posix()}

傳回有關 path 的資訊。如果存在，會傳回 {:ok, info} 元組，其中 info 是 File.Stat 結構。如果發生失敗，會傳回 {:error, reason}，原因與 read/1 相同。

選項

可接受的選項為

• :time - 設定如何傳回檔案時間戳記

:time 的值可以是

• :universal - 傳回 UTC 中的 {date, time} 組合 (預設)
• :local - 使用與機器相同的時區傳回 {date, time} 元組
• :posix - 以自紀元以來的整數秒傳回時間

注意：由於大多數作業系統會以 POSIX 時間格式儲存檔案時間，因此使用 time: :posix 選項擷取檔案資訊會比較快。

@spec stat!(Path.t(), stat_options()) :: File.Stat.t()

與 stat/2 相同，但會直接傳回 File.Stat，或是在傳回錯誤時引發 File.Error 例外。

@spec stream!(Path.t(), :line | pos_integer() | [stream_mode()]) :: File.Stream.t()

File.stream!/3 的捷徑。

@spec stream!(Path.t(), :line | pos_integer(), [stream_mode()]) :: File.Stream.t()

傳回給定 path 的 File.Stream，並具有給定的 modes。

串流同時實作 Enumerable 和 Collectable 協定，這表示它可用於讀取和寫入。

line_or_bytes 參數透過 :line (預設) 或給定的位元組數，設定串流時檔案的讀取方式。使用 :line 選項時，CRLF 換行符 ("\r\n") 會正規化為 LF ("\n")。

類似於其他檔案操作，串流可以在一個節點中建立並轉發到另一個節點。一旦串流在另一個節點中開啟，要求就會被傳送給建立者節點，以產生檔案串流的程序。

操作串流可能會在開啟時失敗，原因與 File.open!/2 相同。請注意，每次串流開始時，檔案都會自動開啟。無需傳遞 :read 和 :write 模式，因為這些模式會由 Elixir 自動設定。

原始檔案

由於 Elixir 控制串流檔案開啟的時間，因此無法共用基礎裝置，因此出於效能考量，以原始模式開啟檔案很方便。因此，如果串流在與建立串流的節點中開啟，且未指定編碼，Elixir 將以 :raw 模式開啟串流，並使用 :read_ahead 選項。這表示串流到檔案中的任何資料都必須轉換為 iodata/0 類型。例如，如果你在模式參數中傳遞 [encoding: :utf8] 或 [encoding: {:utf16, :little}]，基礎串流將使用 IO.write/2 和 String.Chars 協定來轉換資料。請參閱 IO.binwrite/2 和 IO.write/2 。

如果串流要在緊密迴圈中寫入，你也可以考慮傳遞 :delayed_write 選項。

位元組順序標記和讀取偏移量

如果你在模式參數中傳遞 :trim_bom，串流會在從檔案讀取時修剪 UTF-8、UTF-16 和 UTF-32 位元組順序標記。

請注意，此函式不會嘗試根據 BOM 找出檔案編碼。從 Elixir v1.16.0 開始，你也可以傳遞 :read_offset，在列舉串流時會略過該偏移量（如果同時給定 :read_offset 和 :trim_bom，則會在 BOM 之後略過偏移量）。

範例

# Read a utf8 text file which may include BOM
File.stream!("./test/test.txt", [:trim_bom, encoding: :utf8])

# Read in 2048 byte chunks rather than lines
File.stream!("./test/test.data", 2048)

請參閱 Stream.run/1，以取得串流到檔案的範例。

@spec touch(Path.t(), erlang_time() | posix_time()) :: :ok | {:error, posix()}

更新給定檔案的修改時間 (mtime) 和存取時間 (atime)。

如果檔案不存在，則會建立檔案。需要以 UTC 格式提供日期時間 (由 :erlang.universaltime() 傳回)，或提供表示 POSIX 時間戳記的整數 (由 System.os_time(:second) 傳回)。

在類 Unix 系統中，變更修改時間可能需要您成為 root 或檔案的所有者。擁有寫入權限可能還不夠。在這些情況下，第一次觸及檔案 (建立檔案) 會成功，但觸及現有檔案會失敗，並傳回 {:error, :eperm}。

範例

File.touch("/tmp/a.txt", {{2018, 1, 30}, {13, 59, 59}})
#=> :ok
File.touch("/fakedir/b.txt", {{2018, 1, 30}, {13, 59, 59}})
{:error, :enoent}

File.touch("/tmp/a.txt", 1544519753)
#=> :ok

@spec touch!(Path.t(), erlang_time() | posix_time()) :: :ok

與 touch/2 相同，但如果失敗，會引發 File.Error 例外。否則傳回 :ok。

如果檔案不存在，則會建立檔案。需要以 UTC 格式提供日期時間 (由 :erlang.universaltime() 傳回)，或提供表示 POSIX 時間戳記的整數 (由 System.os_time(:second) 傳回)。

範例

File.touch!("/tmp/a.txt", {{2018, 1, 30}, {13, 59, 59}})
#=> :ok
File.touch!("/fakedir/b.txt", {{2018, 1, 30}, {13, 59, 59}})
** (File.Error) could not touch "/fakedir/b.txt": no such file or directory

File.touch!("/tmp/a.txt", 1544519753)

@spec write(Path.t(), iodata(), [mode()]) :: :ok | {:error, posix()}

將 content 寫入檔案 path。

如果檔案不存在，則會建立檔案。如果檔案存在，則會覆寫先前的內容。如果成功，則傳回 :ok，如果發生錯誤，則傳回 {:error, reason}。

content 必須是 iodata (位元組清單或二進位)。設定此函式的編碼並無作用。

警告：每次呼叫此函式時，都會開啟一個檔案描述子，並產生一個新的程序來寫入檔案。因此，如果您在迴圈中執行多次寫入，透過 File.open/2 開啟檔案，並使用 IO 中的函式寫入檔案，將會比多次呼叫此函式產生更好的效能。

典型的錯誤原因是

• :enoent - 檔案名稱的組成部分不存在
• :enotdir - 檔案名稱的組成部分不是目錄；在某些平台上，會傳回 :enoent
• :enospc - 裝置上沒有剩餘空間
• :eacces - 沒有寫入檔案或搜尋其中一個父目錄的權限
• :eisdir - 指定的檔案是目錄

請查看 File.open/2，以取得其他可用選項。

@spec write!(Path.t(), iodata(), [mode()]) :: :ok

與 write/3 相同，但如果失敗，會引發 File.Error 例外。否則傳回 :ok。

@spec write_stat(Path.t(), File.Stat.t(), stat_options()) :: :ok | {:error, posix()}

將給定的 File.Stat 寫回給定路徑的檔案系統。傳回 :ok 或 {:error, reason}。

@spec write_stat!(Path.t(), File.Stat.t(), stat_options()) :: :ok

與 write_stat/3 相同，但如果失敗，會引發 File.Error 例外。否則傳回 :ok。