fuchsia.io

新增：7

通訊協定

AdvisoryLocking

定義於 fuchsia.io/locking.fidl

建議鎖定通訊協定。

這個通訊協定應整合至 |File| 通訊協定，以支援建議鎖定。

建議鎖定僅供參考，也不會阻止實際的讀取或寫入作業在檔案上發生，無論是透過這個連線或其他連線。

這些原始物件旨在支援 flock() 和 fcntl()，特別是 F_SETLK、F_SETLKW 和 F_GETLK，這些功能是 Fuchsia 上執行的程式碼預期從其他作業系統取得的功能。

AdvisoryLock

取得基礎檔案的建議鎖定。

鎖定狀態會持續到連線關閉，或使用 |AdvisoryLockType.UNLOCK| 呼叫這個方法，明確解除鎖定。

建議鎖定僅供參考，也不會阻止透過這個連線或其他連線，對檔案進行實際的讀取或寫入作業。

這個方法需要下列權限：

錯誤

  • ZX_ERR_BAD_STATE 無法取得指定的鎖定類型。舉例來說，另一個連線可能持有衝突的鎖定類型。
  • ZX_ERR_NOT_SUPPORTED 這個檔案不支援建議鎖定。
  • ZX_ERR_ACCESS_DENIED：這個連線沒有足夠權限，無法取得指定類型的鎖定。

要求

名稱類型
request AdvisoryLockRequest

回應

名稱類型
payload AdvisoryLocking_AdvisoryLock_Result

目錄

定義於 fuchsia.io/directory.fidl

目錄定義了可包含其他物件的節點。

AdvisoryLock

取得基礎檔案的建議鎖定。

鎖定狀態會持續到連線關閉，或使用 |AdvisoryLockType.UNLOCK| 呼叫這個方法，明確解除鎖定。

建議鎖定僅供參考，也不會阻止透過這個連線或其他連線，對檔案進行實際的讀取或寫入作業。

這個方法需要下列權限：

錯誤

  • ZX_ERR_BAD_STATE 無法取得指定的鎖定類型。舉例來說，另一個連線可能持有衝突的鎖定類型。
  • ZX_ERR_NOT_SUPPORTED 這個檔案不支援建議鎖定。
  • ZX_ERR_ACCESS_DENIED：這個連線沒有足夠權限，無法取得指定類型的鎖定。

要求

名稱類型
request AdvisoryLockRequest

回應

名稱類型
payload AdvisoryLocking_AdvisoryLock_Result

複製

新增：26

要求

名稱類型
request server_end:fuchsia.unknown/Cloneable

關閉

終止連線。

呼叫 Close 後，用戶端不得傳送任何其他要求。

伺服器傳送狀態回應後，無論狀態為何，都應關閉連線，且不傳送 epitaph。

關閉管道的用戶端，在語意上應等同於呼叫 Close，而不知道關閉作業何時完成或其狀態。

要求

<EMPTY>

回應

名稱類型
payload fuchsia.unknown/Closeable_Close_Result

建立符號連結。

name 是要為建立的符號連結指定的名稱。target 是符號連結的目標，在伺服器上沒有任何意義。除了伺服器選擇的長度上限外，伺服器不會對 target 執行任何驗證。connection 是管道的選用伺服器端，會在成功建立的節點上使用 Symlink 通訊協定。

  • Rights.MODIFY_DIRECTORY

  • 如果 name 已存在，則會發生錯誤 ZX_ERR_ALREADY_EXISTS。

  • 如果 target 超過伺服器對符號連結的長度限制，則會發生 ZX_ERR_BAD_PATH 錯誤。

  • 如果 name 不是有效的名稱，則會傳回錯誤 ZX_ERR_INVALID_ARGS。

  • 如果伺服器不支援建立符號連結，則會傳回錯誤 ZX_ERR_NOT_SUPPORTED。

新增：18
名稱類型
name Name
target SymlinkTarget
connection server_end:Symlink?
名稱類型
payload Directory_CreateSymlink_Result

DeprecatedClone

已淘汰 - 請改用 fuchsia.unknown/Cloneable.Clone。

已移除：29 已淘汰：27 已新增：26

要求

名稱類型
flags OpenFlags
object server_end:Node

DeprecatedGetAttr

已淘汰 - 請改用 Node.GetAttributes。

這個方法需要 Rights.GET_ATTRIBUTES 權限。

已淘汰：HEAD 新增：28

要求

<EMPTY>

回應

名稱類型
s zx/Result
attributes NodeAttributes

DeprecatedGetFlags

[已淘汰 - 請改用新的 GetFlags 方法。]

已淘汰：HEAD 已新增：27

要求

<EMPTY>

回應

名稱類型
s zx/Result
flags OpenFlags

DeprecatedGetToken

取得目錄的權杖，日後可用於識別目錄存取權。只要要求權杖的連線保持開啟，權杖就會持續有效。

這個方法需要下列權限：OpenFlags.RIGHT_WRITABLE，否則會傳回 ZX_ERR_BAD_HANDLE。

這個方法已淘汰：請改用 fuchsia.io/Node.GetToken (新增後)。

新增：NEXT

要求

<EMPTY>

回應

名稱類型
s zx/Result
token handle<handle>?

DeprecatedOpen

已淘汰 - 請改用 fuchsia.io/Directory.Open。

移除：32 新增：27

要求

名稱類型
flags OpenFlags
mode ModeType
path Path
object server_end:Node

DeprecatedSetAttr

已淘汰 - 請改用 Node.UpdateAttributes。

已淘汰：HEAD 新增：28

要求

名稱類型
flags NodeAttributeFlags
attributes NodeAttributes

回應

名稱類型
s zx/Result

DeprecatedSetFlags

[已淘汰 - 請改用新的 SetFlags 方法。]

已淘汰：HEAD 已新增：27

要求

名稱類型
flags OpenFlags

回應

名稱類型
s zx/Result

GetAttributes

取得節點相關資訊。

節點的屬性應保持穩定，不受用於存取節點的特定通訊協定影響。

如果特定屬性不適用或不支援，檔案系統應將對應欄位留空。

  • query：指定要擷取哪些屬性的位元遮罩。伺服器不應傳回超過必要數量的資料。
  • attributes傳回的屬性。

這個方法需要 Rights.GET_ATTRIBUTES 權限。

要求

名稱類型
query NodeAttributesQuery

回應

名稱類型
payload Node_GetAttributes_Result

GetExtendedAttribute

取得與這個節點指定屬性 name 相關聯的值。

屬性名稱長度上限為 MAX_ATTRIBUTE_NAME。不需遵循特定結構。

這個方法需要 Rights.READ_BYTES 權限。

新增：18

要求

名稱類型
name ExtendedAttributeName

回應

名稱類型
payload Node_GetExtendedAttribute_Result

GetFlags

在開啟/建立節點後，查詢適用於該節點的旗標。這個方法不需要任何權限。

請注意，適用於連線的最終旗標組合，可能與建立連線時使用的 fuchsia.io/Directory.Open 要求所指定的旗標不同：

  • Flags.PERM_INHERIT_*：僅在判斷連線權限時適用。
  • Flags.PROTOCOL_*：只會顯示連線的通訊協定。
  • Flags.FLAG_*：僅在開啟資源時適用，不屬於連線的一部分。
新增：27

要求

<EMPTY>

回應

名稱類型
payload Node_GetFlags_Result

GetToken

取得權杖，以便日後識別這項連線。只要要求權杖的連線保持開啟，權杖就會持續有效。

這個方法不需要任何權限。請注意，權杖會識別連線，因此會攜帶此連線的權限資訊。

新增：NEXT

要求

<EMPTY>

回應

名稱類型
payload Node_GetToken_Result

在權杖代表的目錄中，建立名為 dst 的連結，指向名為 src 的物件。

src 必須是已解析的物件名稱。如果字串中包含「/」，則會傳回 ZX_ERR_INVALID_ARGS。

dst 必須是已解析的物件名稱。如果字串中包含「/」，則會傳回 ZX_ERR_INVALID_ARGS。

這個方法需要下列權限：OpenFlags.RIGHT_WRITABLE 和 OpenFlags.RIGHT_READABLE，否則會傳回 ZX_ERR_BAD_HANDLE。

這項作業會以不可分割的方式執行，同時重新命名或取消連結來源，例如，如果有兩個執行者同時運作，其中一個執行者執行重新命名，影響這個目錄中的來源，另一個執行者執行連結，則每個執行者都會以未指定的順序不可分割地執行。

名稱類型
src Name
dst_parent_token handle<handle>
dst Name
名稱類型
s zx/Result

ListExtendedAttributes

為與這個節點相關聯的所有擴充屬性名稱建立疊代器。如果發生錯誤，系統會將錯誤做為疊代器要求管道上的墓誌銘傳回，然後關閉管道。

GetExtendedAttributes 可與上述任一名稱搭配使用，以擷取相關聯的值。

這個方法需要 Rights.READ_BYTES 權限。

新增：18

要求

名稱類型
iterator server_end:ExtendedAttributeIterator

OnOpen

如果 OpenFlags.DESCRIBE 要求，FIDL 伺服器會積極產生事件。

指出開啟作業成功或失敗，並視需要描述物件。如果狀態為 ZX_OK，info 會包含物件的描述性資訊 (與 Describe 傳回的資訊相同)。

已移除：32

回應

名稱類型
s zx/Result
info NodeInfoDeprecated?

OnRepresentation

如果 Flags.FLAG_SEND_REPRESENTATION 要求，伺服器會主動產生事件。這個事件會做為伺服器的第一則訊息傳送，且只會傳送一次。

有效變體對應至目標節點的協商通訊協定 (即這個管道目前使用的通訊協定)。此外，事件也會傳回輔助控制代碼和要求的屬性。

回應

名稱類型
payload Representation

開啟

開啟 (或建立) 相對於這個目錄的節點。如有任何錯誤，系統會透過 object 管道傳送墓誌銘來通知。

錯誤：

  • 如果 path 無效，則為 ZX_ERR_BAD_PATH
  • 請參閱「標記」一節，瞭解可能根據 flags 傳達的其他錯誤

要求

名稱類型
path Path
flags Flags
options Options
object handle<channel>

查詢

要求

<EMPTY>

回應

名稱類型
protocol vector<uint8>

QueryFilesystem

查詢檔案系統，取得檔案系統和/或磁碟區的詳細資料。如果目前的磁碟區有不同的設定，或儲存空間與檔案系統的其他部分分開計算，系統可能會回報該磁碟區的詳細資料，而非整個檔案系統的詳細資料。

要求

<EMPTY>

回應

名稱類型
s zx/Result
info FilesystemInfo?

ReadDirents

將大小不一的 dirent 集合讀取至緩衝區。目錄中的 dirent 數量可能非常龐大：類似於對檔案多次呼叫讀取，目錄具有搜尋偏移，會在後續呼叫 ReadDirents 時更新。每次呼叫 ReadDirents 都只會傳回完整的 dirent 結構，不會在 ReadDirent 呼叫之間分割。當跳轉偏移量到達結尾時，dirents 將為空白。

這些 dirent 的格式如下：

struct dirent {
  // Describes the inode of the entry.
  uint64 ino;
  // Describes the length of the dirent name in bytes.
  uint8 size;
  // Describes the type of the entry. Aligned with the
  // POSIX d_type values. Use `DirentType` constants.
  uint8 type;
  // Unterminated name of entry.
  char name[0];
}

這個方法需要下列權限：

要求

名稱類型
max_bytes uint64

回應

名稱類型
s zx/Result
dirents vector<uint8>:8192

RemoveExtendedAttribute

移除指定的擴充屬性。

如果屬性不存在，則會傳回 ZX_ERR_NOT_FOUND。

這個方法需要 Rights.WRITE_BYTES 權限。

新增：18

要求

名稱類型
name ExtendedAttributeName

回應

名稱類型
payload Node_RemoveExtendedAttribute_Result

重新命名

在 dst_parent_token 代表的目錄中，將名為 src 的節點重新命名為 dst。

src 和 dst 必須是有效的節點名稱。如要瞭解有效名稱的構成要素，請參閱「名稱」。

這個方法需要目前連線和 dst_parent_token 識別的連線具備下列權限：

請務必符合下列規定，以免權限升級。

如果來源和目的地目錄不同，來源目錄也必須具備檔案支援的最大能力組合，通常為 Rights.READ_BYTES、Rights.WRITE_BYTES、Rights.GET_ATTRIBUTES 和 Rights.UPDATE_ATTRIBUTES。部分檔案系統可能也支援 Rights.EXECUTE 權限。

如果 src 指向目錄，且與目的地目錄不同，則來源目錄也必須具備 Rights.CONNECT 和 Rights.TRAVERSE 權限。

  • 如果 src 或 dst 無效，則會傳回錯誤 ZX_ERR_INVALID_ARGS。
  • 錯誤 ZX_ERR_ACCESS_DENIED：權限不足。

要求

名稱類型
src Name
dst_parent_token Token
dst Name

回應

名稱類型
payload Directory_Rename_Result

倒轉

重設目錄搜尋偏移量。

這個方法需要下列權限：

要求

<EMPTY>

回應

名稱類型
s zx/Result

SetExtendedAttribute

將這個節點的指定屬性 name 值設為 value。

如果屬性名稱已存在，系統會更新該屬性。如果屬性不存在，系統會建立屬性。名稱不得包含空值位元組。如果發生這種情況，系統會傳回 ZX_ERR_INVALID_ARGS。

這個方法需要 Rights.WRITE_BYTES 權限。

新增：18

要求

名稱類型
name ExtendedAttributeName
value ExtendedAttributeValue
mode SetExtendedAttributeMode

回應

名稱類型
payload Node_SetExtendedAttribute_Result

SetFlags

設定開啟後要套用至這個節點的旗標。這個方法不需要任何權限。

目前僅支援 Flags.FILE_APPEND。呼叫這個方法時，如果不使用任何旗標，就會清除附加模式。

錯誤：

  • ZX_ERR_NOT_SUPPORTED：物件不支援這項功能或指定標記。
  • ZX_ERR_INVALID_ARGS：指定了 Flags.FILE_APPEND 以外的 flags。
新增：27

要求

名稱類型
flags Flags

回應

名稱類型
payload Node_SetFlags_Result

同步

將節點的更新同步至基礎媒體 (如有)。

當檔案系統伺服器將相關更新排清至基礎媒體時，這個方法會傳回，但不保證基礎媒體已保留資訊，也不保證任何資訊已提交至硬體。用戶端可以使用 Sync，確保作業之間的順序。

這個方法不需要任何權限。

要求

<EMPTY>

回應

名稱類型
payload Node_Sync_Result

從這個目錄的項目清單中移除子節點。

注意：這不保證基礎物件會遭到刪除。雖然連結會從包含的目錄中移除，但具有多個參照的物件 (例如仍開啟的檔案) 只有在所有參照都關閉後，才會實際刪除。

* 如果連線沒有 Rights.WRITE_BYTES，則會傳回錯誤 ZX_ERR_ACCESS_DENIED。* 如果基礎檔案系統不支援寫入，則會傳回錯誤 ZX_ERR_NOT_SUPPORTED。* 如果 name 無效，則會發生錯誤 ZX_ERR_BAD_PATH。* 如果 name 參照非空白目錄，則會發生錯誤 ZX_ERR_NOT_EMPTY。* 如果 name 參照包含遠端管道的掛接點，則會發生錯誤 ZX_ERR_UNAVAILABLE。* 如果選項要求目錄，但找到的不是目錄，則會發生錯誤 ZX_ERR_NOT_DIR。

其他錯誤可能是由檔案系統相關原因造成。

這個方法需要下列權限：

* Rights.ENUMERATE * Rights.MODIFY_DIRECTORY

名稱類型
name Name
options UnlinkOptions
名稱類型
payload Directory_Unlink_Result

UpdateAttributes

更新節點資訊。

  • attributes attributes 中有表格欄位，表示要更新對應的屬性。

如果節點不支援任何指定屬性，則傳回 ZX_ERR_NOT_SUPPORTED。

這個方法需要 Rights.UPDATE_ATTRIBUTES 權限。

要求

名稱類型
payload MutableNodeAttributes

回應

名稱類型
payload Node_UpdateAttributes_Result

智慧手錶

監控目錄，在監控器要求管道上接收新增訊息的事件。

選項必須為零，這是保留值。

這個方法需要下列權限：

要求

名稱類型
mask WatchMask
options uint32
watcher server_end:DirectoryWatcher

回應

名稱類型
s zx/Result

DirectoryWatcher

定義於 fuchsia.io/directory.fidl

DirectoryWatcher 會從檔案系統伺服器傳輸訊息，說明檔案系統中發生的事件。用戶端可以使用 Directory.Watch 方法註冊新的監控程式，並篩選要接收哪些事件的通知。

DirectoryWatcher 會傳送以下格式的訊息：

struct {
  uint8 event;
  uint8 len;
  char name[];
};

名稱「不」以空值結尾。名稱是事件參照項目的相對路徑。如果事件未參照特定項目 (例如 IDLE 事件)，這個欄位會留空。

ExtendedAttributeIterator

定義於 fuchsia.io/node.fidl

新增：18

GetNext

取得下一組擴充屬性名稱。如果這是最後一個區塊，last 會設為 true，且管道會在呼叫後關閉。

要求

<EMPTY>

回應

名稱類型
payload ExtendedAttributeIterator_GetNext_Result

檔案

定義於 fuchsia.io/file.fidl

包含特定長度位元組序列的節點。

注意：複製的連線不會與來源連線共用搜尋偏移量。

AdvisoryLock

取得基礎檔案的建議鎖定。

鎖定狀態會持續到連線關閉，或使用 |AdvisoryLockType.UNLOCK| 呼叫這個方法，明確解除鎖定。

建議鎖定僅供參考，也不會阻止透過這個連線或其他連線，對檔案進行實際的讀取或寫入作業。

這個方法需要下列權限：

錯誤

  • ZX_ERR_BAD_STATE 無法取得指定的鎖定類型。舉例來說，另一個連線可能持有衝突的鎖定類型。
  • ZX_ERR_NOT_SUPPORTED 這個檔案不支援建議鎖定。
  • ZX_ERR_ACCESS_DENIED：這個連線沒有足夠權限，無法取得指定類型的鎖定。

要求

名稱類型
request AdvisoryLockRequest

回應

名稱類型
payload AdvisoryLocking_AdvisoryLock_Result

分配

為這個檔案預先分配磁碟空間。

新增：HEAD

要求

名稱類型
offset uint64
length uint64
mode AllocateMode

回應

名稱類型
payload File_Allocate_Result

複製

新增：26

要求

名稱類型
request server_end:fuchsia.unknown/Cloneable

關閉

終止連線。

呼叫 Close 後，用戶端不得傳送任何其他要求。

伺服器傳送狀態回應後，無論狀態為何，都應關閉連線，且不傳送 epitaph。

關閉管道的用戶端，在語意上應等同於呼叫 Close，而不知道關閉作業何時完成或其狀態。

要求

<EMPTY>

回應

名稱類型
payload fuchsia.unknown/Closeable_Close_Result

DeprecatedClone

已淘汰 - 請改用 fuchsia.unknown/Cloneable.Clone。

已移除：29 已淘汰：27 已新增：26

要求

名稱類型
flags OpenFlags
object server_end:Node

DeprecatedGetAttr

已淘汰 - 請改用 Node.GetAttributes。

這個方法需要 Rights.GET_ATTRIBUTES 權限。

已淘汰：HEAD 新增：28

要求

<EMPTY>

回應

名稱類型
s zx/Result
attributes NodeAttributes

DeprecatedGetFlags

[已淘汰 - 請改用新的 GetFlags 方法。]

已淘汰：HEAD 已新增：27

要求

<EMPTY>

回應

名稱類型
s zx/Result
flags OpenFlags

DeprecatedSetAttr

已淘汰 - 請改用 Node.UpdateAttributes。

已淘汰：HEAD 新增：28

要求

名稱類型
flags NodeAttributeFlags
attributes NodeAttributes

回應

名稱類型
s zx/Result

DeprecatedSetFlags

[已淘汰 - 請改用新的 SetFlags 方法。]

已淘汰：HEAD 已新增：27

要求

名稱類型
flags OpenFlags

回應

名稱類型
s zx/Result

描述

要求

<EMPTY>

回應

名稱類型
payload FileInfo

EnableVerity

為檔案啟用驗證功能 (永久)，包括為檔案計算 Merkle 樹狀結構。在建構 Merkle 樹狀結構前強制清除，確保擷取快取資料。日後的讀取作業會根據計算出的 Merkle 樹狀結構進行驗證，寫入作業則會遭到拒絕。視檔案大小而定，這個方法可能需要一些時間才能完成。如要取消這個方法，可以關閉發出這個方法的連線。

這個方法需要 Rights.UPDATE_ATTRIBUTES 權限。如果檔案系統不支援 Verity，則傳回 ZX_ERR_NOT_SUPPORTED。如果檔案已啟用 fsverity，則傳回 ZX_ERR_ALREADY_EXISTS。此外，也會傳回讀取或清除檔案時可能發生的任何錯誤，例如 ZX_ERR_IO。

新增：HEAD

要求

名稱類型
options VerificationOptions

回應

名稱類型
payload File_EnableVerity_Result

GetAttributes

取得節點相關資訊。

節點的屬性應保持穩定，不受用於存取節點的特定通訊協定影響。

如果特定屬性不適用或不支援，檔案系統應將對應欄位留空。

  • query：指定要擷取哪些屬性的位元遮罩。伺服器不應傳回超過必要數量的資料。
  • attributes傳回的屬性。

這個方法需要 Rights.GET_ATTRIBUTES 權限。

要求

名稱類型
query NodeAttributesQuery

回應

名稱類型
payload Node_GetAttributes_Result

GetBackingMemory

取得代表這個檔案的 zx.Handle:VMO (如有)，並具備要求的存取權。

實作項目不一定要實作 VMO 支援的檔案，因此這項要求可能會失敗。此外，實作可能僅支援特定旗標子集。用戶端應準備好備用行為，以防這項要求失敗。

如果用戶端未指定 PRIVATE_CLONE 或 SHARED_BUFFER，則實作項目可自由選擇傳回 VMO 的語意。

  • 要求 flags VmoFlags，指出所需的存取模式。

這個方法需要下列權限：

要求

名稱類型
flags VmoFlags

回應

名稱類型
payload File_GetBackingMemory_Result

GetExtendedAttribute

取得與這個節點指定屬性 name 相關聯的值。

屬性名稱長度上限為 MAX_ATTRIBUTE_NAME。不需遵循特定結構。

這個方法需要 Rights.READ_BYTES 權限。

新增：18

要求

名稱類型
name ExtendedAttributeName

回應

名稱類型
payload Node_GetExtendedAttribute_Result

GetFlags

在開啟/建立節點後，查詢適用於該節點的旗標。這個方法不需要任何權限。

請注意，適用於連線的最終旗標組合，可能與建立連線時使用的 fuchsia.io/Directory.Open 要求所指定的旗標不同：

  • Flags.PERM_INHERIT_*：僅在判斷連線權限時適用。
  • Flags.PROTOCOL_*：只會顯示連線的通訊協定。
  • Flags.FLAG_*：僅在開啟資源時適用，不屬於連線的一部分。
新增：27

要求

<EMPTY>

回應

名稱類型
payload Node_GetFlags_Result

GetToken

取得權杖，以便日後識別這項連線。只要要求權杖的連線保持開啟，權杖就會持續有效。

這個方法不需要任何權限。請注意，權杖會識別連線，因此會攜帶此連線的權限資訊。

新增：NEXT

要求

<EMPTY>

回應

名稱類型
payload Node_GetToken_Result

LinkInto

在 dst_parent_token 代表的目錄中，建立這個物件的連結，名稱為 dst。

dst 必須是已解析的物件名稱。如果字串中包含「/」，則會傳回 ZX_ERR_INVALID_ARGS。

這個方法需要檔案系統支援此物件的最大權限集。如果是檔案，通常會是 Rights.READ_BYTES、Rights.WRITE_BYTES、Rights.GET_ATTRIBUTES 和 Rights.UPDATE_ATTRIBUTES。部分檔案系統也可能支援 Rights.EXECUTE 權限。權限不足會導致 ZX_ERR_ACCESS_DENIED。

如果這個物件沒有連結，且「不是」未命名的暫存物件 (使用 Flags.FLAG_CREATE_AS_UNNAMED_TEMPORARY 開啟的物件)，則會失敗並傳回 ZX_ERR_NOT_FOUND。

如果是未命名的臨時物件，請使用 LinkInto 命名。成功完成後，物件會永久連結至檔案系統。要求未命名的暫存物件可連結，否則會失敗並顯示 ZX_ERR_NOT_FOUND。

這個方法不具備與 Directory::Link 方法相同的原子性屬性，也就是說，先呼叫 Open 再呼叫 LinkInto 不等於 Directory::Link，因為 LinkInto 不會防止來源重新命名或取消連結。

要求

名稱類型
dst_parent_token Token
dst Name

回應

名稱類型
payload Linkable_LinkInto_Result

ListExtendedAttributes

為與這個節點相關聯的所有擴充屬性名稱建立疊代器。如果發生錯誤，系統會將錯誤做為疊代器要求管道上的墓誌銘傳回，然後關閉管道。

GetExtendedAttributes 可與上述任一名稱搭配使用，以擷取相關聯的值。

這個方法需要 Rights.READ_BYTES 權限。

新增：18

要求

名稱類型
iterator server_end:ExtendedAttributeIterator

OnOpen

如果 OpenFlags.DESCRIBE 要求，FIDL 伺服器會積極產生事件。

指出開啟作業成功或失敗，並視需要描述物件。如果狀態為 ZX_OK，info 會包含物件的描述性資訊 (與 Describe 傳回的資訊相同)。

已移除：32

回應

名稱類型
s zx/Result
info NodeInfoDeprecated?

OnRepresentation

如果 Flags.FLAG_SEND_REPRESENTATION 要求，伺服器會主動產生事件。這個事件會做為伺服器的第一則訊息傳送，且只會傳送一次。

有效變體對應至目標節點的協商通訊協定 (即這個管道目前使用的通訊協定)。此外，事件也會傳回輔助控制代碼和要求的屬性。

回應

名稱類型
payload Representation

查詢

要求

<EMPTY>

回應

名稱類型
protocol vector<uint8>

QueryFilesystem

查詢檔案系統，取得檔案系統和/或磁碟區的詳細資料。如果目前的磁碟區有不同的設定，或儲存空間與檔案系統的其他部分分開計算，系統可能會回報該磁碟區的詳細資料，而非整個檔案系統的詳細資料。

要求

<EMPTY>

回應

名稱類型
s zx/Result
info FilesystemInfo?

閱讀

在跳轉偏移量讀取最多「count」個位元組。搜尋偏移量會根據讀取的位元組數向前移動。

不變量

  • 傳回的 data.length 絕不會大於 count。
  • 如果 data.length 小於 count，表示跳轉偏移量已達到檔案結尾，這是這項作業的一部分。
  • 如果 data.length 為零，而 count 不為零，表示搜尋偏移量已達到或超過檔案結尾，無法讀取任何資料。
  • 如果 count 為零，伺服器應執行所有檢查，確保讀取權限，而不實際讀取任何內容，並傳回空白的 data 向量。

這個方法需要 Rights.READ_BYTES 權限。

如果 count 大於 MAX_TRANSFER_SIZE，則傳回 ZX_ERR_OUT_OF_RANGE。

要求

名稱類型
count uint64

回應

名稱類型
payload Readable_Read_Result

ReadAt

在提供的偏移量讀取最多「count」個位元組。不會影響跳轉偏移。

不變量

  • 傳回的 data.length 絕不會大於 count。
  • 如果 data.length 小於 count，表示 ReadAt 在這項作業中已達到檔案結尾。
  • 如果 data.length 為零，但 count 不為零，表示 offset 已達到或超過檔案結尾，無法讀取任何資料。
  • 如果 count 為零，伺服器應執行所有檢查，確保讀取權限，而不實際讀取任何內容，並傳回空白的 data 向量。

這個方法需要 Rights.READ_BYTES 權限。

如果 count 大於 MAX_TRANSFER_SIZE，則傳回 ZX_ERR_OUT_OF_RANGE。

要求

名稱類型
count uint64
offset uint64

回應

名稱類型
payload File_ReadAt_Result

RemoveExtendedAttribute

移除指定的擴充屬性。

如果屬性不存在，則會傳回 ZX_ERR_NOT_FOUND。

這個方法需要 Rights.WRITE_BYTES 權限。

新增：18

要求

名稱類型
name ExtendedAttributeName

回應

名稱類型
payload Node_RemoveExtendedAttribute_Result

調整大小

將檔案大小縮減或增加至「length」位元組。

如果這項作業縮減了檔案大小，系統會捨棄多餘的結尾資料。如果這項作業會增加檔案大小，擴充區域會顯示為零。

這個方法需要 Rights.WRITE_BYTES 權限。

要求

名稱類型
length uint64

回應

名稱類型
payload File_Resize_Result

搜尋

移動下次叫用 Read 或 Write 時的偏移量。跳轉偏移量因檔案連線而異。

  • 要求 origin offset 的參考點。
  • 要求 offset 要跳轉的位元組數。
  • 回應 offset_from_start 調整後的跳轉偏移量 (從檔案開頭算起)。

這個方法不需要任何權限。

要求

名稱類型
origin SeekOrigin
offset int64

回應

名稱類型
payload File_Seek_Result

SetExtendedAttribute

將這個節點的指定屬性 name 值設為 value。

如果屬性名稱已存在，系統會更新該屬性。如果屬性不存在，系統會建立屬性。名稱不得包含空值位元組。如果發生這種情況，系統會傳回 ZX_ERR_INVALID_ARGS。

這個方法需要 Rights.WRITE_BYTES 權限。

新增：18

要求

名稱類型
name ExtendedAttributeName
value ExtendedAttributeValue
mode SetExtendedAttributeMode

回應

名稱類型
payload Node_SetExtendedAttribute_Result

SetFlags

設定開啟後要套用至這個節點的旗標。這個方法不需要任何權限。

目前僅支援 Flags.FILE_APPEND。呼叫這個方法時，如果不使用任何旗標，就會清除附加模式。

錯誤：

  • ZX_ERR_NOT_SUPPORTED：物件不支援這項功能或指定標記。
  • ZX_ERR_INVALID_ARGS：指定了 Flags.FILE_APPEND 以外的 flags。
新增：27

要求

名稱類型
flags Flags

回應

名稱類型
payload Node_SetFlags_Result

同步

將節點的更新同步至基礎媒體 (如有)。

當檔案系統伺服器將相關更新排清至基礎媒體時，這個方法會傳回，但不保證基礎媒體已保留資訊，也不保證任何資訊已提交至硬體。用戶端可以使用 Sync，確保作業之間的順序。

這個方法不需要任何權限。

要求

<EMPTY>

回應

名稱類型
payload Node_Sync_Result

UpdateAttributes

更新節點資訊。

  • attributes attributes 中有表格欄位，表示要更新對應的屬性。

如果節點不支援任何指定屬性，則傳回 ZX_ERR_NOT_SUPPORTED。

這個方法需要 Rights.UPDATE_ATTRIBUTES 權限。

要求

名稱類型
payload MutableNodeAttributes

回應

名稱類型
payload Node_UpdateAttributes_Result

寫入

在搜尋偏移量寫入資料。搜尋偏移量會根據寫入的位元組數向前移動。如果檔案處於附加模式，系統會先將搜尋偏移量設為檔案結尾，然後在一個原子步驟中寫入。

如果搜尋偏移量加上 data.length 超過目前的檔案結尾，檔案大小可能會增加。

  • 要求 data 位元組緩衝區寫入檔案。
  • 回應 actual_count 寫入的位元組數。

不變量

  • 傳回的 actual_count 絕不會大於 data.length。
  • 如果伺服器因空間不足等原因而無法寫入所有資料，actual_count 可能會小於 data.length。如果無法寫入任何位元組，系統會傳回錯誤。
  • 如果 data.length 為零，伺服器應執行所有檢查，確保寫入權限不會變更檔案，並傳回成功寫入零個位元組。如果處於附加模式，系統仍會更新跳轉偏移量。

這個方法需要 Rights.WRITE_BYTES 權限。

要求

名稱類型
data Transfer

回應

名稱類型
payload Writable_Write_Result

WriteAt

在提供的偏移量寫入資料。不會影響跳轉偏移。

如果 offset 加上 data.length 超過目前的檔案結尾，檔案大小可能會增加。

  • 要求 data 位元組緩衝區寫入檔案。
  • 要求 offset 從檔案開頭的偏移量開始寫入。
  • 回應 actual_count 寫入的位元組數。

不變量

  • 傳回的 actual_count 絕不會大於 data.length。
  • 如果伺服器因空間不足等原因而無法寫入所有資料，actual_count 可能會小於 data.length。如果無法寫入任何位元組，系統會傳回錯誤。
  • 如果 data.length 為零，伺服器應執行所有檢查，確保寫入權限不會變更檔案，並傳回成功寫入零個位元組。

這個方法需要 Rights.WRITE_BYTES 權限。

要求

名稱類型
data Transfer
offset uint64

回應

名稱類型
payload File_WriteAt_Result

可連結

定義於 fuchsia.io/node.fidl

新增：18

LinkInto

在 dst_parent_token 代表的目錄中，建立這個物件的連結，名稱為 dst。

dst 必須是已解析的物件名稱。如果字串中包含「/」，則會傳回 ZX_ERR_INVALID_ARGS。

這個方法需要檔案系統支援此物件的最大權限集。如果是檔案，通常會是 Rights.READ_BYTES、Rights.WRITE_BYTES、Rights.GET_ATTRIBUTES 和 Rights.UPDATE_ATTRIBUTES。部分檔案系統也可能支援 Rights.EXECUTE 權限。權限不足會導致 ZX_ERR_ACCESS_DENIED。

如果這個物件沒有連結，且「不是」未命名的暫存物件 (使用 Flags.FLAG_CREATE_AS_UNNAMED_TEMPORARY 開啟的物件)，則會失敗並傳回 ZX_ERR_NOT_FOUND。

如果是未命名的臨時物件，請使用 LinkInto 命名。成功完成後，物件會永久連結至檔案系統。要求未命名的暫存物件可連結，否則會失敗並顯示 ZX_ERR_NOT_FOUND。

這個方法不具備與 Directory::Link 方法相同的原子性屬性，也就是說，先呼叫 Open 再呼叫 LinkInto 不等於 Directory::Link，因為 LinkInto 不會防止來源重新命名或取消連結。

要求

名稱類型
dst_parent_token Token
dst Name

回應

名稱類型
payload Linkable_LinkInto_Result

節點

定義於 fuchsia.io/node.fidl

節點會定義可在檔案系統中存取的實體最小介面。

複製

新增：26

要求

名稱類型
request server_end:fuchsia.unknown/Cloneable

關閉

終止連線。

呼叫 Close 後，用戶端不得傳送任何其他要求。

伺服器傳送狀態回應後，無論狀態為何，都應關閉連線，且不傳送 epitaph。

關閉管道的用戶端，在語意上應等同於呼叫 Close，而不知道關閉作業何時完成或其狀態。

要求

<EMPTY>

回應

名稱類型
payload fuchsia.unknown/Closeable_Close_Result

DeprecatedClone

已淘汰 - 請改用 fuchsia.unknown/Cloneable.Clone。

已移除：29 已淘汰：27 已新增：26

要求

名稱類型
flags OpenFlags
object server_end:Node

DeprecatedGetAttr

已淘汰 - 請改用 Node.GetAttributes。

這個方法需要 Rights.GET_ATTRIBUTES 權限。

已淘汰：HEAD 新增：28

要求

<EMPTY>

回應

名稱類型
s zx/Result
attributes NodeAttributes

DeprecatedGetFlags

[已淘汰 - 請改用新的 GetFlags 方法。]

已淘汰：HEAD 已新增：27

要求

<EMPTY>

回應

名稱類型
s zx/Result
flags OpenFlags

DeprecatedSetAttr

已淘汰 - 請改用 Node.UpdateAttributes。

已淘汰：HEAD 新增：28

要求

名稱類型
flags NodeAttributeFlags
attributes NodeAttributes

回應

名稱類型
s zx/Result

DeprecatedSetFlags

[已淘汰 - 請改用新的 SetFlags 方法。]

已淘汰：HEAD 已新增：27

要求

名稱類型
flags OpenFlags

回應

名稱類型
s zx/Result

GetAttributes

取得節點相關資訊。

節點的屬性應保持穩定，不受用於存取節點的特定通訊協定影響。

如果特定屬性不適用或不支援，檔案系統應將對應欄位留空。

  • query：指定要擷取哪些屬性的位元遮罩。伺服器不應傳回超過必要數量的資料。
  • attributes傳回的屬性。

這個方法需要 Rights.GET_ATTRIBUTES 權限。

要求

名稱類型
query NodeAttributesQuery

回應

名稱類型
payload Node_GetAttributes_Result

GetExtendedAttribute

取得與這個節點指定屬性 name 相關聯的值。

屬性名稱長度上限為 MAX_ATTRIBUTE_NAME。不需遵循特定結構。

這個方法需要 Rights.READ_BYTES 權限。

新增：18

要求

名稱類型
name ExtendedAttributeName

回應

名稱類型
payload Node_GetExtendedAttribute_Result

GetFlags

在開啟/建立節點後，查詢適用於該節點的旗標。這個方法不需要任何權限。

請注意，適用於連線的最終旗標組合，可能與建立連線時使用的 fuchsia.io/Directory.Open 要求所指定的旗標不同：

  • Flags.PERM_INHERIT_*：僅在判斷連線權限時適用。
  • Flags.PROTOCOL_*：只會顯示連線的通訊協定。
  • Flags.FLAG_*：僅在開啟資源時適用，不屬於連線的一部分。
新增：27

要求

<EMPTY>

回應

名稱類型
payload Node_GetFlags_Result

GetToken

取得權杖，以便日後識別這項連線。只要要求權杖的連線保持開啟，權杖就會持續有效。

這個方法不需要任何權限。請注意，權杖會識別連線，因此會攜帶此連線的權限資訊。

新增：NEXT

要求

<EMPTY>

回應

名稱類型
payload Node_GetToken_Result

ListExtendedAttributes

為與這個節點相關聯的所有擴充屬性名稱建立疊代器。如果發生錯誤，系統會將錯誤做為疊代器要求管道上的墓誌銘傳回，然後關閉管道。

GetExtendedAttributes 可與上述任一名稱搭配使用，以擷取相關聯的值。

這個方法需要 Rights.READ_BYTES 權限。

新增：18

要求

名稱類型
iterator server_end:ExtendedAttributeIterator

OnOpen

如果 OpenFlags.DESCRIBE 要求，FIDL 伺服器會積極產生事件。

指出開啟作業成功或失敗，並視需要描述物件。如果狀態為 ZX_OK，info 會包含物件的描述性資訊 (與 Describe 傳回的資訊相同)。

已移除：32

回應

名稱類型
s zx/Result
info NodeInfoDeprecated?

OnRepresentation

如果 Flags.FLAG_SEND_REPRESENTATION 要求，伺服器會主動產生事件。這個事件會做為伺服器的第一則訊息傳送，且只會傳送一次。

有效變體對應至目標節點的協商通訊協定 (即這個管道目前使用的通訊協定)。此外，事件也會傳回輔助控制代碼和要求的屬性。

回應

名稱類型
payload Representation

查詢

要求

<EMPTY>

回應

名稱類型
protocol vector<uint8>

QueryFilesystem

查詢檔案系統，取得檔案系統和/或磁碟區的詳細資料。如果目前的磁碟區有不同的設定，或儲存空間與檔案系統的其他部分分開計算，系統可能會回報該磁碟區的詳細資料，而非整個檔案系統的詳細資料。

要求

<EMPTY>

回應

名稱類型
s zx/Result
info FilesystemInfo?

RemoveExtendedAttribute

移除指定的擴充屬性。

如果屬性不存在，則會傳回 ZX_ERR_NOT_FOUND。

這個方法需要 Rights.WRITE_BYTES 權限。

新增：18

要求

名稱類型
name ExtendedAttributeName

回應

名稱類型
payload Node_RemoveExtendedAttribute_Result

SetExtendedAttribute

將這個節點的指定屬性 name 值設為 value。

如果屬性名稱已存在，系統會更新該屬性。如果屬性不存在，系統會建立屬性。名稱不得包含空值位元組。如果發生這種情況，系統會傳回 ZX_ERR_INVALID_ARGS。

這個方法需要 Rights.WRITE_BYTES 權限。

新增：18

要求

名稱類型
name ExtendedAttributeName
value ExtendedAttributeValue
mode SetExtendedAttributeMode

回應

名稱類型
payload Node_SetExtendedAttribute_Result

SetFlags

設定開啟後要套用至這個節點的旗標。這個方法不需要任何權限。

目前僅支援 Flags.FILE_APPEND。呼叫這個方法時，如果不使用任何旗標，就會清除附加模式。

錯誤：

  • ZX_ERR_NOT_SUPPORTED：物件不支援這項功能或指定標記。
  • ZX_ERR_INVALID_ARGS：指定了 Flags.FILE_APPEND 以外的 flags。
新增：27

要求

名稱類型
flags Flags

回應

名稱類型
payload Node_SetFlags_Result

同步

將節點的更新同步至基礎媒體 (如有)。

當檔案系統伺服器將相關更新排清至基礎媒體時，這個方法會傳回，但不保證基礎媒體已保留資訊，也不保證任何資訊已提交至硬體。用戶端可以使用 Sync，確保作業之間的順序。

這個方法不需要任何權限。

要求

<EMPTY>

回應

名稱類型
payload Node_Sync_Result

UpdateAttributes

更新節點資訊。

  • attributes attributes 中有表格欄位，表示要更新對應的屬性。

如果節點不支援任何指定屬性，則傳回 ZX_ERR_NOT_SUPPORTED。

這個方法需要 Rights.UPDATE_ATTRIBUTES 權限。

要求

名稱類型
payload MutableNodeAttributes

回應

名稱類型
payload Node_UpdateAttributes_Result

可開啟

定義於 fuchsia.io/openable.fidl

Openable 定義了可開啟其他物件的節點。

新增：31

開啟

開啟 (或建立) 相對於這個目錄的節點。如有任何錯誤，系統會透過 object 管道傳送墓誌銘來通知。

錯誤：

  • 如果 path 無效，則為 ZX_ERR_BAD_PATH
  • 請參閱「標記」一節，瞭解可能根據 flags 傳達的其他錯誤

要求

名稱類型
path Path
flags Flags
options Options
object handle<channel>

可閱覽

定義於 fuchsia.io/file.fidl

閱讀

在跳轉偏移量讀取最多「count」個位元組。搜尋偏移量會根據讀取的位元組數向前移動。

不變量

  • 傳回的 data.length 絕不會大於 count。
  • 如果 data.length 小於 count，表示跳轉偏移量已達到檔案結尾，這是這項作業的一部分。
  • 如果 data.length 為零，而 count 不為零，表示搜尋偏移量已達到或超過檔案結尾，無法讀取任何資料。
  • 如果 count 為零，伺服器應執行所有檢查，確保讀取權限，而不實際讀取任何內容，並傳回空白的 data 向量。

這個方法需要 Rights.READ_BYTES 權限。

如果 count 大於 MAX_TRANSFER_SIZE，則傳回 ZX_ERR_OUT_OF_RANGE。

要求

名稱類型
count uint64

回應

名稱類型
payload Readable_Read_Result

定義於 fuchsia.io/symlink.fidl

包含符號連結的 ['Node']。

新增：18

複製

新增：26

要求

名稱類型
request server_end:fuchsia.unknown/Cloneable

關閉

終止連線。

呼叫 Close 後，用戶端不得傳送任何其他要求。

伺服器傳送狀態回應後，無論狀態為何，都應關閉連線，且不傳送 epitaph。

關閉管道的用戶端，在語意上應等同於呼叫 Close，而不知道關閉作業何時完成或其狀態。

要求

<EMPTY>

回應

名稱類型
payload fuchsia.unknown/Closeable_Close_Result

DeprecatedClone

已淘汰 - 請改用 fuchsia.unknown/Cloneable.Clone。

已移除：29 已淘汰：27 已新增：26

要求

名稱類型
flags OpenFlags
object server_end:Node

DeprecatedGetAttr

已淘汰 - 請改用 Node.GetAttributes。

這個方法需要 Rights.GET_ATTRIBUTES 權限。

已淘汰：HEAD 新增：28

要求

<EMPTY>

回應

名稱類型
s zx/Result
attributes NodeAttributes

DeprecatedGetFlags

[已淘汰 - 請改用新的 GetFlags 方法。]

已淘汰：HEAD 已新增：27

要求

<EMPTY>

回應

名稱類型
s zx/Result
flags OpenFlags

DeprecatedSetAttr

已淘汰 - 請改用 Node.UpdateAttributes。

已淘汰：HEAD 新增：28

要求

名稱類型
flags NodeAttributeFlags
attributes NodeAttributes

回應

名稱類型
s zx/Result

DeprecatedSetFlags

[已淘汰 - 請改用新的 SetFlags 方法。]

已淘汰：HEAD 已新增：27

要求

名稱類型
flags OpenFlags

回應

名稱類型
s zx/Result

描述

要求

<EMPTY>

回應

名稱類型
payload Symlink_Describe_Result

GetAttributes

取得節點相關資訊。

節點的屬性應保持穩定，不受用於存取節點的特定通訊協定影響。

如果特定屬性不適用或不支援，檔案系統應將對應欄位留空。

  • query：指定要擷取哪些屬性的位元遮罩。伺服器不應傳回超過必要數量的資料。
  • attributes傳回的屬性。

這個方法需要 Rights.GET_ATTRIBUTES 權限。

要求

名稱類型
query NodeAttributesQuery

回應

名稱類型
payload Node_GetAttributes_Result

GetExtendedAttribute

取得與這個節點指定屬性 name 相關聯的值。

屬性名稱長度上限為 MAX_ATTRIBUTE_NAME。不需遵循特定結構。

這個方法需要 Rights.READ_BYTES 權限。

新增：18

要求

名稱類型
name ExtendedAttributeName

回應

名稱類型
payload Node_GetExtendedAttribute_Result

GetFlags

在開啟/建立節點後，查詢適用於該節點的旗標。這個方法不需要任何權限。

請注意，適用於連線的最終旗標組合，可能與建立連線時使用的 fuchsia.io/Directory.Open 要求所指定的旗標不同：

  • Flags.PERM_INHERIT_*：僅在判斷連線權限時適用。
  • Flags.PROTOCOL_*：只會顯示連線的通訊協定。
  • Flags.FLAG_*：僅在開啟資源時適用，不屬於連線的一部分。
新增：27

要求

<EMPTY>

回應

名稱類型
payload Node_GetFlags_Result

GetToken

取得權杖，以便日後識別這項連線。只要要求權杖的連線保持開啟，權杖就會持續有效。

這個方法不需要任何權限。請注意，權杖會識別連線，因此會攜帶此連線的權限資訊。

新增：NEXT

要求

<EMPTY>

回應

名稱類型
payload Node_GetToken_Result

LinkInto

在 dst_parent_token 代表的目錄中，建立這個物件的連結，名稱為 dst。

dst 必須是已解析的物件名稱。如果字串中包含「/」，則會傳回 ZX_ERR_INVALID_ARGS。

這個方法需要檔案系統支援此物件的最大權限集。如果是檔案，通常會是 Rights.READ_BYTES、Rights.WRITE_BYTES、Rights.GET_ATTRIBUTES 和 Rights.UPDATE_ATTRIBUTES。部分檔案系統也可能支援 Rights.EXECUTE 權限。權限不足會導致 ZX_ERR_ACCESS_DENIED。

如果這個物件沒有連結，且「不是」未命名的暫存物件 (使用 Flags.FLAG_CREATE_AS_UNNAMED_TEMPORARY 開啟的物件)，則會失敗並傳回 ZX_ERR_NOT_FOUND。

如果是未命名的臨時物件，請使用 LinkInto 命名。成功完成後，物件會永久連結至檔案系統。要求未命名的暫存物件可連結，否則會失敗並顯示 ZX_ERR_NOT_FOUND。

這個方法不具備與 Directory::Link 方法相同的原子性屬性，也就是說，先呼叫 Open 再呼叫 LinkInto 不等於 Directory::Link，因為 LinkInto 不會防止來源重新命名或取消連結。

要求

名稱類型
dst_parent_token Token
dst Name

回應

名稱類型
payload Linkable_LinkInto_Result

ListExtendedAttributes

為與這個節點相關聯的所有擴充屬性名稱建立疊代器。如果發生錯誤，系統會將錯誤做為疊代器要求管道上的墓誌銘傳回，然後關閉管道。

GetExtendedAttributes 可與上述任一名稱搭配使用，以擷取相關聯的值。

這個方法需要 Rights.READ_BYTES 權限。

新增：18

要求

名稱類型
iterator server_end:ExtendedAttributeIterator

OnOpen

如果 OpenFlags.DESCRIBE 要求，FIDL 伺服器會積極產生事件。

指出開啟作業成功或失敗，並視需要描述物件。如果狀態為 ZX_OK，info 會包含物件的描述性資訊 (與 Describe 傳回的資訊相同)。

已移除：32

回應

名稱類型
s zx/Result
info NodeInfoDeprecated?

OnRepresentation

如果 Flags.FLAG_SEND_REPRESENTATION 要求，伺服器會主動產生事件。這個事件會做為伺服器的第一則訊息傳送，且只會傳送一次。

有效變體對應至目標節點的協商通訊協定 (即這個管道目前使用的通訊協定)。此外，事件也會傳回輔助控制代碼和要求的屬性。

回應

名稱類型
payload Representation

開啟

開啟 (或建立) 相對於這個目錄的節點。如有任何錯誤，系統會透過 object 管道傳送墓誌銘來通知。

錯誤：

  • 如果 path 無效，則為 ZX_ERR_BAD_PATH
  • 請參閱「標記」一節，瞭解可能根據 flags 傳達的其他錯誤

要求

名稱類型
path Path
flags Flags
options Options
object handle<channel>

查詢

要求

<EMPTY>

回應

名稱類型
protocol vector<uint8>

QueryFilesystem

查詢檔案系統，取得檔案系統和/或磁碟區的詳細資料。如果目前的磁碟區有不同的設定，或儲存空間與檔案系統的其他部分分開計算，系統可能會回報該磁碟區的詳細資料，而非整個檔案系統的詳細資料。

要求

<EMPTY>

回應

名稱類型
s zx/Result
info FilesystemInfo?

RemoveExtendedAttribute

移除指定的擴充屬性。

如果屬性不存在，則會傳回 ZX_ERR_NOT_FOUND。

這個方法需要 Rights.WRITE_BYTES 權限。

新增：18

要求

名稱類型
name ExtendedAttributeName

回應

名稱類型
payload Node_RemoveExtendedAttribute_Result

SetExtendedAttribute

將這個節點的指定屬性 name 值設為 value。

如果屬性名稱已存在，系統會更新該屬性。如果屬性不存在，系統會建立屬性。名稱不得包含空值位元組。如果發生這種情況，系統會傳回 ZX_ERR_INVALID_ARGS。

這個方法需要 Rights.WRITE_BYTES 權限。

新增：18

要求

名稱類型
name ExtendedAttributeName
value ExtendedAttributeValue
mode SetExtendedAttributeMode

回應

名稱類型
payload Node_SetExtendedAttribute_Result

SetFlags

設定開啟後要套用至這個節點的旗標。這個方法不需要任何權限。

目前僅支援 Flags.FILE_APPEND。呼叫這個方法時，如果不使用任何旗標，就會清除附加模式。

錯誤：

  • ZX_ERR_NOT_SUPPORTED：物件不支援這項功能或指定標記。
  • ZX_ERR_INVALID_ARGS：指定了 Flags.FILE_APPEND 以外的 flags。
新增：27

要求

名稱類型
flags Flags

回應

名稱類型
payload Node_SetFlags_Result

同步

將節點的更新同步至基礎媒體 (如有)。

當檔案系統伺服器將相關更新排清至基礎媒體時，這個方法會傳回，但不保證基礎媒體已保留資訊，也不保證任何資訊已提交至硬體。用戶端可以使用 Sync，確保作業之間的順序。

這個方法不需要任何權限。

要求

<EMPTY>

回應

名稱類型
payload Node_Sync_Result

UpdateAttributes

更新節點資訊。

  • attributes attributes 中有表格欄位，表示要更新對應的屬性。

如果節點不支援任何指定屬性，則傳回 ZX_ERR_NOT_SUPPORTED。

這個方法需要 Rights.UPDATE_ATTRIBUTES 權限。

要求

名稱類型
payload MutableNodeAttributes

回應

名稱類型
payload Node_UpdateAttributes_Result

可寫入

定義於 fuchsia.io/file.fidl

寫入

在搜尋偏移量寫入資料。搜尋偏移量會根據寫入的位元組數向前移動。如果檔案處於附加模式，系統會先將搜尋偏移量設為檔案結尾，然後在一個原子步驟中寫入。

如果搜尋偏移量加上 data.length 超過目前的檔案結尾，檔案大小可能會增加。

  • 要求 data 位元組緩衝區寫入檔案。
  • 回應 actual_count 寫入的位元組數。

不變量

  • 傳回的 actual_count 絕不會大於 data.length。
  • 如果伺服器因空間不足等原因而無法寫入所有資料，actual_count 可能會小於 data.length。如果無法寫入任何位元組，系統會傳回錯誤。
  • 如果 data.length 為零，伺服器應執行所有檢查，確保寫入權限不會變更檔案，並傳回成功寫入零個位元組。如果處於附加模式，系統仍會更新跳轉偏移量。

這個方法需要 Rights.WRITE_BYTES 權限。

要求

名稱類型
data Transfer

回應

名稱類型
payload Writable_Write_Result

STRUCTS

AdvisoryLockRange

定義於 fuchsia.io/locking.fidl

欄位類型說明預設
origin SeekOrigin

檔案中用於計算偏移量的位置。

 無預設值
offset int64

位元組範圍的開頭，以相對於起點的偏移量表示。如果 origin 為 SeekOrigin.START，則不得為負值。

 無預設值
length int64

位元組範圍的長度 (以位元組為單位)。

如果長度為零，則位元組範圍會延伸至檔案結尾，無論檔案大小為何。

如果長度為負數，位元組範圍會包含 offset + length 到 offset - 1 (含) 的位元組，前提是這個範圍不會超出檔案開頭。

 無預設值

AdvisoryLocking_AdvisoryLock_Response

定義於 fuchsia.io/locking.fidl

<EMPTY>

DirectoryObject

定義於 fuchsia.io/node.fidl

<EMPTY>

定義於 fuchsia.io/directory.fidl

<EMPTY>

Directory_Rename_Response

定義於 fuchsia.io/directory.fidl

<EMPTY>

定義於 fuchsia.io/directory.fidl

<EMPTY>

EmptyStruct

定義於 fuchsia.io/node.fidl

用於需要空結構體的地方 (例如空聯集成員)，避免建立新的結構體類型。

新增：HEAD

<EMPTY>

ExtendedAttributeIterator_GetNext_Response

定義於 fuchsia.io/node.fidl

欄位類型說明預設
attributes vector<ExtendedAttributeName>:128 無預設值
last bool 無預設值

FileObject 資源

定義於 fuchsia.io/node.fidl

欄位類型說明預設
event handle<event>?

選用事件，用於傳輸物件的可讀性或可寫性資訊。這個事件會轉送基礎物件的相關資訊，而非授予用戶端的能力：在不具備讀取能力的連線上，這個事件可能會發出「可讀取」信號。

這個事件可能會觀察到「FILE_SIGNAL_」值。

 無預設值
stream handle<stream>?

預留位置，用於日後支援串流。

目前，伺服器不得在這個欄位中傳送控制代碼。

 無預設值

File_Allocate_Response

定義於 fuchsia.io/file.fidl

<EMPTY>

File_EnableVerity_Response

定義於 fuchsia.io/file.fidl

<EMPTY>

File_GetBackingMemory_Response 資源

定義於 fuchsia.io/file.fidl

欄位類型說明預設
vmo handle<vmo> 無預設值

File_ReadAt_Response

定義於 fuchsia.io/file.fidl

欄位類型說明預設
data Transfer 無預設值

File_Resize_Response

定義於 fuchsia.io/file.fidl

<EMPTY>

File_Seek_Response

定義於 fuchsia.io/file.fidl

欄位類型說明預設
offset_from_start uint64 無預設值

File_WriteAt_Response

定義於 fuchsia.io/file.fidl

欄位類型說明預設
actual_count uint64 無預設值

FilesystemInfo

定義於 fuchsia.io/node.fidl

欄位類型說明預設
total_bytes uint64

可儲存在檔案系統中的資料位元組數。這不包括中繼資料或其他檔案系統負擔，例如區塊捨入。

 無預設值
used_bytes uint64

檔案系統使用的資料位元組數。這不包括中繼資料或其他檔案系統負擔，例如區塊捨入。

 無預設值
total_nodes uint64

可儲存在檔案系統中的節點數量。

 無預設值
used_nodes uint64

檔案系統使用的節點數量。

 無預設值
free_shared_pool_bytes uint64

可從基礎磁碟區管理員分配的額外空間量。如果系統不支援，或檔案系統沒有擴充空間，則會是零。

 無預設值
fs_id uint64

這個檔案系統執行個體的專屬 ID。重新啟動後不會保留。

實作者應建立核心物件 (通常是事件)，並使用其 koid 做為檔案系統 ID。這個 koid 可確保系統中的唯一性。

 無預設值
block_size uint32

單一檔案系統區塊的大小 (以位元組為單位)。

 無預設值
max_filename_size uint32

檔案系統名稱的長度上限。

 無預設值
fs_type uint32

基礎檔案系統類型的專屬 ID。

 無預設值
padding uint32 無預設值
name array<int8, 32> 無預設值

FscryptPolicy

定義於 fuchsia.io/node.fidl

與加密目錄或檔案相關聯的 Fscrypt 加密政策。

新增：HEAD

欄位類型說明預設
key_identifier array<uint8, 16>

16 位元組的主要金鑰 ID (對應至 fscrypt_policy_v2.master_key_identifier)。

 無預設值
flags FscryptPolicyFlags

政策旗標 (對應至 fscrypt_policy_v2.flags)。

 無預設值

Linkable_LinkInto_Response

定義於 fuchsia.io/node.fidl

<EMPTY>

NodeAttributes

定義於 fuchsia.io/node.fidl

NodeAttributes 定義檔案系統節點的一般資訊。

欄位類型說明預設
mode uint32

「mode」中說明的保護位元和節點類型資訊。

 無預設值
id uint64

檔案系統專屬 ID。

 無預設值
content_size uint64

節點大小，以位元組為單位。

 無預設值
storage_size uint64

儲存節點所需的空間 (可能大於大小)，以位元組為單位。

 無預設值
creation_time uint64

建立時間 (建立後可手動更新)，以世界標準時間 Unix 紀元起算的奈秒為單位。

 無預設值
modification_time uint64

上次修改時間 (自 Unix 紀元起算，以世界標準時間的奈秒為單位)。

 無預設值

NodeAttributes2

定義於 fuchsia.io/node.fidl

欄位類型說明預設
mutable_attributes MutableNodeAttributes 無預設值
immutable_attributes ImmutableNodeAttributes 無預設值

Node_GetFlags_Response

定義於 fuchsia.io/node.fidl

欄位類型說明預設
flags Flags 無預設值

Node_GetToken_Response resource

定義於 fuchsia.io/node.fidl

欄位類型說明預設
token Token 無預設值

Node_RemoveExtendedAttribute_Response

定義於 fuchsia.io/node.fidl

<EMPTY>

Node_SetExtendedAttribute_Response

定義於 fuchsia.io/node.fidl

<EMPTY>

Node_SetFlags_Response

定義於 fuchsia.io/node.fidl

<EMPTY>

Node_Sync_Response

定義於 fuchsia.io/node.fidl

<EMPTY>

Node_UpdateAttributes_Response

定義於 fuchsia.io/node.fidl

<EMPTY>

Readable_Read_Response

定義於 fuchsia.io/file.fidl

欄位類型說明預設
data Transfer 無預設值

服務

定義於 fuchsia.io/node.fidl

<EMPTY>

SymlinkObject

定義於 fuchsia.io/node.fidl

欄位類型說明預設
target SymlinkTarget 無預設值

Writable_Write_Response

定義於 fuchsia.io/file.fidl

欄位類型說明預設
actual_count uint64 無預設值

列舉

AdvisoryLockType strict

類型：uint32

定義於 fuchsia.io/locking.fidl

名稱值說明
1

零或多個連線可以同時保留檔案的讀取鎖定。
2

最多只能有一個連線同時持有檔案的寫入鎖定。如果檔案設有寫入鎖定，就無法設定其他類型的鎖定。
3

指定要解鎖的區域。

DirentType 彈性

類型：uint8

定義於 fuchsia.io/directory.fidl

名稱值說明
0

類型不明的 dirent。
4

代表目錄物件的 dirent。
6

代表區塊裝置物件的 dirent。
8

代表檔案物件的 dirent。
16

代表服務物件的 dirent。

HashAlgorithm 彈性

類型：uint8

定義於 fuchsia.io/file.fidl

表示用於為啟用 fsverity 的檔案建構 Merkle 樹狀結構的雜湊演算法。

新增：HEAD

名稱值說明
1
2

SeekOrigin strict

類型：uint32

定義於 fuchsia.io/file.fidl

更新跳轉偏移量的參考點。請參閱 File.Seek。

這個列舉與 zx_stream_seek_origin_t 列舉相符。

名稱值說明
0

從檔案開頭開始跳轉。跳轉偏移量會設為 offset 個位元組。在這種情況下，跳轉偏移量不得為負值。
1

從檔案中的目前位置跳轉。跳轉偏移量會是目前的跳轉偏移量加上 offset 個位元組。
2

從檔案結尾開始搜尋。搜尋偏移量會是檔案大小加上 offset 個位元組。

SetExtendedAttributeMode strict

類型：uint32

定義於 fuchsia.io/node.fidl

名稱值說明
1

無論擴充屬性是否存在，都設定其值。
2

建立新的擴充屬性。如果已存在，則失敗。
3

取代現有擴充屬性的值。如果不存在，則失敗。

WatchEvent strict

類型：uint8

定義於 fuchsia.io/directory.fidl

名稱值說明
0

表示監控的目錄已刪除。這個事件傳回的名稱會是 . (點)，因為它參照的是目錄本身。
1

表示已在目錄中建立節點 (無論是新建立或移動)。
2

識別已從目錄中移除 (刪除或移動) 的節點。
3

識別監控開始時，目錄中已存在的節點。
4

表示不會再傳送 EXISTING 事件。這個事件傳回的名稱會是空白，因為並未參照特定項目。

TABLES

AdvisoryLockRequest

定義於 fuchsia.io/locking.fidl

序數欄位類型說明
type AdvisoryLockType

要取得的鎖定類型。

如果缺少這個欄位，AdvisoryLock 方法會失敗，並傳回 ZX_ERR_INVALID_ARGS。
range AdvisoryLockRange

檔案中要鎖定的位元組範圍。

範圍可以延伸到檔案結尾之後，但不能延伸到檔案開頭之前。

如果沒有這個欄位，範圍預設為整個檔案。
wait bool

檔案是否應等待 AdvisoryLock 方法的回覆，直到可取得要求的鎖定。

如果沒有這個欄位，檔案就不會等待。

ConnectionInfo 資源

定義於 fuchsia.io/node.fidl

序數欄位類型說明
rights Rights

目前連線擁有的權限。注意：rights 會限制連線允許的一組作業，但不保證這些作業可用。舉例來說，某個檔案連線可能具有 Rights.EXECUTE 權限，但檔案本身不具備 EXECUTE 功能，因此無法執行。請參閱 ConnectionOptions.rights。

DirectoryInfo

定義於 fuchsia.io/directory.fidl

序數欄位類型說明
attributes NodeAttributes2

目錄的要求屬性。只有在提出要求時，系統才會填入這項資訊。

新增：18

FileInfo 資源

定義於 fuchsia.io/file.fidl

節點檔案表示法的輔助資料。

序數欄位類型說明
is_append bool

如果檔案是以附加模式開啟，則為 True。在附加模式中，搜尋偏移量會在每次寫入前移至結尾，這兩個步驟會以不可分割的方式執行。
observer handle<event>

選用事件，用於傳輸物件可讀性或可寫性的相關資訊。這個事件會轉送基礎物件的相關資訊，而非授予用戶端的能力：這個事件可能會在不具備讀取能力的連線上，發出「可讀取」信號。

如果符合下列條件，就會顯示這個事件：

  • 檔案連線上的 available_operations 不是空白。
  • 檔案系統支援發出可讀取/可寫入事件的信號。

這個事件可能會顯示 FileSignal 值。
stream handle<stream>

選用的串流物件，可用於讀取和寫入檔案，速度比 fidl 更快。

使用串流時，檔案的管道「必須」保持開啟。如果使用的串流物件已超過來源管道的生命週期，可能會導致失敗或非預期的結果。
attributes NodeAttributes2

檔案的要求屬性。只有在要求時才會填入這項資訊。

新增：18

ImmutableNodeAttributes

定義於 fuchsia.io/node.fidl

序數欄位類型說明
protocols NodeProtocolKinds

說明節點支援的表示法類型。注意：這不是連線時間協商的結果，協商結果會透過 representation 傳達。
abilities Abilities

說明節點支援的作業類型。注意：這與連線時使用的權限不同。
content_size uint64

節點大小，以位元組為單位。
storage_size uint64

儲存節點所需的空間 (可能大於大小)，以位元組為單位。
id Id

節點的 ID。請參閱 Id。這個 id 在目錄的所有項目中應為不重複。
change_time uint64

上次變更中繼資料的時間，以 Unix 紀元 (世界標準時間) 起算的奈秒數表示。

新增：18
options VerificationOptions

包含已啟用 Verity 檔案的驗證選項。

新增：HEAD
root_hash vector<uint8>:64

檔案的根雜湊。並非所有檔案系統都支援這項功能。

新增：HEAD
verity_enabled bool

如果這個檔案已啟用 Verity，則為 True。

新增：HEAD

MutableNodeAttributes

定義於 fuchsia.io/node.fidl

序數欄位類型說明
creation_time uint64

建立時間，以 Unix 紀元 (世界標準時間) 起算的奈秒數表示。
modification_time uint64

上次修改時間，以世界標準時間 Unix 紀元起算的奈秒數表示。
mode uint32

POSIX 相容性屬性。大多數檔案系統都不支援這些功能。如果需要，則必須單純儲存及擷取這些屬性 (例如做為擴充屬性)，不得嘗試解讀 (例如執行權限檢查或特別處理裝置開啟作業)。

新增：18
uid uint32
新增：18
gid uint32
新增：18
rdev uint64
新增：18
access_time uint64

上次存取時間，以世界標準時間 Unix 紀元起算的奈秒數表示。請注意，如果只有這個屬性更新，伺服器不一定會更新這個值。

新增：18
casefold bool

支援 Casefold (不區分大小寫的檔案名稱) 這項屬性只能在空白目錄中變更，且會由後續建立的任何子目錄繼承。 撰寫本文時，只有 Fxfs 檔案系統支援這項功能。

新增：HEAD
selinux_context SelinuxContext

在 SELinux 實作環境中使用的擴充屬性「security.selinux」值。只有在值不超過 MAX_SELINUX_CONTEXT_ATTRIBUTE_LEN 個字元時，才能設定或傳回值，以限制回應的大小。如果目前在節點上找不到該值，回應欄位就不會包含在回應中。如果節點上有值，但伺服器因大小或實作而未在此傳回，則會傳回 use_extended_attributes，表示使用 ['fuchsia.io/Node.GetExtendedAttribute`] 擷取。

如果嘗試使用 use_extended_attributes 成員設定這項屬性，系統會傳回 ZX_ERR_INVALID_ARGS。

新增：HEAD
encryption_policy FscryptPolicy

支援 Fscrypt 加密政策。這項屬性只能在空白目錄中變更，且會由後續建立的任何子目錄繼承。每個目錄只能設定一次這項屬性。政策集會用於加密這個目錄及其子目錄的檔案內容和檔案名稱。撰寫本文時，只有 Fxfs 檔案系統支援這項功能。

新增：HEAD

NodeInfo

定義於 fuchsia.io/node.fidl

描述目標節點的資訊。

新增：27

序數欄位類型說明
attributes NodeAttributes2

選項

定義於 fuchsia.io/directory.fidl

開啟節點時可使用的選項。與旗標不同，這些選項是專為特定用途設計 (例如減少要求屬性時的往返延遲時間)。

序數欄位類型說明
attributes NodeAttributesQuery

要求一組屬性，與 OnRepresentation 回應一併傳送。如果未設定 Flags.FLAG_SEND_REPRESENTATION，則不會產生任何影響。
create_attributes MutableNodeAttributes

建立新物件時，要求以不可分割的方式設定一組屬性。如果未設定 Flags.FLAG_MAYBE_CREATE 和 Flags.FLAG_MUST_CREATE (即建立模式為「Never」)，要求會失敗並顯示 ZX_ERR_INVALID_ARGS。

SymlinkInfo

定義於 fuchsia.io/symlink.fidl

新增：18

序數欄位類型說明
target SymlinkTarget

符號連結在伺服器上沒有任何意義，用戶端可以自由解讀目標。
attributes NodeAttributes2

符號連結的要求屬性。只有在要求時才會填入這項資訊。

UnlinkOptions

定義於 fuchsia.io/directory.fidl

序數欄位類型說明
flags UnlinkFlags

VerificationOptions

定義於 fuchsia.io/file.fidl

用於啟用檔案驗證功能的一組選項。

新增：HEAD

序數欄位類型說明
hash_algorithm HashAlgorithm
salt vector<uint8>:32

系統會在每個區塊雜湊前，在區塊前面加上 salt。

UNIONS

AdvisoryLocking_AdvisoryLock_Result strict

定義於 fuchsia.io/locking.fidl

序數Variant類型說明
response AdvisoryLocking_AdvisoryLock_Response
err zx/Status

定義於 fuchsia.io/directory.fidl

序數Variant類型說明

Directory_Rename_Result strict

定義於 fuchsia.io/directory.fidl

序數Variant類型說明
response Directory_Rename_Response
err zx/Status

定義於 fuchsia.io/directory.fidl

序數Variant類型說明

ExtendedAttributeIterator_GetNext_Result strict

定義於 fuchsia.io/node.fidl

序數Variant類型說明
response ExtendedAttributeIterator_GetNext_Response
err zx/Status

ExtendedAttributeValue 彈性 資源

定義於 fuchsia.io/node.fidl

擴充屬性的值類型。如果值小於 32768 位元組，則會內嵌。大於這個大小的值會寫入 VMO 緩衝區。

新增：18
序數Variant類型說明
bytes vector<uint8>:32768
buffer handle<vmo>

File_Allocate_Result strict

定義於 fuchsia.io/file.fidl

序數Variant類型說明
response File_Allocate_Response
err zx/Status
framework_err internal

File_EnableVerity_Result strict

定義於 fuchsia.io/file.fidl

序數Variant類型說明
response File_EnableVerity_Response
err zx/Status
framework_err internal

File_GetBackingMemory_Result strict resource

定義於 fuchsia.io/file.fidl

序數Variant類型說明
response File_GetBackingMemory_Response
err zx/Status

File_ReadAt_Result strict

定義於 fuchsia.io/file.fidl

序數Variant類型說明
response File_ReadAt_Response
err zx/Status

File_Resize_Result strict

定義於 fuchsia.io/file.fidl

序數Variant類型說明
response File_Resize_Response
err zx/Status

File_Seek_Result strict

定義於 fuchsia.io/file.fidl

序數Variant類型說明
response File_Seek_Response
err zx/Status

File_WriteAt_Result strict

定義於 fuchsia.io/file.fidl

序數Variant類型說明
response File_WriteAt_Response
err zx/Status

Linkable_LinkInto_Result strict

定義於 fuchsia.io/node.fidl

序數Variant類型說明
response Linkable_LinkInto_Response
err zx/Status

嚴格 資源 NodeInfoDeprecated

定義於 fuchsia.io/node.fidl

序數Variant類型說明
service Service

連線未提供通訊協定資訊。
file FileObject

連線會組成檔案。
directory DirectoryObject

連線會組成目錄。

Node_GetAttributes_Result strict

定義於 fuchsia.io/node.fidl

序數Variant類型說明
response NodeAttributes2
err zx/Status

Node_GetExtendedAttribute_Result strict resource

定義於 fuchsia.io/node.fidl

序數Variant類型說明
response ExtendedAttributeValue
err zx/Status

Node_GetFlags_Result strict

定義於 fuchsia.io/node.fidl

序數Variant類型說明
response Node_GetFlags_Response
err zx/Status
framework_err internal

Node_GetToken_Result strict resource

定義於 fuchsia.io/node.fidl

序數Variant類型說明
response Node_GetToken_Response
err zx/Status
framework_err internal

Node_RemoveExtendedAttribute_Result strict

定義於 fuchsia.io/node.fidl

序數Variant類型說明
response Node_RemoveExtendedAttribute_Response
err zx/Status

Node_SetExtendedAttribute_Result strict

定義於 fuchsia.io/node.fidl

序數Variant類型說明
response Node_SetExtendedAttribute_Response
err zx/Status

Node_SetFlags_Result strict

定義於 fuchsia.io/node.fidl

序數Variant類型說明
response Node_SetFlags_Response
err zx/Status
framework_err internal

Node_Sync_Result strict

定義於 fuchsia.io/node.fidl

序數Variant類型說明
response Node_Sync_Response
err zx/Status

Node_UpdateAttributes_Result strict

定義於 fuchsia.io/node.fidl

序數Variant類型說明
response Node_UpdateAttributes_Response
err zx/Status

Readable_Read_Result strict

定義於 fuchsia.io/file.fidl

序數Variant類型說明
response Readable_Read_Response
err zx/Status

表示法彈性 資源

定義於 fuchsia.io/node.fidl

序數Variant類型說明
node NodeInfo

這個連線已協商 Node 通訊協定。

新增：27
directory DirectoryInfo

這個連線已協商 File 通訊協定。
file FileInfo

這個連線已協商 File 通訊協定。

SelinuxContext 彈性

定義於 fuchsia.io/node.fidl

序數Variant類型說明
data vector<uint8>:256
use_extended_attributes EmptyStruct

定義於 fuchsia.io/symlink.fidl

序數Variant類型說明

Writable_Write_Result strict

定義於 fuchsia.io/file.fidl

序數Variant類型說明
response Writable_Write_Response
err zx/Status

BITS

AllocateMode flexible

類型：uint32

定義於 fuchsia.io/file.fidl

名稱值說明
1
2
4
8
16
32

FileSignal strict

類型：uint32

定義於 fuchsia.io/file.fidl

名稱值說明
16777216

表示檔案已可供讀取。
33554432

表示檔案已可寫入。

標記彈性

類型：uint64

定義於 fuchsia.io/directory.fidl

用於指定節點開啟方式的旗標。請注意，某些位元範圍會保留給特定用途：

名稱值說明
1

允許使用 PROTOCOL_SERVICE 開啟子節點。
2

讀取檔案的位元組內容。
4

將位元組內容寫入檔案。
8

執行檔案的位元組內容。
16

取得/查詢節點屬性。
32

設定/更新節點屬性。
64

列舉 (列出) 目錄項目。
128

允許使用節點通訊協定開啟子節點。必須與 PERM_ENUMERATE 一併指定，否則要求會失敗，並傳回 ZX_ERR_INVALID_ARGS。
256

修改目錄項目 (建立/重新命名/連結/取消連結)。必須與 PERM_ENUMERATE 一併指定，否則要求會失敗並傳回 ZX_ERR_INVALID_ARGS。
8192

盡可能沿用寫入權限 (PERM_WRITE_BYTES、PERM_UPDATE_ATTRIBUTES、PERM_MODIFY_DIRECTORY、/// PERM_ENUMERATE)。如果父項連線缺少上述任何權限，伺服器必須確保移除這個標記。如要瞭解會沿用的確切權限組合，請參閱 INHERITED_WRITE_PERMISSIONS。
16384

在可用時沿用執行權限 (PERM_EXECUTE)。如果父項連線缺少 PERM_EXECUTE，伺服器必須確保移除這個標記。
4294967296

如果這是服務節點，請連線至基礎通訊協定。呼叫端必須判斷要使用的正確通訊協定 (例如根據路徑)。除非與 PROTOCOL_NODE 搭配使用，否則在要求中指定其他旗標會失敗，並傳回 ZX_ERR_INVALID_ARGS。
4194304

連線至基礎節點。優先順序高於其他通訊協定。如果指定其他 PROTOCOL_*，系統會使用這些值來驗證目標節點類型。如果指定 PROTOCOL_* 和 FLAG_SEND_REPRESENTATION 以外的旗標，要求會失敗並傳回 ZX_ERR_INVALID_ARGS。等同於 POSIX O_PATH。
524288

呼叫端接受 fuchsia.io/Directory 通訊協定。等同於 POSIX O_DIRECTORY。
8589934592

呼叫端接受 fuchsia.io/File 通訊協定。
1099511627776

呼叫端要求在成功時傳送 fuchsia.io/Node.OnRepresentation 事件。
65536

如果物件不存在，則建立新物件，否則開啟現有物件。如果設定，則必須設定單一 PROTOCOL_* 旗標，指出要建立的物件類型。相當於 POSIX O_CREAT。
131072

如果物件不存在，則建立新物件，否則要求失敗並傳回 ZX_ERR_ALREADY_EXISTS。如果設定，則必須設定單一 PROTOCOL_\* 旗標，指出要建立的物件類型。優先順序高於 FLAG_MAYBE_CREATE。等同於 POSIX O_EXCL。
34359738368

建立新的未命名暫時物件。在連結至檔案系統之前，物件都是暫時性的。如果使用 FLAG_TEMPORARY_AS_NOT_LINKABLE 指定，則建立的物件無法連結。如果設定這個旗標：

  • fuchsia.io/Directory.Open 中指定的 path 是指新物件建立位置的目錄路徑，
  • PROTOCOL_* 旗標會設為指出要建立的物件類型。目前只有在指定 PROTOCOL_FILE 時才支援這項功能，在這種情況下，這項功能等同於 Linux O_TMPFILE。
  • 系統會忽略 FLAG_MAYBE_CREATE。
新增：HEAD
1048576

以附加模式開啟檔案。在所有寫入作業之前，搜尋指標會移至檔案結尾 (EOF)。等同於 POSIX O_APPEND。
262144

開啟檔案時，將檔案截斷為零長度。等同於 POSIX O_TRUNC。

FscryptPolicyFlags flexible

類型：uint8

定義於 fuchsia.io/node.fidl

設定 fscrypt 加密政策的旗標。

這些旗標與 Linux fscrypt UAPI 的位元組相容：每個成員的值都與 <linux/fscrypt.h> 中對應的 FSCRYPT_POLICY_FLAG* 常數相同，因此 Linux fscrypt_policy_v2 的 flags 欄位可以與這個類型相互轉換，不需經過轉譯。

新增：HEAD

名稱值說明
1

將加密檔案名稱填補至 8 位元組邊界 (如果未設定 PAD_8 和 PAD_16，檔案名稱會填補至 4 位元組邊界；如果同時設定 PAD_8 和 PAD_16，檔案名稱會填補至 32 位元組邊界)。
2

將加密檔案名稱填補至 16 位元組邊界。
4

使用直接金鑰模式。
8

對 inode 編號進行雜湊處理，並與 64 位元邏輯區塊編號 (FSCRYPT_POLICY_FLAG_IV_INO_LBLK_64) 結合，藉此衍生 IV/DUN。
16

對主金鑰和 inode 編號進行雜湊處理，並加上 32 位元邏輯區塊編號 (FSCRYPT_POLICY_FLAG_IV_INO_LBLK_32)，藉此衍生 IV/DUN。

ModeType strict

類型：uint32

定義於 fuchsia.io/directory.fidl

名稱值說明
2147483648

NodeAttributeFlags strict

類型：uint32

定義於 fuchsia.io/node.fidl

「flags」引數會指出用於更新節點的「attributes」欄位。

名稱值說明
1
2

NodeAttributesQuery 彈性

類型：uint64

定義於 fuchsia.io/node.fidl

名稱值說明
1

要求 NodeAttributes.protocols。
2

要求 NodeAttributes.abilities。
4

要求 NodeAttributes.content_size。
8

要求 NodeAttributes.storage_size。
32

要求 NodeAttributes.id。
64

要求 NodeAttributes.creation_time。
128

要求 NodeAttributes.modification_time。
256

Posix 屬性。

新增：18
512
新增：18
1024
新增：18
2048
新增：18
4096
新增：18
8192
新增：18
16384

Verity 屬性。

新增：HEAD
32768
新增：HEAD
65536
新增：HEAD
131072

支援 Casefold (不區分大小寫的檔案名稱)。如果設為 true，檔案查詢將不區分大小寫，但會保留大小寫。也就是說，「Foo」會逐字儲存，但可以開啟為「foo」、「fOO」等。大小寫摺疊是根據 Unicode 12 NFD 正規化和大小寫摺疊標準完成。

新增：HEAD
262144

要求 MutableNodeAttributes.selinux_context。詳情請參閱該欄位。

新增：HEAD
524288

要求 MutableNodeAttributes.encryption_policy。

新增：HEAD
1048576

在 fuchsia.io/Node.GetAttributes 中查詢時，如果符合下列任一條件，系統會向檔案系統指出這個節點已存取，且正在等待存取時間更新：

  • current_access_time <= current_modification_time
  • current_access_time <= current_change_time
  • current_access_time < current_time - duration(1 day)

如果符合上述任一條件，系統會先將 access_time 更新為目前時間，再傳回任何查詢的節點屬性。

這與 Linux relatime 掛接相容。

新增 NodeAttributesQuery 的原因在於，某些檔案系統 (例如 Fxfs) 無法識別檔案存取發生的時間，因此無法更新存取時間。我們允許用戶端與基礎檔案系統通訊，告知檔案存取作業已發生，且正在等待存取時間更新。

警告：如果在未事先存取檔案的情況下查詢，只要符合上述條件，節點的存取時間就會更新。並非所有檔案系統都支援這項功能。如果檔案系統不支援，系統會忽略查詢。

新增：HEAD

NodeProtocolKinds 彈性

類型：uint64

定義於 fuchsia.io/node-protocols.fidl

開啟節點時，節點可能有多個支援的表示法，即使節點可能具有固定的基礎身分。

目前，檔案是透過 File 通訊協定存取，並在使用 GET_REPRESENTATION 開啟時傳送 Representation.FileInfo。不過，我們日後可能會推出更複雜的 FileV2 通訊協定，或由專門核心物件支援、更有效率的 SuperFastFile。新用戶端可以指定 NodeProtocolKinds 中的對應位元，要求更進階的表示法，而現有用戶端則會繼續透過舊表示法與節點通訊。

NodeProtocolKinds 透過通訊協定協商的形式，實現向前相容性。

這些元素與 Representation 的成員有一對一的對應關係。

名稱值說明
1

節點的連接器表示法。

連線會使用 Node 或目標通訊協定，具體取決於開啟時使用的旗標。
2

節點的目錄表示法。

連線會使用目錄通訊協定。
4

節點的檔案表示法。

連線會使用檔案通訊協定。

OpenFlags strict

類型：uint32

定義於 fuchsia.io/directory.fidl

已淘汰 - 請改用標記。

名稱值說明
1

可讀取目標物件。
2

可寫入目標物件。
8

連線可對應目標物件執行檔。
65536

如果物件不存在，請建立物件。
131072

(使用 Create) 如果物件已存在，則失敗。
262144

請先截斷物件再使用。
524288

Assert that the object to be opened is a directory. 如果目標物件不是目錄，則傳回錯誤。
1048576

在所有寫入作業前，跳轉至物件結尾。
4194304

開啟物件的參照，而非物件本身。只有下列旗標可以與 NODE_REFERENCE 一起傳遞：

  • DIRECTORY
  • NOT_DIRECTORY
  • DESCRIBE 否則會傳回錯誤。 如果使用這個方法開啟或複製物件，產生的連線不會帶有任何權限旗標。建立連線後，只能執行一組有限的操作：GetAttr、Clone、Close、Describe 和 GetFlags。連線會使用 Node 通訊協定。呼叫 SetAttr 或 SetFlags 會導致 ZX_ERR_BAD_HANDLE。
8388608

要求將「OnOpen」事件傳送至介面要求。

如果成功開啟/複製，事件會包含非空值的 NodeInfoDeprecated。這可用於開啟不包含 fuchsia.io/Node 的通訊協定；系統會傳送事件，就像通訊協定是 fuchsia.io/Node 一樣，然後只使用目標通訊協定。
134217728

指定這個旗標，即可要求 POSIX 相容性，以便處理寫入權限。目前，這項政策會影響 Open 期間的權限處理方式：

  • 如果目標路徑是目錄，則只有在目前連線和所有中繼掛接點都可寫入時，新連線的權限才會擴大至包含 WRITABLE。
  • 否則系統會忽略這個旗標。如果要求比目前連線或任何中繼掛接點更多的權限，就會發生存取遭拒錯誤。

如果省略這個旗標，開啟時一律會使用要求的權限，如果要求的權限超過目前連線附加的權限，作業就會失敗，並顯示存取遭拒錯誤。

如果要求連線和要求的權限都是唯讀，伺服器可能會忽略標記，且不會轉送至下游。這是實作詳細資料，必須強制執行跨掛接點的階層權限，且不應影響用戶端的預期行為。
268435456

指定這個旗標，即可要求 POSIX 相容性，以便處理執行權限。目前，這項設定會影響 Open 期間的權限處理方式：

  • 如果目標路徑是目錄，則只有在目前連線和所有中繼掛接點都可執行時，新連線的權限才會擴大至包含 EXECUTABLE。
  • 否則系統會忽略這個旗標。如果要求比目前連線或任何中繼掛接點更多的權限，就會發生存取遭拒錯誤。

如果省略這個旗標，開啟時一律會使用要求的權限，如果要求的權限超過目前連線附加的權限，作業就會失敗，並顯示存取遭拒錯誤。

如果要求連線和要求的權限都是唯讀，伺服器可能會忽略標記，且不會轉送至下游。這是實作詳細資料，必須強制執行跨掛接點的階層權限，且不應影響用戶端的預期行為。
33554432

Assert that the object to be opened is not a directory. 如果目標物件是目錄，則傳回錯誤。
67108864

在複製期間使用時，新連線會繼承來源連線的權限，無論是檔案或目錄都一樣。否則，複製作業會嘗試使用要求的權限。同時傳遞任何 RIGHT_* 旗標和 OpenFlags.CLONE_SAME_RIGHTS 是無效的。
16777216

以區塊裝置的形式開啟目標物件。

作業彈性

類型：uint64

定義於 fuchsia.io/rights-abilities.fidl

權利和能力背後的共同成員定義。部分作業可能僅適用於特定節點類型 (例如 Operations.MODIFY_DIRECTORY 僅適用於目錄)。

名稱值說明
1

連線至目錄中的服務。
2

讀取節點或其子項的位元組內容。
4

寫入節點或其子項的位元組內容。
8

執行節點或其子項的位元組內容。
16

讀取節點和/或其子項的屬性。
32

更新節點和/或其子項的屬性。
64

讀取目錄中的節點清單。
128

從目錄開啟節點。

注意：建議搭配 Rights.ENUMERATE 使用 (開啟子項即可探測目錄內容)，例如使用 PERM_READABLE。如果需要嚴格隔離，請考慮改為轉送離散功能。
256

修改目錄中的節點清單，例如建立、重新命名、連結/取消連結等...

注意：建議搭配 Rights.ENUMERATE 使用 (在建立節點時，可透過名稱衝突探測目錄內容)，例如使用 PERM_WRITABLE。如果需要嚴格隔離，請考慮改為轉送離散功能。

UnlinkFlags flexible

類型：uint64

定義於 fuchsia.io/directory.fidl

名稱值說明
1

如果設定，且物件不是目錄，取消連結就會失敗 (並顯示 ZX_ERR_NOT_DIR)。

VmoFlags strict

類型：uint32

定義於 fuchsia.io/file.fidl

名稱值說明
1

要求 VMO 可讀取。
2

要求 VMO 可寫入。
4

要求 VMO 可執行。
65536

需要基礎 VMO 的寫入時複製副本。如果無法複製 VMO，要求應會失敗。可能未隨附SHARED_BUFFER。

私人複製項目至少會使用 ZX_VMO_CHILD_SNAPSHOT_AT_LEAST_ON_WRITE 旗標的保證，zx_vmo_create_child()。這表示傳回的 VMO 將是寫入時複製 (如果要求 WRITE)，但可能會或不會反映基礎檔案的後續內容變更。傳回的 VMO 不會反映檔案的大小變更。這些語意與 POSIX mmap() MAP_PRIVATE 旗標的語意相符。

在某些情況下，如果用戶端需要保證檔案的快照，可以使用 SHARED_BUFFER，然後搭配 ZX_VMO_CHILD_SNAPSHOT 使用 zx_vmo_create_child()。不過，除了實作無法傳回 SHARED_BUFFER 的情況外，如果 VMO 附加至翻頁元素，建立完整快照也會失敗。由於大多數檔案系統都會使用分頁系統，因此只有在用戶端與已知伺服器通訊的特定情況下，才應使用完整快照方法。
131072

要求 VMO 提供直接存取檔案基礎 VMO 內容的權限。如果無法提供這類 VMO，要求應會失敗。可能未隨附PRIVATE_CLONE。

即使要求 WRITE 存取權，傳回的 VMO 也可能無法調整大小。在這種情況下，應使用 File.Resize 調整檔案大小。

WatchMask strict

類型：uint32

定義於 fuchsia.io/directory.fidl

名稱值說明
1

由 Directory.Watch 使用。要求傳輸 WatchEvent.DELETED。
2

由 Directory.Watch 使用。要求傳輸 WatchEvent.ADDED。
4

由 Directory.Watch 使用。要求傳輸 WatchEvent.REMOVED。
8

由 Directory.Watch 使用。要求傳輸 WatchEvent.EXISTING。
16

由 Directory.Watch 使用。要求傳輸 WatchEvent.IDLE。

常數

名稱值類型說明
DIRECTORY_PROTOCOL_NAME fuchsia.io/Directory String
已移除：29
FILE_PROTOCOL_NAME fuchsia.io/File String
已移除：29
FLAG_TEMPORARY_AS_NOT_LINKABLE

指定這個物件無法連結。這項功能僅適用於建立臨時未命名物件的情境。如果不是這種情況，節點通訊協定會定義是否可連結 (即是否構成 Linkable 通訊協定)。如果這個旗標與 Flags.FLAG_CREATE_AS_UNNAMED_TEMPORARY 一起設定，系統會建立未命名的暫存物件，且無法連結至檔案系統。這與 Linux O_TMPFILE | O_EXCL 類似。

注意：如未指定 Flags.FLAG_CREATE_AS_UNNAMED_TEMPORARY，系統會將其視為「必須建立」旗標。

之所以多載 Flags.FLAG_MUST_CREATE，使其在此情境中代表「不可連結」，在其他情境中代表「必須建立」，是因為假設某些 POSIX 旗標與 Flags 中的成員相容。特別是 POSIX O_EXCL 的值與 Flags.FLAG_MUST_CREATE 相同。我們無法定義相同值的不同位元成員，因此會在 Flags 之外單獨定義。

新增：HEAD
INHERITED_WRITE_PERMISSIONS

如果指定 Flags.PERM_INHERIT_WRITE，則會從父項連線繼承一組權限。請注意，如果連線缺少任何一項權限，就不會繼承任何權限。
INO_UNKNOWN 18446744073709551615 uint64

沒有 ino 值的節點應從 Readdir 和 GetAttr 傳回這個值。
MASK_KNOWN_PERMISSIONS
MASK_KNOWN_PROTOCOLS
MASK_PERMISSION_FLAGS 65535 uint64
MASK_POSIX_FLAGS 4294967295 uint64
MAX_ATTRIBUTE_NAME 255 uint64

擴充屬性名稱的大小上限。

新增：18
MAX_BUF 8192 uint64

緩衝作業可傳輸的最大緩衝區空間。目前這項容量設定有些隨意。
MAX_FILENAME 255 uint64

單一檔案系統元件的長度上限 (以位元組為單位)。

已移除：HEAD 已淘汰：27
MAX_FS_NAME_BUFFER 32 uint64
MAX_INLINE_ATTRIBUTE_VALUE 32768 uint64

內嵌擴充屬性值的長度上限。大於這個大小的值會以 VMO 傳遞。

新增：18
MAX_LIST_ATTRIBUTES_CHUNK 128 uint64

ListExtendedAttributes 疊代器中區塊的大小上限。

新增：18
MAX_NAME_LENGTH 255 uint64

單一檔案系統元件的長度上限 (以位元組為單位)。
MAX_PATH_LENGTH 4095 uint64

檔案系統路徑的長度上限 (以位元組為單位)。
MAX_SELINUX_CONTEXT_ATTRIBUTE_LEN 256 uint64

將 SELinux 內容做為屬性傳遞時的大小上限。

新增：HEAD
MAX_TRANSFER_SIZE 8192 uint64

使用位元組向量進行讀取/寫入作業時，允許的最大 I/O 大小。
NODE_PROTOCOL_NAME fuchsia.io/Node String
已移除：29
OPEN_FLAGS_ALLOWED_WITH_NODE_REFERENCE

開啟節點參照時使用的旗標必須在這個遮罩內。
OPEN_RIGHTS

所有已知權利。
PERM_EXECUTABLE

以可執行檔開啟節點時，預期會有一組權限。
PERM_READABLE

以可讀取方式開啟節點時，預期會有的權限組合。
PERM_WRITABLE

以可寫入方式開啟節點時，預期會取得的一組權限。
RW_STAR_DIR

目錄權限別名 rw* 的別名
RX_STAR_DIR

目錄權限別名 rx* 的別名
R_STAR_DIR

目錄權限別名 r* 的別名
SELINUX_CONTEXT_NAME security.selinux String

可透過 SELinux 內容屬性存取的擴充屬性名稱。

新增：HEAD
W_STAR_DIR

目錄權限別名 w* 的別名
X_STAR_DIR

目錄權限別名 x* 的別名

別名

名稱值說明
能力 fuchsia.io/Operations

能力是節點固有的屬性。指定支援哪些作業。

如果對不支援某項作業的節點叫用該作業，會導致 ZX_ERR_NOT_SUPPORTED。請注意，如果兩者皆適用，ZX_ERR_ACCESS_DENIED 的優先順序高於 ZX_ERR_NOT_SUPPORTED。
ExtendedAttributeName vector[MAX_ATTRIBUTE_NAME]

擴充屬性的名稱。不得包含任何空值位元組。除了上述限制和大小上限外，名稱沒有特定結構。

新增：18
Id uint64

如果實作支援不重複節點 ID 的概念，則用於識別節點的類型。

唯一性保證

用戶端通常會看到一個目錄樹狀結構，這是由多個支援實作執行個體組合而成的結果。ID 只在對應的執行個體內不重複。由於目錄 Proxy 會透明轉送，因此在 Fuchsia 上，這些邊界相當隱晦。用戶端在周遊目錄樹狀結構時，如果遇到來自不同備份執行個體的節點，通常會觀察到相同的 Id。因此，這個 ID 最適合用於偵錯和資訊用途。

fuchsia.fs/FilesystemInfo.fs_id 欄位可用於區分不同備份執行個體的 ID。
名稱 string[MAX_NAME_LENGTH]

節點名稱的類型，即單一路徑元件。例如：foo

不變量

有效的節點名稱必須符合下列條件：

  • 長度不得超過 MAX_NAME_LENGTH。
  • 不得空白。
  • 不得為「..」(兩個點)。
  • 不得為「.」(單點)。
  • 不得包含「/」。
  • 不得包含嵌入的 NUL。
路徑 string[MAX_PATH_LENGTH]

路徑是由一或多個元件組成的字串，以「/」分隔。例如：foo/bar/baz

不變量

有效的路徑必須符合下列條件：

  • 不得空白。
  • 長度不得超過 MAX_PATH_LENGTH。
  • 開頭不得為「/」。
  • 結尾不得為「/」。
  • 必須為「.」，或每個元件都必須是有效的名稱。

路徑應在用戶端轉換為標準形式。舉例來說，用戶端應先將 "foo/bar/.././baz/" 轉換為 "foo/baz"，再將其做為路徑使用。
權利 fuchsia.io/Operations

權限是連線專屬的屬性。這類政策會限制連線允許執行的作業，包括可能授予新連線的作業。

如果叫用作業時沒有對應的權限，即使節點不支援該作業，也會產生 ZX_ERR_ACCESS_DENIED。
SymlinkTarget vector[MAX_PATH_LENGTH]
Token zx/Handle

用於識別節點連線的類型。代表一項能力：參照具有相關權利的節點。
轉移 vector[MAX_TRANSFER_SIZE]

用於讀取/寫入作業的位元組向量類型。