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 后，客户端不得发送任何其他请求。

服务器在发送状态响应后，应关闭连接，无论状态如何，且不发送墓志铭。

关闭通道的客户端端点在语义上应等同于调用 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

在由 token 表示的目录中，创建一个名为 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

针对与此节点关联的所有扩展属性名称创建迭代器。如果发生错误，系统会将其作为 epitaph 在迭代器请求通道上返回，然后关闭该通道。

GetExtendedAttributes 可与其中任何名称搭配使用，以检索关联的值。

此方法需要 Rights.READ_BYTES 权限。

新增：18

请求

名称类型
iterator server_end:ExtendedAttributeIterator

OnOpen

FIDL 服务器在 OpenFlags.DESCRIBE 请求时主动生成的事件。

指示打开操作是成功还是失败，并可选择性地描述对象。如果状态为 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 数量可能非常大：类似于对文件多次调用 read，目录具有一个跳转偏移量，该偏移量会在后续调用 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。

属性名称可能已存在，在这种情况下，系统会更新该属性。 如果该属性不存在，系统会创建该属性。名称中不应包含 null 字节。如果存在，则返回 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[];
};

其中名称不以 null 结尾。名称是事件所引用的条目的相对路径。如果事件未引用特定条目（例如，对于 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

分配

为此文件预分配磁盘可用空间。

Added: HEAD

请求

名称类型
offset uint64
length uint64
mode AllocateMode

响应

名称类型
payload File_Allocate_Result

克隆

添加：26

请求

名称类型
request server_end:fuchsia.unknown/Cloneable

关闭

终止连接。

调用 Close 后，客户端不得发送任何其他请求。

服务器在发送状态响应后，应关闭连接，无论状态如何，且不发送墓志铭。

关闭通道的客户端端点在语义上应等同于调用 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。

Added: 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 的语义。

  • request flags VmoFlags，用于指示所需的访问模式。
  • error：一个 zx.Status 值，表示失败。

此方法需要以下权限：

请求

名称类型
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

针对与此节点关联的所有扩展属性名称创建迭代器。如果发生错误，系统会将其作为 epitaph 在迭代器请求通道上返回，然后关闭该通道。

GetExtendedAttributes 可与其中任何名称搭配使用，以检索关联的值。

此方法需要 Rights.READ_BYTES 权限。

新增：18

请求

名称类型
iterator server_end:ExtendedAttributeIterator

OnOpen

FIDL 服务器在 OpenFlags.DESCRIBE 请求时主动生成的事件。

指示打开操作是成功还是失败，并可选择性地描述对象。如果状态为 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。

属性名称可能已存在，在这种情况下，系统会更新该属性。 如果该属性不存在，系统会创建该属性。名称中不应包含 null 字节。如果存在，则返回 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 中定义

Node 定义了可在文件系统中访问的实体的最小接口。

克隆

添加：26

请求

名称类型
request server_end:fuchsia.unknown/Cloneable

关闭

终止连接。

调用 Close 后，客户端不得发送任何其他请求。

服务器在发送状态响应后，应关闭连接，无论状态如何，且不发送墓志铭。

关闭通道的客户端端点在语义上应等同于调用 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

针对与此节点关联的所有扩展属性名称创建迭代器。如果发生错误，系统会将其作为 epitaph 在迭代器请求通道上返回，然后关闭该通道。

GetExtendedAttributes 可与其中任何名称搭配使用，以检索关联的值。

此方法需要 Rights.READ_BYTES 权限。

新增：18

请求

名称类型
iterator server_end:ExtendedAttributeIterator

OnOpen

FIDL 服务器在 OpenFlags.DESCRIBE 请求时主动生成的事件。

指示打开操作是成功还是失败，并可选择性地描述对象。如果状态为 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。

属性名称可能已存在，在这种情况下，系统会更新该属性。 如果该属性不存在，系统会创建该属性。名称中不应包含 null 字节。如果存在，则返回 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 后，客户端不得发送任何其他请求。

服务器在发送状态响应后，应关闭连接，无论状态如何，且不发送墓志铭。

关闭通道的客户端端点在语义上应等同于调用 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

针对与此节点关联的所有扩展属性名称创建迭代器。如果发生错误，系统会将其作为 epitaph 在迭代器请求通道上返回，然后关闭该通道。

GetExtendedAttributes 可与其中任何名称搭配使用，以检索关联的值。

此方法需要 Rights.READ_BYTES 权限。

新增：18

请求

名称类型
iterator server_end:ExtendedAttributeIterator

OnOpen

FIDL 服务器在 OpenFlags.DESCRIBE 请求时主动生成的事件。

指示打开操作是成功还是失败，并可选择性地描述对象。如果状态为 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。

属性名称可能已存在，在这种情况下，系统会更新该属性。 如果该属性不存在，系统会创建该属性。名称中不应包含 null 字节。如果存在，则返回 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 的偏移量。如果 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 中定义

用于需要空结构体的位置（例如空并集成员），以避免创建新的结构体类型。

Added: 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

此文件系统实例的唯一标识符。重启后不再存在。

实现者应创建一个内核对象（通常是一个事件），并将其 koid 用作文件系统 ID。此 koid 可保证在系统中的唯一性。

 无默认应用
block_size uint32

单个文件系统块的大小（以字节为单位）。

 无默认应用
max_filename_size uint32

文件系统名称的长度上限。

 无默认应用
fs_type uint32

底层文件系统类型的唯一标识符。

 无默认应用
padding uint32 无默认应用
name array<int8, 32> 无默认应用

FscryptPolicy

在 fuchsia.io/node.fidl 中定义

与加密目录或文件关联的 Fscrypt 加密政策。

Added: HEAD

字段类型说明默认
key_identifier array<uint8, 16>

16 字节的主密钥标识符（对应于 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 纪元 (UTC) 以来经过的纳秒数表示。

 无默认应用
modification_time uint64

自 Unix 纪元（世界协调时间 [UTC]）以来上次修改的时间（以纳秒为单位）。

 无默认应用

NodeAttributes2

在 fuchsia.io/node.fidl 中定义

字段类型说明默认
mutable_attributes MutableNodeAttributes 无默认应用
immutable_attributes ImmutableNodeAttributes 无默认应用

Node_GetFlags_Response

在 fuchsia.io/node.fidl 中定义

字段类型说明默认
flags Flags 无默认应用

Node_GetToken_Response 资源

在 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 flexible

类型：uint8

在 fuchsia.io/directory.fidl 中定义

名称值说明
0

类型未知的 dirent。
4

表示目录对象的 dirent。
6

表示块存储设备对象的 dirent。
8

表示文件对象的 dirent。
16

表示服务对象的 dirent。

HashAlgorithm flexible

类型：uint8

在 fuchsia.io/file.fidl 中定义

表示用于为启用了 fsverity 的文件构建 Merkle 树的哈希算法。

Added: 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 严格执行

类型：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 纪元 (UTC) 以来，上次更改元数据的时间（以纳秒为单位）。

新增：18
options VerificationOptions

包含已启用 verity 的文件的验证选项。

Added: HEAD
root_hash vector<uint8>:64

文件的根哈希。并非所有文件系统都支持对所有文件执行此操作。

Added: HEAD
verity_enabled bool

如果此文件已启用 verity，则为 true。

Added: HEAD

MutableNodeAttributes

在 fuchsia.io/node.fidl 中定义

序数字段类型说明
creation_time uint64

创建时间，以自 Unix 纪元（世界协调时间）以来的纳秒数表示。
modification_time uint64

上次修改时间，以自 Unix 纪元 (UTC) 以来经过的纳秒数表示。
mode uint32

POSIX 兼容性属性。大多数文件系统都不支持这些。支持这些功能的系统必须仅存储和检索这些功能（例如，作为扩展属性），而不能尝试解释这些功能（例如，通过执行权限检查或专门处理设备打开操作）。

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

上次访问时间（自 Unix 纪元 [UTC] 以来经过的纳秒数）。请注意，如果这是唯一要更新的属性，服务器可能不会始终更新此属性。

新增：18
casefold bool

Casefold（不区分大小写的文件名）支持 此属性只能在空目录中更改，并且会被随后创建的任何子目录继承。 在撰写本文时，唯一支持此功能的文件系统是 Fxfs。

Added: 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。

Added: HEAD
encryption_policy FscryptPolicy

Fscrypt 加密政策支持。 此属性只能在空目录中更改，并且会由随后创建的所有子目录继承。每个目录只能设置一次此属性。设置的政策将用于加密此目录及其子目录的文件内容和文件名。 在撰写本文时，唯一支持此功能的文件系统是 Fxfs。

Added: 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 均未设置（即创建模式为“从不”），则请求将失败并显示 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 中定义

用于对文件启用 verity 的一组选项。

Added: HEAD

序数字段类型说明
hash_algorithm HashAlgorithm
salt vector<uint8>:32

在对每个块进行哈希处理之前，系统会先在块前面加上 salt。

UNIONS

AdvisoryLocking_AdvisoryLock_Result strict

在 fuchsia.io/locking.fidl 中定义

序数变体类型说明
response AdvisoryLocking_AdvisoryLock_Response
err zx/Status

在 fuchsia.io/directory.fidl 中定义

序数变体类型说明

Directory_Rename_Result strict

在 fuchsia.io/directory.fidl 中定义

序数变体类型说明
response Directory_Rename_Response
err zx/Status

在 fuchsia.io/directory.fidl 中定义

序数变体类型说明

ExtendedAttributeIterator_GetNext_Result strict

在 fuchsia.io/node.fidl 中定义

序数变体类型说明
response ExtendedAttributeIterator_GetNext_Response
err zx/Status

ExtendedAttributeValue 灵活 资源

在 fuchsia.io/node.fidl 中定义

扩展属性的值类型。如果值小于 32768 字节，则以内嵌方式包含。大于此大小的值会写入 vmo 缓冲区。

新增：18
序数变体类型说明
bytes vector<uint8>:32768
buffer handle<vmo>

File_Allocate_Result strict

在 fuchsia.io/file.fidl 中定义

序数变体类型说明
response File_Allocate_Response
err zx/Status
framework_err internal

File_EnableVerity_Result strict

在 fuchsia.io/file.fidl 中定义

序数变体类型说明
response File_EnableVerity_Response
err zx/Status
framework_err internal

File_GetBackingMemory_Result strict resource

在 fuchsia.io/file.fidl 中定义

序数变体类型说明
response File_GetBackingMemory_Response
err zx/Status

File_ReadAt_Result strict

在 fuchsia.io/file.fidl 中定义

序数变体类型说明
response File_ReadAt_Response
err zx/Status

File_Resize_Result strict

在 fuchsia.io/file.fidl 中定义

序数变体类型说明
response File_Resize_Response
err zx/Status

File_Seek_Result strict

在 fuchsia.io/file.fidl 中定义

序数变体类型说明
response File_Seek_Response
err zx/Status

File_WriteAt_Result strict

在 fuchsia.io/file.fidl 中定义

序数变体类型说明
response File_WriteAt_Response
err zx/Status

Linkable_LinkInto_Result strict

在 fuchsia.io/node.fidl 中定义

序数变体类型说明
response Linkable_LinkInto_Response
err zx/Status

NodeInfoDeprecated strict resource

在 fuchsia.io/node.fidl 中定义

序数变体类型说明
service Service

连接未提供任何协议信息。
file FileObject

连接由文件组成。
directory DirectoryObject

该连接由目录组成。

Node_GetAttributes_Result strict

在 fuchsia.io/node.fidl 中定义

序数变体类型说明
response NodeAttributes2
err zx/Status

Node_GetExtendedAttribute_Result strict resource

在 fuchsia.io/node.fidl 中定义

序数变体类型说明
response ExtendedAttributeValue
err zx/Status

Node_GetFlags_Result strict

在 fuchsia.io/node.fidl 中定义

序数变体类型说明
response Node_GetFlags_Response
err zx/Status
framework_err internal

Node_GetToken_Result strict resource

在 fuchsia.io/node.fidl 中定义

序数变体类型说明
response Node_GetToken_Response
err zx/Status
framework_err internal

Node_RemoveExtendedAttribute_Result strict

在 fuchsia.io/node.fidl 中定义

序数变体类型说明
response Node_RemoveExtendedAttribute_Response
err zx/Status

Node_SetExtendedAttribute_Result strict

在 fuchsia.io/node.fidl 中定义

序数变体类型说明
response Node_SetExtendedAttribute_Response
err zx/Status

Node_SetFlags_Result strict

在 fuchsia.io/node.fidl 中定义

序数变体类型说明
response Node_SetFlags_Response
err zx/Status
framework_err internal

Node_Sync_Result strict

在 fuchsia.io/node.fidl 中定义

序数变体类型说明
response Node_Sync_Response
err zx/Status

Node_UpdateAttributes_Result strict

在 fuchsia.io/node.fidl 中定义

序数变体类型说明
response Node_UpdateAttributes_Response
err zx/Status

Readable_Read_Result strict

在 fuchsia.io/file.fidl 中定义

序数变体类型说明
response Readable_Read_Response
err zx/Status

表示法灵活 资源

在 fuchsia.io/node.fidl 中定义

序数变体类型说明
node NodeInfo

已为此连接协商 Node 协议。

新增：27
directory DirectoryInfo

已为此连接协商文件协议。
file FileInfo

已为此连接协商文件协议。

SelinuxContext flexible

在 fuchsia.io/node.fidl 中定义

序数变体类型说明
data vector<uint8>:256
use_extended_attributes EmptyStruct

在 fuchsia.io/symlink.fidl 中定义

序数变体类型说明

Writable_Write_Result strict

在 fuchsia.io/file.fidl 中定义

序数变体类型说明
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 将被忽略。
Added: 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 字段可以与此类型相互转换，而无需进行转换。

Added: 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 中定义

用于更新节点的“attributes”字段由“flags”参数指示。

名称值说明
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

验证属性。

Added: HEAD
32768
Added: HEAD
65536
Added: HEAD
131072

支持 Casefold（不区分大小写的文件名）。 如果为 true，则文件查找将不区分大小写，但会保留大小写。也就是说，“Foo”将逐字存储，但可以作为“foo”“fOO”等打开。大小写折叠是根据 Unicode 12 NFD 规范化和大小写折叠标准完成的。

Added: HEAD
262144

请求 MutableNodeAttributes.selinux_context。如需了解详情，请参阅该字段。

Added: HEAD
524288

请求 MutableNodeAttributes.encryption_policy。

Added: 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）无法识别文件访问何时发生，因此无法更新访问时间。我们允许客户端向底层文件系统传达已发生文件访问且正在等待访问时间更新的信息。

警告：如果在没有事先访问文件的情况下查询此属性，只要满足上述条件，节点的访问时间就会更新。并非所有文件系统都支持此功能。如果文件系统不支持此操作，系统将忽略该查询。

Added: HEAD

NodeProtocolKinds 灵活

类型：uint64

在 fuchsia.io/node-protocols.fidl 中定义

节点在打开时可能有多种受支持的表示形式，即使它可能具有固定的底层身份。

目前，文件通过 File 协议访问，并在使用 GET_REPRESENTATION 打开时发送 Representation.FileInfo。不过，将来我们可能会引入更复杂的 FileV2 协议，或由专用内核对象支持的更高效的 SuperFastFile。新客户端可以通过在 NodeProtocolKinds 中指定相应的位来请求更高级的表示，而现有客户端将继续通过旧表示与节点通信。

NodeProtocolKinds 通过一种协议协商形式实现向前兼容性。

这些元素与 Representation 的成员具有一对一的对应关系。

名称值说明
1

节点的连接器表示。

连接将使用 Node 或目标协议，具体取决于打开期间使用的标志。
2

节点的目录表示。

该连接将使用目录协议。
4

节点的文件表示形式。

该连接将使用 File 协议。

OpenFlags strict

类型：uint32

在 fuchsia.io/directory.fidl 中定义

已弃用 - 请改用标志。

名称值说明
1

可以从目标对象中读取。
2

可以写入目标对象。
8

连接可以映射目标对象可执行文件。
65536

如果对象不存在，则创建该对象。
131072

（与 Create 搭配使用）如果对象已存在，则失败。
262144

在使用前截断对象。
524288

断言要打开的对象是目录。 如果目标对象不是目录，则返回错误。
1048576

在所有写入操作之前，先跳转到对象的末尾。
4194304

打开对对象的引用，而不是对象本身。 只有将以下标志与 NODE_REFERENCE 一起传递才有效：

  • DIRECTORY
  • NOT_DIRECTORY
  • DESCRIBE 否则会返回错误。 如果使用此方法打开或克隆对象，则生成的连接不会带有任何权限标志。 生成的连接允许执行一组有限的操作：GetAttr、Clone、Close、Describe 和 GetFlags。连接将使用 Node 协议。调用 SetAttr 或 SetFlags 会导致 ZX_ERR_BAD_HANDLE。
8388608

请求向接口请求发送“OnOpen”事件。

如果打开/克隆成功，该事件将包含一个非 null 的 NodeInfoDeprecated。这可用于打开不构成 fuchsia.io/Node 的协议；系统会发送事件，就像协议是 fuchsia.io/Node 一样，然后仅使用目标协议。
134217728

指定此标志可请求在写入权限处理方面实现 POSIX 兼容性。 目前，它会影响打开应用时的权限处理：

  • 如果目标路径是目录，则当且仅当当前连接和所有中间装载点均可写入时，新连接的权限才会扩展为包含 WRITABLE。
  • 否则，系统会忽略此标志。如果请求的权限超出当前连接或任何中间装载点的权限，则会发生访问遭拒错误。

如果省略此标志，打开操作始终会使用请求的权限，如果请求的权限超出附加到当前连接的权限，则操作会失败并显示“访问遭拒”错误。

如果请求连接是只读的，并且请求的权限是只读的，则服务器可能会忽略该标志，并且不会将其转发到下游。这是实现细节，对于在装载点之间强制执行分层权限是必要的，并且不应对客户端的预期行为产生任何影响。
268435456

指定此标志可请求在执行权限处理方面实现 POSIX 兼容性。 目前，它会影响打开应用时的权限处理：

  • 如果目标路径是目录，则当且仅当当前连接和所有中间装载点可执行时，新连接上的权限才会扩展为包含 EXECUTABLE。
  • 否则，系统会忽略此标志。如果请求的权限超出当前连接或任何中间装载点的权限，则会发生访问遭拒错误。

如果省略此标志，打开操作始终会使用请求的权限，如果请求的权限超出附加到当前连接的权限，则操作会失败并显示“访问遭拒”错误。

如果请求连接是只读的，并且请求的权限是只读的，则服务器可能会忽略该标志，并且不会将其转发到下游。这是实现细节，对于在装载点之间强制执行分层权限是必要的，并且不应对客户端的预期行为产生任何影响。
33554432

断言要打开的对象不是目录。 如果目标对象是目录，则返回错误。
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 严格执行

类型：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_create_child() 与 ZX_VMO_CHILD_SNAPSHOT 搭配使用。不过，除了实现无法返回 SHARED_BUFFER 的情况之外，如果 VMO 附加到分页器，创建完整快照也会失败。由于大多数文件系统都会使用分页系统，因此完整快照方法应仅在客户端与已知服务器通信的特定情况下使用。
131072

需要一个 VMO，用于直接访问文件底层 VMO 的内容。如果无法提供此类 VMO，请求应失败。可能未随附PRIVATE_CLONE。

即使请求了 WRITE 访问权限，返回的 VMO 也可能无法调整大小。在这种情况下，应使用 File.Resize 调整文件大小。

WatchMask 严格执行

类型：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 之外单独定义的。

Added: 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 上下文作为属性传递的大小上限。

Added: 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 上下文属性访问的扩展属性的名称。

Added: 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]

扩展属性的名称。不能包含任何 null 字节。除了这些限制和大小上限之外，名称没有特定的结构要求。

新增：18
ID uint64

用于标识节点的类型（如果实现支持某种唯一节点 ID 概念）。

唯一性保证

客户端通常会看到一个目录树，该目录树是多个后备实现实例组合在一起的结果。ID 仅在相应实例中是唯一的。 由于透明转发目录代理，它们的边界在 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]

用于读/写操作的字节向量类型。