fuchsia.io2

Library Overview

PROTOCOLS

Debuglog

Defined in fuchsia.io2/debuglog.fidl

A node for interacting with the kernel debug log. It may be manipulated via the debuglog object returned from the DebuglogInfo member in Representation.

Reopen

Creates another connection to the same node.

  • options options applicable to both Open and Reopen, including negotiating protocol and restricting rights. See ConnectionOptions.
  • object_request is the server end of a channel created for the new connection. The caller may proceed to send messages on the corresponding client end right away.

For files, the cloned connection and the original connection have independent seek offsets.

Request

NameType
options ConnectionOptions
object_request handle<channel>

Close

Terminates the connection to the node.

After calling Close, the client must not send any other requests. The result of Close arrives as an epitaph, where the channel is closed by the server upon processing this operation.

Closing the client end of the channel should be semantically equivalent to calling Close without monitoring the status epitaph.

This method does not require any rights.

Request

NameType

Describe

Returns extra connection information and auxiliary handles.

  • query specifies the fields in ConnectionInfo that the caller is interested in.

When all known bits in query are set, the return value matches the one from OnConnectionInfo, as if the caller requested that event using ConnectionFlags.GET_CONNECTION_INFO.

If the Describe operation fails, the connection is closed with the associated error.

This method does not require any rights.

Request

NameType
query ConnectionInfoQuery

Response

NameType
info ConnectionInfo

OnConnectionInfo

An event produced eagerly by the server if requested by ConnectionFlags.GET_CONNECTION_INFO. This event will be the first message from the server, and is sent exactly once.

  • info See ConnectionInfo for details on the fields. All members should be present.

Different from fuchsia.io/OnOpen, an error during open/reopen is always manifested as an epitaph.

Response

NameType
info ConnectionInfo

GetToken

Acquires a token which can be used to identify this connection at a later point in time.

This method does not require any rights. Note that the token identifies the connection, hence carries the rights information on this connection.

Request

NameType

Response

NameType
result Node_GetToken_Result

GetAttributes

Acquires information about the node.

The attributes of a node should be stable, independent of the specific protocol used to access it.

  • query a bit-mask specifying which attributes to fetch. The server should not return more than necessary.
  • attributes the returned attributes.

This method requires the Rights.GET_ATTRIBUTES right.

Request

NameType
query NodeAttributesQuery

Response

NameType
result Node_GetAttributes_Result

UpdateAttributes

Updates information about the node.

  • attributes the presence of a table field in attributes indicates the intent to update the corresponding attribute.

This method requires the Rights.UPDATE_ATTRIBUTES right.

Request

NameType
attributes NodeAttributes

Response

NameType
result Node_UpdateAttributes_Result

Sync

Synchronizes updates to the node to the underlying media, if it exists.

This method will return when the filesystem server has flushed the relevant updates to the underlying media, but does not guarantee the underlying media has persisted the information, nor that any information is committed to hardware. Clients may use Sync to ensure ordering between operations.

This method does not require any rights.

Request

NameType

Response

NameType
result Node_Sync_Result

DirectoryIterator

Defined in fuchsia.io2/directory-iterator.fidl

GetNext

Reads a collection of variably sized directory entries into a buffer.

The number of entries in a directory may be very large: akin to calling read multiple times on a file, directories have a seek offset which is updated on subsequent calls to Enumerate. The caller should always use a receiving buffer size as large as the maximum channel limit.

When the end of iteration is reached, the returned entries vector will be empty.

This method does not require any rights, as the rights are checked in the Directory.Enumerate call.

Request

NameType

Response

NameType
result DirectoryIterator_GetNext_Result

DirectoryWatcher

Defined in fuchsia.io2/directory-watcher.fidl

DirectoryWatcher transmits messages from a filesystem server about events happening in the filesystem. Clients can register new watchers using the Directory.Watch method, where they can filter which events they want to receive notifications for.

GetNext

A hanging get to obtain the next batch of events.

The caller should always use a receiving buffer size as large as the maximum channel limit.

Clients should attempt to maintain one in-flight GetNext call as much as possible. If GetNext is not constantly polled, the filesystem server might hit an upper limit on the number of buffered events, resulting in dropping. Should this happen, the connection will be closed with a ZX_ERR_IO_OVERRUN epitaph.

When the watched directory is deleted, this connection will be closed with a ZX_ERR_UNAVAILABLE epitaph. When the filesystem server is dying, this connection will be closed with a ZX_ERR_PEER_CLOSED epitaph.

Request

NameType

Response

NameType
events vector<DirectoryWatchedEvent>[8192]

Directory

Defined in fuchsia.io2/directory.fidl

A Node that is capable of containing other nodes.

Reopen

Creates another connection to the same node.

  • options options applicable to both Open and Reopen, including negotiating protocol and restricting rights. See ConnectionOptions.
  • object_request is the server end of a channel created for the new connection. The caller may proceed to send messages on the corresponding client end right away.

For files, the cloned connection and the original connection have independent seek offsets.

Request

NameType
options ConnectionOptions
object_request handle<channel>

Close

Terminates the connection to the node.

After calling Close, the client must not send any other requests. The result of Close arrives as an epitaph, where the channel is closed by the server upon processing this operation.

Closing the client end of the channel should be semantically equivalent to calling Close without monitoring the status epitaph.

This method does not require any rights.

Request

NameType

Describe

Returns extra connection information and auxiliary handles.

  • query specifies the fields in ConnectionInfo that the caller is interested in.

When all known bits in query are set, the return value matches the one from OnConnectionInfo, as if the caller requested that event using ConnectionFlags.GET_CONNECTION_INFO.

If the Describe operation fails, the connection is closed with the associated error.

This method does not require any rights.

Request

NameType
query ConnectionInfoQuery

Response

NameType
info ConnectionInfo

OnConnectionInfo

An event produced eagerly by the server if requested by ConnectionFlags.GET_CONNECTION_INFO. This event will be the first message from the server, and is sent exactly once.

  • info See ConnectionInfo for details on the fields. All members should be present.

Different from fuchsia.io/OnOpen, an error during open/reopen is always manifested as an epitaph.

Response

NameType
info ConnectionInfo

GetToken

Acquires a token which can be used to identify this connection at a later point in time.

This method does not require any rights. Note that the token identifies the connection, hence carries the rights information on this connection.

Request

NameType

Response

NameType
result Node_GetToken_Result

GetAttributes

Acquires information about the node.

The attributes of a node should be stable, independent of the specific protocol used to access it.

  • query a bit-mask specifying which attributes to fetch. The server should not return more than necessary.
  • attributes the returned attributes.

This method requires the Rights.GET_ATTRIBUTES right.

Request

NameType
query NodeAttributesQuery

Response

NameType
result Node_GetAttributes_Result

UpdateAttributes

Updates information about the node.

  • attributes the presence of a table field in attributes indicates the intent to update the corresponding attribute.

This method requires the Rights.UPDATE_ATTRIBUTES right.

Request

NameType
attributes NodeAttributes

Response

NameType
result Node_UpdateAttributes_Result

Sync

Synchronizes updates to the node to the underlying media, if it exists.

This method will return when the filesystem server has flushed the relevant updates to the underlying media, but does not guarantee the underlying media has persisted the information, nor that any information is committed to hardware. Clients may use Sync to ensure ordering between operations.

This method does not require any rights.

Request

NameType

Response

NameType
result Node_Sync_Result

Open

Opens or creates a new node relative to this directory node.

  • path identifies the node to open. If path contains multiple segments, then the directory is traversed, one segment at a time, relative to the directory represented by this connection. See Path for what constitutes a valid path. To open another connection to the current directory, use Node.Reopen instead.
  • mode controls whether to open existing/create new etc.
  • options additional options applicable to both Open and Reopen, including negotiating protocol and restricting rights. See ConnectionOptions.
  • object_request is the server end of a channel created for the new connection. The caller may proceed to send messages on the corresponding client end right away.

This method requires the following rights on the current connection:

Errors are presented as an epitaph on the object_request channel.

  • error ZX_ERR_ACCESS_DENIED if the requested rights exceeds what is allowed.
  • error ZX_ERR_BAD_PATH if path is invalid.

Request

NameType
path Path
mode OpenMode
options ConnectionOptions
object_request handle<channel>

Removes a child node from the this directory's list of entries.

Note: this does not guarantee that the underlying object is destroyed. Although the link will be removed from the containing directory, objects with multiple references (such as files which are still open) will not actually be destroyed until all references are closed.

  • path identifies the node to be detached. If path contains multiple segments, then the directory is traversed, one segment at a time, relative to the directory represented by this connection.
  • error ZX_ERR_ACCESS_DENIED if the connection does not have Rights.WRITE_BYTES.
  • error ZX_ERR_NOT_SUPPORTED if the underlying filesystem does not support writing.
  • error ZX_ERR_BAD_PATH if path is invalid.
  • error ZX_ERR_NOT_EMPTY if path refers to a non-empty directory.
  • error ZX_ERR_UNAVAILABLE if path refers to a mount point, containing a remote channel.

Other errors may be returned for filesystem-specific reasons.

This method requires the following rights:

Request

NameType
path Path

Response

NameType
result Directory_Unlink_Result

Enumerate

Initiates a directory listing operation over the input channel, starting at seek offset 0.

This method requires the Rights.ENUMERATE right. If this right is absent, iterator will be closed with a ZX_ERR_ACCESS_DENIED epitaph.

Request

NameType
iterator request<DirectoryIterator>

Rename

Renames a node named src to the name dst, in a directory represented by dst_parent_token.

src and dst must be valid node names. See Name for what constitutes a valid name.

This method requires the following rights on both the current connection, and the connection identified by dst_parent_token:

Request

NameType
src Name
dst_parent_token Token
dst Name

Response

NameType
result Directory_Rename_Result

Creates a link to a node named src by the name dst, in a directory represented by dst_parent_token.

Directories cannot be linked, to prevent reference cycles.

src and dst must be valid node names. See Name for what constitutes a valid name.

This method requires the following rights on both the current connection, and the connection identified by dst_parent_token:

Request

NameType
src Name
dst_parent_token Token
dst Name

Response

NameType
result Directory_Link_Result

Watch

Watches a directory, monitoring events for children being added or removed on the server end of the watcher channel.

Mask specifies a bit mask of events to observe.

This method requires the Rights.ENUMERATE right. If this right is absent, watcher will be closed with a ZX_ERR_ACCESS_DENIED epitaph.

Request

NameType
mask DirectoryWatchMask
options DirectoryWatchOptions
watcher request<DirectoryWatcher>

File

Defined in fuchsia.io2/file.fidl

A Node which contains a sequence of bytes of definite length.

Reopen

Creates another connection to the same node.

  • options options applicable to both Open and Reopen, including negotiating protocol and restricting rights. See ConnectionOptions.
  • object_request is the server end of a channel created for the new connection. The caller may proceed to send messages on the corresponding client end right away.

For files, the cloned connection and the original connection have independent seek offsets.

Request

NameType
options ConnectionOptions
object_request handle<channel>

Close

Terminates the connection to the node.

After calling Close, the client must not send any other requests. The result of Close arrives as an epitaph, where the channel is closed by the server upon processing this operation.

Closing the client end of the channel should be semantically equivalent to calling Close without monitoring the status epitaph.

This method does not require any rights.

Request

NameType

Describe

Returns extra connection information and auxiliary handles.

  • query specifies the fields in ConnectionInfo that the caller is interested in.

When all known bits in query are set, the return value matches the one from OnConnectionInfo, as if the caller requested that event using ConnectionFlags.GET_CONNECTION_INFO.

If the Describe operation fails, the connection is closed with the associated error.

This method does not require any rights.

Request

NameType
query ConnectionInfoQuery

Response

NameType
info ConnectionInfo

OnConnectionInfo

An event produced eagerly by the server if requested by ConnectionFlags.GET_CONNECTION_INFO. This event will be the first message from the server, and is sent exactly once.

  • info See ConnectionInfo for details on the fields. All members should be present.

Different from fuchsia.io/OnOpen, an error during open/reopen is always manifested as an epitaph.

Response

NameType
info ConnectionInfo

GetToken

Acquires a token which can be used to identify this connection at a later point in time.

This method does not require any rights. Note that the token identifies the connection, hence carries the rights information on this connection.

Request

NameType

Response

NameType
result Node_GetToken_Result

GetAttributes

Acquires information about the node.

The attributes of a node should be stable, independent of the specific protocol used to access it.

  • query a bit-mask specifying which attributes to fetch. The server should not return more than necessary.
  • attributes the returned attributes.

This method requires the Rights.GET_ATTRIBUTES right.

Request

NameType
query NodeAttributesQuery

Response

NameType
result Node_GetAttributes_Result

UpdateAttributes

Updates information about the node.

  • attributes the presence of a table field in attributes indicates the intent to update the corresponding attribute.

This method requires the Rights.UPDATE_ATTRIBUTES right.

Request

NameType
attributes NodeAttributes

Response

NameType
result Node_UpdateAttributes_Result

Sync

Synchronizes updates to the node to the underlying media, if it exists.

This method will return when the filesystem server has flushed the relevant updates to the underlying media, but does not guarantee the underlying media has persisted the information, nor that any information is committed to hardware. Clients may use Sync to ensure ordering between operations.

This method does not require any rights.

Request

NameType

Response

NameType
result Node_Sync_Result

Seek

Moves the offset at which the next invocation of Read or Write will occur. The seek offset is specific to each file connection.

  • request origin the reference point where offset will be based on.
  • request offset the number of bytes to seek.
  • response offset_from_start the adjusted seek offset, from the start of the file.

This method does not require any rights.

Request

NameType
origin SeekOrigin
offset int64

Response

NameType
result File_Seek_Result

Read

Reads up to 'count' bytes at the seek offset. The seek offset is moved forward by the number of bytes read.

Invariants

  • The returned data.length will never be greater than count.
  • If data.length is less than count, it means that the seek offset has reached the end of file as part of this operation.
  • If data.length is zero while count is not, it means that the seek offset is already at or beyond the end of file, and no data could be read.
  • If count is zero, the server should perform all the checks ensuring read access without actually read anything, and return an empty data vector.

This method requires the Rights.READ_BYTES right.

Request

NameType
count uint64

Response

NameType
result File_Read_Result

Write

Writes data at the seek offset. The seek offset is moved forward by the number of bytes written. If the file is in append mode, the seek offset is first set to the end of the file, followed by the write, in one atomic step.

The file size may grow if the seek offset plus data.length is beyond the current end of file.

  • request data the byte buffer to write to the file.
  • response actual_count the number of bytes written.

Invariants

  • The returned actual_count will never be greater than data.length.
  • If the server is unable to write all the data due to e.g. not enough space, actual_count may be less than data.length.
  • If data.length is zero, the server should perform all the checks ensuring write access without mutating the file. The seek offset is still updated if in append mode.

This method requires the Rights.WRITE_BYTES right.

Request

NameType
data Transfer

Response

NameType
result File_Write_Result

ReadAt

Reads up to 'count' bytes at the provided offset. Does not affect the seek offset.

Invariants

  • The returned data.length will never be greater than count.
  • If data.length is less than count, it means that ReadAt has hit the end of file as part of this operation.
  • If data.length is zero while count is not, it means that offset is at or past the end of file, and no data can be read.
  • If count is zero, the server should perform all the checks ensuring read access without actually reading anything, and return an empty data vector.

This method requires the Rights.READ_BYTES right.

Request

NameType
count uint64
offset uint64

Response

NameType
result File_ReadAt_Result

WriteAt

Writes data at the provided offset. Does not affect the seek offset.

The file size may grow if offset plus data.length is past the current end of file.

  • request data the byte buffer to write to the file.
  • request offset the offset from start of the file to begin writing.
  • response actual_count the number of bytes written.

Invariants

  • The returned actual_count will never be greater than data.length.
  • If the server is unable to write all the data due to e.g. not enough space, actual_count may be less than data.length.
  • If data.length is zero, the server should perform all the checks ensuring write access without mutating the file.

This method requires the Rights.WRITE_BYTES right.

Request

NameType
data Transfer
offset uint64

Response

NameType
result File_WriteAt_Result

Resize

Shrinks or grows the file size to 'length' bytes.

If file size is reduced by this operation, the extra trailing data' is discarded. If file size is increased by this operation, the extended area appears as if it was zeroed.

This method requires the Rights.WRITE_BYTES right.

Request

NameType
length uint64

Response

NameType
result File_Resize_Result

GetMemRange

Acquires a fuchsia.mem/Range representing this file, if there is one, with the requested access rights.

  • request flags a VmoFlags indicating the desired mode of access.
  • error a zx.status value indicating the failure.

This method requires the following rights:

Request

NameType
flags VmoFlags

Response

NameType
result File_GetMemRange_Result

Memory

Defined in fuchsia.io2/memory.fidl

A file-like node backed by a VMO. No memory-specific methods are provided by this protocol. The client should access it via the the MemoryInfo.buffer object in Representation.

Reopen

Creates another connection to the same node.

  • options options applicable to both Open and Reopen, including negotiating protocol and restricting rights. See ConnectionOptions.
  • object_request is the server end of a channel created for the new connection. The caller may proceed to send messages on the corresponding client end right away.

For files, the cloned connection and the original connection have independent seek offsets.

Request

NameType
options ConnectionOptions
object_request handle<channel>

Close

Terminates the connection to the node.

After calling Close, the client must not send any other requests. The result of Close arrives as an epitaph, where the channel is closed by the server upon processing this operation.

Closing the client end of the channel should be semantically equivalent to calling Close without monitoring the status epitaph.

This method does not require any rights.

Request

NameType

Describe

Returns extra connection information and auxiliary handles.

  • query specifies the fields in ConnectionInfo that the caller is interested in.

When all known bits in query are set, the return value matches the one from OnConnectionInfo, as if the caller requested that event using ConnectionFlags.GET_CONNECTION_INFO.

If the Describe operation fails, the connection is closed with the associated error.

This method does not require any rights.

Request

NameType
query ConnectionInfoQuery

Response

NameType
info ConnectionInfo

OnConnectionInfo

An event produced eagerly by the server if requested by ConnectionFlags.GET_CONNECTION_INFO. This event will be the first message from the server, and is sent exactly once.

  • info See ConnectionInfo for details on the fields. All members should be present.

Different from fuchsia.io/OnOpen, an error during open/reopen is always manifested as an epitaph.

Response

NameType
info ConnectionInfo

GetToken

Acquires a token which can be used to identify this connection at a later point in time.

This method does not require any rights. Note that the token identifies the connection, hence carries the rights information on this connection.

Request

NameType

Response

NameType
result Node_GetToken_Result

GetAttributes

Acquires information about the node.

The attributes of a node should be stable, independent of the specific protocol used to access it.

  • query a bit-mask specifying which attributes to fetch. The server should not return more than necessary.
  • attributes the returned attributes.

This method requires the Rights.GET_ATTRIBUTES right.

Request

NameType
query NodeAttributesQuery

Response

NameType
result Node_GetAttributes_Result

UpdateAttributes

Updates information about the node.

  • attributes the presence of a table field in attributes indicates the intent to update the corresponding attribute.

This method requires the Rights.UPDATE_ATTRIBUTES right.

Request

NameType
attributes NodeAttributes

Response

NameType
result Node_UpdateAttributes_Result

Sync

Synchronizes updates to the node to the underlying media, if it exists.

This method will return when the filesystem server has flushed the relevant updates to the underlying media, but does not guarantee the underlying media has persisted the information, nor that any information is committed to hardware. Clients may use Sync to ensure ordering between operations.

This method does not require any rights.

Request

NameType

Response

NameType
result Node_Sync_Result

Node

Defined in fuchsia.io2/node.fidl

Node defines the minimal protocol for entities which can be accessed in a filesystem.

Reopen

Creates another connection to the same node.

  • options options applicable to both Open and Reopen, including negotiating protocol and restricting rights. See ConnectionOptions.
  • object_request is the server end of a channel created for the new connection. The caller may proceed to send messages on the corresponding client end right away.

For files, the cloned connection and the original connection have independent seek offsets.

Request

NameType
options ConnectionOptions
object_request handle<channel>

Close

Terminates the connection to the node.

After calling Close, the client must not send any other requests. The result of Close arrives as an epitaph, where the channel is closed by the server upon processing this operation.

Closing the client end of the channel should be semantically equivalent to calling Close without monitoring the status epitaph.

This method does not require any rights.

Request

NameType

Describe

Returns extra connection information and auxiliary handles.

  • query specifies the fields in ConnectionInfo that the caller is interested in.

When all known bits in query are set, the return value matches the one from OnConnectionInfo, as if the caller requested that event using ConnectionFlags.GET_CONNECTION_INFO.

If the Describe operation fails, the connection is closed with the associated error.

This method does not require any rights.

Request

NameType
query ConnectionInfoQuery

Response

NameType
info ConnectionInfo

OnConnectionInfo

An event produced eagerly by the server if requested by ConnectionFlags.GET_CONNECTION_INFO. This event will be the first message from the server, and is sent exactly once.

  • info See ConnectionInfo for details on the fields. All members should be present.

Different from fuchsia.io/OnOpen, an error during open/reopen is always manifested as an epitaph.

Response

NameType
info ConnectionInfo

GetToken

Acquires a token which can be used to identify this connection at a later point in time.

This method does not require any rights. Note that the token identifies the connection, hence carries the rights information on this connection.

Request

NameType

Response

NameType
result Node_GetToken_Result

GetAttributes

Acquires information about the node.

The attributes of a node should be stable, independent of the specific protocol used to access it.

  • query a bit-mask specifying which attributes to fetch. The server should not return more than necessary.
  • attributes the returned attributes.

This method requires the Rights.GET_ATTRIBUTES right.

Request

NameType
query NodeAttributesQuery

Response

NameType
result Node_GetAttributes_Result

UpdateAttributes

Updates information about the node.

  • attributes the presence of a table field in attributes indicates the intent to update the corresponding attribute.

This method requires the Rights.UPDATE_ATTRIBUTES right.

Request

NameType
attributes NodeAttributes

Response

NameType
result Node_UpdateAttributes_Result

Sync

Synchronizes updates to the node to the underlying media, if it exists.

This method will return when the filesystem server has flushed the relevant updates to the underlying media, but does not guarantee the underlying media has persisted the information, nor that any information is committed to hardware. Clients may use Sync to ensure ordering between operations.

This method does not require any rights.

Request

NameType

Response

NameType
result Node_Sync_Result

Pipe

Defined in fuchsia.io2/pipe.fidl

A node for streaming unstructured data. No pipe-specific methods are provided by this protocol. The client should access the pipe via the socket object returned from the PipeInfo member in Representation.

Reopen

Creates another connection to the same node.

  • options options applicable to both Open and Reopen, including negotiating protocol and restricting rights. See ConnectionOptions.
  • object_request is the server end of a channel created for the new connection. The caller may proceed to send messages on the corresponding client end right away.

For files, the cloned connection and the original connection have independent seek offsets.

Request

NameType
options ConnectionOptions
object_request handle<channel>

Close

Terminates the connection to the node.

After calling Close, the client must not send any other requests. The result of Close arrives as an epitaph, where the channel is closed by the server upon processing this operation.

Closing the client end of the channel should be semantically equivalent to calling Close without monitoring the status epitaph.

This method does not require any rights.

Request

NameType

Describe

Returns extra connection information and auxiliary handles.

  • query specifies the fields in ConnectionInfo that the caller is interested in.

When all known bits in query are set, the return value matches the one from OnConnectionInfo, as if the caller requested that event using ConnectionFlags.GET_CONNECTION_INFO.

If the Describe operation fails, the connection is closed with the associated error.

This method does not require any rights.

Request

NameType
query ConnectionInfoQuery

Response

NameType
info ConnectionInfo

OnConnectionInfo

An event produced eagerly by the server if requested by ConnectionFlags.GET_CONNECTION_INFO. This event will be the first message from the server, and is sent exactly once.

  • info See ConnectionInfo for details on the fields. All members should be present.

Different from fuchsia.io/OnOpen, an error during open/reopen is always manifested as an epitaph.

Response

NameType
info ConnectionInfo

GetToken

Acquires a token which can be used to identify this connection at a later point in time.

This method does not require any rights. Note that the token identifies the connection, hence carries the rights information on this connection.

Request

NameType

Response

NameType
result Node_GetToken_Result

GetAttributes

Acquires information about the node.

The attributes of a node should be stable, independent of the specific protocol used to access it.

  • query a bit-mask specifying which attributes to fetch. The server should not return more than necessary.
  • attributes the returned attributes.

This method requires the Rights.GET_ATTRIBUTES right.

Request

NameType
query NodeAttributesQuery

Response

NameType
result Node_GetAttributes_Result

UpdateAttributes

Updates information about the node.

  • attributes the presence of a table field in attributes indicates the intent to update the corresponding attribute.

This method requires the Rights.UPDATE_ATTRIBUTES right.

Request

NameType
attributes NodeAttributes

Response

NameType
result Node_UpdateAttributes_Result

Sync

Synchronizes updates to the node to the underlying media, if it exists.

This method will return when the filesystem server has flushed the relevant updates to the underlying media, but does not guarantee the underlying media has persisted the information, nor that any information is committed to hardware. Clients may use Sync to ensure ordering between operations.

This method does not require any rights.

Request

NameType

Response

NameType
result Node_Sync_Result

STRUCTS

DirectoryIterator_GetNext_Response

generated

NameTypeDescriptionDefault
entries vector<DirectoryEntry>[8192] No default

IdleEvent

Defined in fuchsia.io2/directory-watcher.fidl

NameTypeDescriptionDefault

generated

NameTypeDescriptionDefault

Directory_Rename_Response

generated

NameTypeDescriptionDefault

generated

NameTypeDescriptionDefault

File_Seek_Response

generated

NameTypeDescriptionDefault
offset_from_start uint64 No default

File_Read_Response

generated

NameTypeDescriptionDefault
data Transfer No default

File_Write_Response

generated

NameTypeDescriptionDefault
actual_count uint64 No default

File_ReadAt_Response

generated

NameTypeDescriptionDefault
data Transfer No default

File_WriteAt_Response

generated

NameTypeDescriptionDefault
actual_count uint64 No default

File_Resize_Response

generated

NameTypeDescriptionDefault

File_GetMemRange_Response

generated

NameTypeDescriptionDefault
buffer fuchsia.mem/Range No default

Node_GetToken_Response

generated

NameTypeDescriptionDefault
token Token No default

Node_GetAttributes_Response

generated

NameTypeDescriptionDefault
attributes NodeAttributes No default

Node_UpdateAttributes_Response

generated

NameTypeDescriptionDefault

Node_Sync_Response

generated

NameTypeDescriptionDefault

ENUMS

OpenMode

Type: uint32

Defined in fuchsia.io2/directory.fidl

Options related to node creation during Directory.Open.

NameValueDescription
OPEN_EXISTING 1

Only succeed if the object exists.

MAYBE_CREATE 2

Create the object if it does not exist, otherwise open existing. The check and the creation are performed in one atomic step.

ALWAYS_CREATE 3

Assert that the object does not exist, then create it. The assertion and creation are performed in one atomic step.

OPEN_MOUNT_POINT 268435456

If the object is a mount point, open the local directory instead of forwarding the request. The object must be a directory.

This option implies the behavior of OPEN_EXISTING.

SeekOrigin

Type: uint32

Defined in fuchsia.io2/file.fidl

The reference point for updating the seek offset. See File.Seek.

NameValueDescription
START 1

Seek from the start of the file. The seek offset will be set to offset bytes. The seek offset cannot be negative in this case.

CURRENT 2

Seek from the current position in the file. The seek offset will be the current seek offset plus offset bytes.

END 3

Seek from the end of the file. The seek offset will be the file size plus offset bytes.

TABLES

ConnectionInfo

Defined in fuchsia.io2/connection-info.fidl

Returns run-time information about a node that is specific to the current connection.

OrdinalNameTypeDescription
1 representation Representation

The active variant corresponds to one of the supported protocols of the node, and represents the result of the connection-time negotiation. Provides auxiliary handles if applicable.

2 rights Rights

Information about the rights possessed by the current connection. Note: rights limits the set of operations allowed on the connection, but does not guarantee their availability. For example, one may have the Rights.EXECUTE right on a file connection, but the file itself does not have the EXECUTE ability, and hence cannot be executed. See ConnectionOptions.rights.

3 available_operations Operations

The set of available operations on this channel. It is always the intersection between the rights possessed by this connection, and the abilities of the node. The value may be zero in the case of an empty intersection. See ConnectionOptions.rights.

ConnectionOptions

Defined in fuchsia.io2/connection-options.fidl

Options for Directory.Open and Node.Reopen.

OrdinalNameTypeDescription
1 flags ConnectionFlags

Flags which can affect the behavior when opening and reopening. If absent, assumes a default of zero.

2 protocols NodeProtocolSet

Specifies the set of representations accepted by the client, to support a form of protocol negotiation on the node being opened. Refer to the definition of NodeProtocolSet for more details. It cannot be zero.

In addition, clients may assert the type of the object by setting the protocol corresponding to the expected type:

  • If the caller expected a directory but the node cannot be accessed as a directory, the error is ZX_ERR_NOT_DIR.
  • If the caller expected a file but the node cannot be accessed as a file, the error is ZX_ERR_NOT_FILE.
  • In other mismatched cases, the error is ZX_ERR_WRONG_TYPE.

During Directory.Open, if a new object is to be created, protocols determines the type of object to create; it must be present. If a valid object type cannot be unambiguously inferred e.g. both DIRECTORY and FILE were set, the request must fail.

During Node.Reopen, clients may specify a different but compatible protocols to do a "protocol upgrade".

If more than one protocol is present in protocols, the resultant protocol may become any one of them. Clients should specify ConnectionFlags.GET_CONNECTION_INFO to receive a Node.OnConnectionInfo event, in order to ascertain the protocol.

If absent, indicates that the caller accepts any type of node, and the resulting protocol is unspecified.

3 rights Rights

Requests the specified rights on the new connection. If absent, inherits the same rights as the source connection.

Rights Hierarchy

Respecting principles of least privileges, rights must meet the following restrictions:

  • A connection must have nonzero rights.
  • Rights must never increase in a derived connection:
    • During Directory.Open, you may only request the same rights as what the directory connection already has, or a subset of those.
    • During Node.Reopen, similarly, you may only request the same or a subset of rights possessed by the original connection.
  • Exceeding those rights causes object_request to be closed with a ZX_ERR_ACCESS_DENIED epitaph.

The proper enforcement of the rights hierarchy is a powerful refinement over the existing access control facilities offered by directory sandboxing. The rights manipulation should be implemented mechanically without knowledge of any specific rights, and servers should propagate unknown bits members, to gracefully handle future rights extensions.

Rights Inheritance

Absent rights field means inheriting the same rights as the source.

  • During Node.Reopen, the new connection would have the same rights as the connection where the Reopen call is made.
  • During Directory.Open, the connection would have the same rights as the connection where the Open call is made.

Note: rights limits the set of operations allowed on the new connection, but does not guarantee their availability. For convenience, clients may query the ConnectionInfo.available_operations field on a new connection, which is the intersection of the rights and abilities and indicates the guaranteed set of available operations.

See Rights and Abilities.

ConnectorInfo

Defined in fuchsia.io2/connector.fidl

Auxiliary data for the connector representation of a node, used for protocol discovery and connection.

It supports connecting to arbitrary protocols exported by the filesystem server at a path, including ones that do not compose Node.

OrdinalNameTypeDescription

DebuglogInfo

Defined in fuchsia.io2/debuglog.fidl

The debuglog representation of a node. The selection of this variant in Representation implies that the connection speaks the Debuglog protocol.

OrdinalNameTypeDescription
1 debuglog handle<debuglog>

The backing debuglog kernel object.

DeviceInfo

Defined in fuchsia.io2/deprecated.fidl

The object may be cast to the shared interface of devices.

OrdinalNameTypeDescription
1 event handle<event>

An optional event which transmits information about a device's state.

The DeviceSignal values may be observed on this event.

TtyInfo

Defined in fuchsia.io2/deprecated.fidl

The object may be cast to a Tty interface.

OrdinalNameTypeDescription
1 event handle<event>

An optional event which transmits information about a device's state.

The DeviceSignal values may be observed on this event.

DirectoryEntry

Defined in fuchsia.io2/directory-entry.fidl

OrdinalNameTypeDescription
1 name Name

Name of the entry.

2 protocols NodeProtocolSet

Describes the kinds of representations supported by the entry.

3 abilities Abilities

Describes the kinds of operations supported by the entry.

DirectoryWatchOptions

Defined in fuchsia.io2/directory-watcher.fidl

OrdinalNameTypeDescription

DirectoryInfo

Defined in fuchsia.io2/directory.fidl

Auxiliary data for the directory representation of a node. The selection of this variant in Representation implies that the connection speaks the Directory protocol.

OrdinalNameTypeDescription

FileInfo

Defined in fuchsia.io2/file.fidl

Auxiliary data for the file representation of a node. The selection of this variant in Representation implies that the connection speaks the File protocol.

OrdinalNameTypeDescription
1 observer handle<event>

An optional event which transmits information about an object's readability or writability. This event relays information about the underlying object, not the capability granted to client: this event may be signalled "readable" on a connection that does not have the capability to read.

This event will be present if the following conditions are met:

  • The available_operations on the file connection is not empty.
  • The filesystem supports signalling readability/writability events.

The FileSignal values may be observed on this event.

2 is_append bool

Returns if the file is opened in append mode. In append mode, the seek offset is moved to the end before every write, the two steps performed in an atomic manner.

MemoryInfo

Defined in fuchsia.io2/memory.fidl

Auxiliary data for the memory object representation of a node. The node is a file which is represented as a VMO. The selection of this variant in Representation implies that the connection speaks the Memory protocol.

OrdinalNameTypeDescription
1 buffer fuchsia.mem/Range

Although a VMO is returned as a part of this structure, that VMO may back multiple files. To identify the logical portion of the VMO that represents the single file, offset and size are also supplied.

If the range covers the entire VMO (i.e. the offset is zero and the length matches the size of the VMO), then all clients must receive a VMO with the same koid. This can be a duplicate of the same underlying page-aligned VMO.

The rights on this VMO should correspond to the rights on the node connection.

NodeAttributes

Defined in fuchsia.io2/node-attributes.fidl

Objective information about a filesystem node. See Node.GetAttributes and Node.UpdateAttributes.

The attributes of a node should be stable, independent of the specific protocol used to access it.

If a particular attribute is not applicable or not supported, filesystems should leave the corresponding field absent.

OrdinalNameTypeDescription
1 protocols NodeProtocolSet

Describes the kinds of representations supported by the node. Note: This is not the result of the connection-time negotiation, which is conveyed via representation.

This attribute is read-only.

2 abilities Abilities

Describes the kinds of operations supported by the node. Note: This is distinct from the rights used at connection time.

This attribute is read-only.

3 content_size uint64

Node size, in bytes.

This attribute is read-only.

4 storage_size uint64

Space needed to store the node (possibly larger than size), in bytes.

This attribute is read-only.

5 link_count uint64

Number of hard links to the node. It must be at least one.

This attribute is read-only.

6 creation_time uint64

Time of creation in nanoseconds since the Unix epoch, UTC. It may be updated manually after creation.

7 modification_time uint64

Time of last modification in nanoseconds since the Unix epoch, UTC.

PipeInfo

Defined in fuchsia.io2/pipe.fidl

The pipe representation of a node. A pipe is a data streaming interface, commonly used for standard in/out. There is no universal requirement as to if it is uni- or bi-directional. The selection of this variant in Representation implies that the connection speaks the Pipe protocol.

OrdinalNameTypeDescription
1 socket handle<socket>

The backing socket transport for the pipe. The rights on this socket should correspond to the rights on the node connection.

PosixSocketInfo

Defined in fuchsia.io2/posix-socket.fidl

Auxiliary data for the POSIX socket representation of a node. The selection of this variant in Representation implies that the connection speaks the fuchsia.posix.socket/Control protocol.

OrdinalNameTypeDescription
1 socket handle<socket>

The backing transport for the socket. The rights on this socket should correspond to the rights on the node connection.

UNIONS

DirectoryIterator_GetNext_Result

generated

NameTypeDescription
response DirectoryIterator_GetNext_Response
err zx/status

generated

NameTypeDescription
response Directory_Unlink_Response
err zx/status

Directory_Rename_Result

generated

NameTypeDescription
response Directory_Rename_Response
err zx/status

generated

NameTypeDescription
response Directory_Link_Response
err zx/status

File_Seek_Result

generated

NameTypeDescription
response File_Seek_Response
err zx/status

File_Read_Result

generated

NameTypeDescription
response File_Read_Response
err zx/status

File_Write_Result

generated

NameTypeDescription
response File_Write_Response
err zx/status

File_ReadAt_Result

generated

NameTypeDescription
response File_ReadAt_Response
err zx/status

File_WriteAt_Result

generated

NameTypeDescription
response File_WriteAt_Response
err zx/status

File_Resize_Result

generated

NameTypeDescription
response File_Resize_Response
err zx/status

File_GetMemRange_Result

generated

NameTypeDescription
response File_GetMemRange_Response
err zx/status

Node_GetToken_Result

generated

NameTypeDescription
response Node_GetToken_Response
err zx/status

Node_GetAttributes_Result

generated

NameTypeDescription
response Node_GetAttributes_Response
err zx/status

Node_UpdateAttributes_Result

generated

NameTypeDescription
response Node_UpdateAttributes_Response
err zx/status

Node_Sync_Result

generated

NameTypeDescription
response Node_Sync_Response
err zx/status

XUNIONS

Representation

Defined in fuchsia.io2/connection-info.fidl

Describes how the connection should be handled, and provides auxiliary handles and information for the connection where applicable. Refer to Node.Describe and Node.OnConnectionInfo.

If handles are returned which offer alternative ways of access to the node, the rights on the handles should correspond to the rights on the connection.

If the client specified more than one protocol in protocols during Directory.Open or Node.Reopen, the Representation xunion carries additionally the result of the connection-time negotiation via its tag.

The elements have one-to-one correspondence with the members of NodeProtocolSet.

NameTypeDescription
connector ConnectorInfo

See NodeProtocolSet.CONNECTOR.

directory DirectoryInfo

See NodeProtocolSet.DIRECTORY.

file FileInfo

See NodeProtocolSet.FILE.

memory MemoryInfo

See NodeProtocolSet.MEMORY.

posix_socket PosixSocketInfo

See NodeProtocolSet.POSIX_SOCKET.

pipe PipeInfo

See NodeProtocolSet.PIPE.

debuglog DebuglogInfo

See NodeProtocolSet.DEBUGLOG.

device DeviceInfo
tty TtyInfo

DirectoryWatchedEvent

Defined in fuchsia.io2/directory-watcher.fidl

Events returned from DirectoryWatcher.GetNext.

NameTypeDescription
existing DirectoryEntry

Indicates a node already existed in the directory when watching started.

idle IdleEvent

Indicates that no more existing events will be sent.

added DirectoryEntry

Indicates a node has been created (either new or moved) into a directory.

removed Name

Indicates a node has been removed (either deleted or moved) from the directory.

BITS

ConnectionInfoQuery

Type: uint64

NameValueDescription
REPRESENTATION 1

Requests ConnectionInfo.representation.

RIGHTS 2

Requests ConnectionInfo.rights.

AVAILABLE_OPERATIONS 4

Requests ConnectionInfo.available_operations.

NodeProtocolSet

Type: uint64

NameValueDescription
CONNECTOR 1

The connector representation of a node. The connection will speak either Node, or some custom protocol, depending on the flags used during opening and reopening.

DIRECTORY 2

The directory representation of a node. The connection will speak the Directory protocol.

FILE 4

The file representation of a node. The connection will speak the File protocol.

MEMORY 8

The memory representation of a node. A memory object is a file whose contents are explicitly backed by some VMO. The connection will speak the Memory protocol, and Representation would contain a fuchsia.mem/Range object representing the contents of the file.

POSIX_SOCKET 16

The POSIX socket representation of a node. The connection will speak the fuchsia.posix.socket/Control protocol.

PIPE 32

The pipe representation of a node. The connection will speak the Pipe protocol.

DEBUGLOG 64

The debuglog representation of a node. The connection will speak the Debuglog protocol.

DEVICE 268435456
TTY 536870912

ConnectionFlags

Type: uint64

NameValueDescription
GET_CONNECTION_INFO 1

Requests that an Node.OnConnectionInfo event be sent as the first message on the protocol request. Requests all fields in the ConnectionInfo table. Doing so is more efficient than calling Node.Describe later on the connection.

CONNECT 2

Connects to the exposed protocol if the node is a Connector. It is an error to use this flag with other types of nodes.

If both GET_CONNECTION_INFO and CONNECT are specified, the channel will receive exactly one Node.OnConnectionInfo event, after which the protocol switches from Node to the intended protocol. Message sent by the client prior to receiving Node.OnConnectionInfo are queued and processed after the protocol switch.

CONNECT cannot be supplied together with APPEND. CONNECT cannot be supplied together with TRUNCATE.

Requires the Rights.CONNECT right on the connection.

APPEND 4

Opens the node in append mode, i.e. the connection should seek to the end of the node before every write.

If the node does not support appending, it should result in a ZX_ERR_NOT_SUPPORTED epitaph. Currently, only NodeProtocolSet.FILE connections may be configured for appending.

TRUNCATE 8

Truncates the object before usage, by setting its length to 0. Requires the Rights.WRITE_BYTES right on the connection.

If the node does not support truncating, it should result in a ZX_ERR_NOT_SUPPORTED epitaph.

DeviceSignal

Type: uint32

NameValueDescription
READABLE 16777216

Indicates the device is ready for reading.

WRITABLE 33554432

Indicates the device is ready for writing.

ERROR 67108864

Indicates the device has encountered an error state.

HANGUP 134217728

Indicates the device has hung up on the current connection.

OOB 268435456

Indicates an out-of-band state transition has occurred.

DirectoryWatchMask

Type: uint64

NameValueDescription
EXISTING 1

Requests transmission of existing events.

IDLE 2

Requests transmission of idle events.

ADDED 4

Requests transmission of added events.

REMOVED 8

Requests transmission of removed events.

VmoFlags

Type: uint64

NameValueDescription
READ 1

Requests that the VMO be readable.

WRITE 2

Requests that the VMO be writable.

EXECUTE 4
PRIVATE_CLONE 65536

Require a copy-on-write clone of the underlying VMO. The request should fail if the VMO cannot be cloned. May not be supplied with SHARED_BUFFER.

SHARED_BUFFER 131072

Require an exact (non-cloned) handle to the underlying VMO. All clients using this flag would get a VMO with the same koid. The request should fail if a handle to the exact VMO cannot be returned. May not be supplied with PRIVATE_CLONE.

FileSignal

Type: uint32

NameValueDescription
READABLE 16777216

Indicates the file is ready for reading.

WRITABLE 33554432

Indicates the file is ready for writing.

NodeAttributesQuery

Type: uint64

NameValueDescription
PROTOCOLS 1

Requests NodeAttributes.protocols.

ABILITIES 2

Requests NodeAttributes.abilities.

CONTENT_SIZE 4

Requests NodeAttributes.content_size.

STORAGE_SIZE 8

Requests NodeAttributes.storage_size.

LINK_COUNT 16

Requests NodeAttributes.link_count.

CREATION_TIME 32

Requests NodeAttributes.creation_time.

MODIFICATION_TIME 64

Requests NodeAttributes.modification_time.

Operations

Type: uint64

NameValueDescription
CONNECT 1

Connecting to a service.

READ_BYTES 2

Reading from the byte contents of a node.

WRITE_BYTES 4

Writing to the byte contents of a node.

EXECUTE 8

Execute the byte contents of a node.

GET_ATTRIBUTES 16

Reading the attributes of a node.

UPDATE_ATTRIBUTES 32

Updating the attributes of a node.

ENUMERATE 64

Reading the list of entries in a directory.

TRAVERSE 128

Opening a node from a directory.

When used in ConnectionOptions.rights, it must be specified together with Rights.ENUMERATE, since one can always probe the directory contents by opening children.

MODIFY_DIRECTORY 256

Modifying the list of entries in a directory. For example: node creation, renaming, linking, unlinking, etc.

When used in ConnectionOptions.rights, it must be specified together with Rights.ENUMERATE, since one can always probe the directory contents by triggering name conflicts during node creation.

ADMIN 72057594037927936

CONSTANTS

NameValueTypeDescription
MAX_DIRECTORY_BATCH_SIZE 8192 uint64

The maximum number of directory entires or watcher events returned in a batch by a hanging-get pattern.

MAX_TRANSFER_SIZE 8192 uint64

The maximum I/O size that is allowed for read/write operations using byte vectors.

MAX_NAME_LENGTH 255 uint64

The maximum length, in bytes, of a single filesystem component.

MAX_PATH_LENGTH 4095 uint64

The maximum length, in bytes, of a filesystem path.

TYPE ALIASES

NameValueDescription
Transfer vector[MAX_TRANSFER_SIZE]

The byte vector type used for read/write operations.

Name string[MAX_NAME_LENGTH]

The type for the name of a node, i.e. a single path component. E.g. foo

Invariants

A valid node name must meet the following criteria:

  • It cannot be longer than MAX_NAME_LENGTH.
  • It cannot be empty.
  • It cannot be ".." (dot-dot).
  • It cannot be "." (single dot).
  • It cannot contain "/".
  • It cannot contain embedded NUL.
Path string[MAX_PATH_LENGTH]

A path is a string of one or more components, separated by "/". E.g. foo/bar/baz

Invariants

A valid path must meet the following criteria:

  • It cannot be empty.
  • It cannot be longer than MAX_PATH_LENGTH.
  • It cannot have a leading "/".
  • It cannot have a trailing "/".
  • Each component must be a valid Name.

Paths should be transformed into their canonical forms at client side. For example, a client should convert "foo/bar/.././baz/" to "foo/baz" before using it as a path.

Token handle

The type to identify a connection to a node. It represents a capability: a reference to a node with associated rights.

Rights fuchsia.io2/Operations

Rights are properties specific to a connection. They limit which operations are allowed on a connection.

Invoking an operation without the corresponding right results in a ZX_ERR_ACCESS_DENIED error.

Right Aliases - Useful constants for commonly used collections of rights. Currently FIDL doesn't support expressions on assignment so these cannot be defined. They are left here as documentation.

"r*" a collection of rights to read from a directory. const Rights R_STAR_DIR = CONNECT | ENUMERATE | TRAVERSE | READ_BYTES | GET_ATTRIBUTES;

"w*" a collection of rights to write to a directory. const Rights W_STAR_DIR = CONNECT | ENUMERATE | TRAVERSE | MODIFY_DIRECTORY | WRITE_BYTES | UPDATE_ATTRIBUTES;

"x*" a collection of rights to execute from a directory. const Rights X_STAR_DIR = CONNECT | ENUMERATE | TRAVERSE | EXECUTE;

Abilities fuchsia.io2/Operations

Abilities are properties intrinsic to a node. They specify which operations are supported by it.

Invoking an operation without corresponding support in the node results in a ZX_ERR_NOT_SUPPORTED error. Note that if both the access denied and the not supported error conditions apply, the access denied case takes precedence.