fuchsia.io2

Library Overview

PROTOCOLS

Debuglog

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

Name	Type
`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

Name	Type

Describe

Returns extra connection information and auxiliary handles.

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

info see ConnectionInfo for details on the fields.

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

Name	Type
`query`	`ConnectionInfoQuery`

Response

Name	Type
`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

Name	Type
`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

Name	Type

Response

Name	Type
`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

Name	Type
`query`	`NodeAttributesQuery`

Response

Name	Type
`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

Name	Type
`attributes`	`NodeAttributes`

Response

Name	Type
`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

Name	Type

Response

Name	Type
`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

Name	Type

Response

Name	Type
`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

Name	Type

Response

Name	Type
`events`	`vector<DirectoryWatchedEvent>[8192]`

Name	Type
`path`	`Path`
`mode`	`OpenMode`
`options`	`ConnectionOptions`
`object_request`	`handle<channel>`

Name	Type
`path`	`Path`

Name	Type
`result`	`Directory_Unlink_Result`

Name	Type
`options`	`DirectoryEnumerateOptions`
`iterator`	`request<DirectoryIterator>`

Name	Type
`src`	`Name`
`dst_parent_token`	`Token`
`dst`	`Name`

Name	Type
`result`	`Directory_Rename_Result`

Name	Type
`src`	`Name`
`dst_parent_token`	`Token`
`dst`	`Name`

Name	Type
`result`	`Directory_Link_Result`

Name	Type
`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

Name	Type
`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

Name	Type

Describe

Returns extra connection information and auxiliary handles.

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

info see ConnectionInfo for details on the fields.

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

Name	Type
`query`	`ConnectionInfoQuery`

Response

Name	Type
`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

Name	Type
`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

Name	Type

Response

Name	Type
`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

Name	Type
`query`	`NodeAttributesQuery`

Response

Name	Type
`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

Name	Type
`attributes`	`NodeAttributes`

Response

Name	Type
`result`	`Node_UpdateAttributes_Result`

Sync

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

This method does not require any rights.

Request

Name	Type

Response

Name	Type
`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

Name	Type
`origin`	`SeekOrigin`
`offset`	`int64`

Response

Name	Type
`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

Name	Type
`count`	`uint64`

Response

Name	Type
`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

Name	Type
`data`	`Transfer`

Response

Name	Type
`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

Name	Type
`count`	`uint64`
`offset`	`uint64`

Response

Name	Type
`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

Name	Type
`data`	`Transfer`
`offset`	`uint64`

Response

Name	Type
`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

Name	Type
`length`	`uint64`

Response

Name	Type
`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.

response buffer the requested fuchsia.mem/Range.

error a zx.status value indicating the failure.

This method requires the following rights:

Rights.READ_BYTES if flags includes VmoFlags.READ.
Rights.WRITE_BYTES if flags includes VmoFlags.WRITE.
Rights.EXECUTE if flags includes VmoFlags.EXECUTE.

Request

Name	Type
`flags`	`VmoFlags`

Response

Name	Type
`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

Name	Type
`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

Name	Type

Describe

Returns extra connection information and auxiliary handles.

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

info see ConnectionInfo for details on the fields.

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

Name	Type
`query`	`ConnectionInfoQuery`

Response

Name	Type
`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

Name	Type
`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

Name	Type

Response

Name	Type
`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

Name	Type
`query`	`NodeAttributesQuery`

Response

Name	Type
`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

Name	Type
`attributes`	`NodeAttributes`

Response

Name	Type
`result`	`Node_UpdateAttributes_Result`

Sync

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

This method does not require any rights.

Request

Name	Type

Response

Name	Type
`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

Name	Type
`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

Name	Type

Describe

Returns extra connection information and auxiliary handles.

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

info see ConnectionInfo for details on the fields.

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

Name	Type
`query`	`ConnectionInfoQuery`

Response

Name	Type
`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

Name	Type
`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

Name	Type

Response

Name	Type
`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

Name	Type
`query`	`NodeAttributesQuery`

Response

Name	Type
`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

Name	Type
`attributes`	`NodeAttributes`

Response

Name	Type
`result`	`Node_UpdateAttributes_Result`

Sync

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

This method does not require any rights.

Request

Name	Type

Response

Name	Type
`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

Name	Type
`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

Name	Type

Describe

Returns extra connection information and auxiliary handles.

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

info see ConnectionInfo for details on the fields.

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

Name	Type
`query`	`ConnectionInfoQuery`

Response

Name	Type
`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

Name	Type
`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

Name	Type

Response

Name	Type
`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

Name	Type
`query`	`NodeAttributesQuery`

Response

Name	Type
`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

Name	Type
`attributes`	`NodeAttributes`

Response

Name	Type
`result`	`Node_UpdateAttributes_Result`

Sync

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

This method does not require any rights.

Request

Name	Type

Response

Name	Type
`result`	`Node_Sync_Result`

STRUCTS

DirectoryIterator_GetNext_Response

Defined in fuchsia.io2/directory-iterator.fidl

Name	Type	Description	Default
`entries`	`vector<DirectoryEntry>[8192]`		No default

IdleEvent

Defined in fuchsia.io2/directory-watcher.fidl

Name	Type	Description	Default

Directory_Unlink_Response

Defined in fuchsia.io2/directory.fidl

Name	Type	Description	Default

Directory_Rename_Response

Defined in fuchsia.io2/directory.fidl

Name	Type	Description	Default

Directory_Link_Response

Defined in fuchsia.io2/directory.fidl

Name	Type	Description	Default

File_Seek_Response

Defined in fuchsia.io2/file.fidl

Name	Type	Description	Default
`offset_from_start`	`uint64`		No default

File_Read_Response

Defined in fuchsia.io2/file.fidl

Name	Type	Description	Default
`data`	`Transfer`		No default

File_Write_Response

Defined in fuchsia.io2/file.fidl

Name	Type	Description	Default
`actual_count`	`uint64`		No default

File_ReadAt_Response

Defined in fuchsia.io2/file.fidl

Name	Type	Description	Default
`data`	`Transfer`		No default

File_WriteAt_Response

Defined in fuchsia.io2/file.fidl

Name	Type	Description	Default
`actual_count`	`uint64`		No default

File_Resize_Response

Defined in fuchsia.io2/file.fidl

Name	Type	Description	Default

File_GetMemRange_Response

Defined in fuchsia.io2/file.fidl

Name	Type	Description	Default
`buffer`	`fuchsia.mem/Range`		No default

Node_GetToken_Response

Defined in fuchsia.io2/node.fidl

Name	Type	Description	Default
`token`	`Token`		No default

Node_GetAttributes_Response

Defined in fuchsia.io2/node.fidl

Name	Type	Description	Default
`attributes`	`NodeAttributes`		No default

Node_UpdateAttributes_Response

Defined in fuchsia.io2/node.fidl

Name	Type	Description	Default

Node_Sync_Response

Defined in fuchsia.io2/node.fidl

Name	Type	Description	Default

ENUMS

OpenMode

Type: uint32

Defined in fuchsia.io2/directory.fidl

Options related to node creation during Directory.Open.

Name	Value	Description
`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.

Name	Value	Description
`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.

Ordinal	Name	Type	Description
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.

Ordinal Name Type Description

flags

ConnectionFlags

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

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.

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.

Ordinal	Name	Type	Description

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.

Ordinal	Name	Type	Description
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.

Ordinal Name Type Description

event

handle<eventpair>

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.

Ordinal Name Type Description

event

handle<eventpair>

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

Information about an immediate child node of a directory.

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

Ordinal	Name	Type	Description
1	`name`	`Name`	Name of the node. This field must be present.
2	`protocols`	`NodeProtocolSet`	Describes the kinds of representations supported by the node.
3	`abilities`	`Abilities`	Describes the kinds of operations supported by the node.
4	`id`	`Id`	An ID for the node. See Id. This `id` should be unique among all entries of a directory.

DirectoryEnumerateOptions

Defined in fuchsia.io2/directory-iterator.fidl

Options to pass to Directory.Enumerate.

Ordinal	Name	Type	Description

DirectoryWatchOptions

Defined in fuchsia.io2/directory-watcher.fidl

Ordinal	Name	Type	Description

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.

Ordinal	Name	Type	Description

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.

Ordinal Name Type Description

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.

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.

Ordinal Name Type Description

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.

Ordinal	Name	Type	Description
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.
8	`id`	`Id`	An ID for the node. See Id. This `id` should be unique among all entries of a directory. This attribute is read-only.

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.

Ordinal	Name	Type	Description
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.

Ordinal	Name	Type	Description
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

Defined in fuchsia.io2/directory-iterator.fidl

Name	Type	Description
`response`	`DirectoryIterator_GetNext_Response`
`err`	`zx/status`

Directory_Unlink_Result

Defined in fuchsia.io2/directory.fidl

Name	Type	Description
`response`	`Directory_Unlink_Response`
`err`	`zx/status`

Directory_Rename_Result

Defined in fuchsia.io2/directory.fidl

Name	Type	Description
`response`	`Directory_Rename_Response`
`err`	`zx/status`

Directory_Link_Result

Defined in fuchsia.io2/directory.fidl

Name	Type	Description
`response`	`Directory_Link_Response`
`err`	`zx/status`

File_Seek_Result

Defined in fuchsia.io2/file.fidl

Name	Type	Description
`response`	`File_Seek_Response`
`err`	`zx/status`

File_Read_Result

Defined in fuchsia.io2/file.fidl

Name	Type	Description
`response`	`File_Read_Response`
`err`	`zx/status`

File_Write_Result

Defined in fuchsia.io2/file.fidl

Name	Type	Description
`response`	`File_Write_Response`
`err`	`zx/status`

File_ReadAt_Result

Defined in fuchsia.io2/file.fidl

Name	Type	Description
`response`	`File_ReadAt_Response`
`err`	`zx/status`

File_WriteAt_Result

Defined in fuchsia.io2/file.fidl

Name	Type	Description
`response`	`File_WriteAt_Response`
`err`	`zx/status`

File_Resize_Result

Defined in fuchsia.io2/file.fidl

Name	Type	Description
`response`	`File_Resize_Response`
`err`	`zx/status`

File_GetMemRange_Result

Defined in fuchsia.io2/file.fidl

Name	Type	Description
`response`	`File_GetMemRange_Response`
`err`	`zx/status`

Node_GetToken_Result

Defined in fuchsia.io2/node.fidl

Name	Type	Description
`response`	`Node_GetToken_Response`
`err`	`zx/status`

Node_GetAttributes_Result

Defined in fuchsia.io2/node.fidl

Name	Type	Description
`response`	`Node_GetAttributes_Response`
`err`	`zx/status`

Node_UpdateAttributes_Result

Defined in fuchsia.io2/node.fidl

Name	Type	Description
`response`	`Node_UpdateAttributes_Response`
`err`	`zx/status`

Node_Sync_Result

Defined in fuchsia.io2/node.fidl

Name	Type	Description
`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.

Name	Type	Description
`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.

Name	Type	Description
`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

Name	Value	Description
REPRESENTATION	1	Requests ConnectionInfo.representation.
RIGHTS	2	Requests ConnectionInfo.rights.
AVAILABLE_OPERATIONS	4	Requests ConnectionInfo.available_operations.

NodeProtocolSet

Type: uint64

Name	Value	Description
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

Name	Value	Description
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

Name	Value	Description
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

Name	Value	Description
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

Name	Value	Description
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

Name	Value	Description
READABLE	16777216	Indicates the file is ready for reading.
WRITABLE	33554432	Indicates the file is ready for writing.

NodeAttributesQuery

Type: uint64

Name	Value	Description
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.
ID	128	Requests NodeAttributes.id.

Operations

Type: uint64

Name	Value	Description
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

Name	Value	Type	Description
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

Name	Value	Description
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.
Id	`uint64`	The type to identify a node, if the implementation supports some notion of unique node ID. Uniqueness Guarantees A client is usually presented with a directory tree that is the result of composing together multiple backing implementation instances. An ID would be unique within the corresponding instance only. Their boundaries are rather implicit on Fuchsia, as a result of transparently-forwarding directory proxies. It could be common for a client to observe identical `Id`s when traversing a directory tree, when it encounters nodes from different backing instances. Therefore, the ID is best used for debugging and informational purposes. If the implementation also supports fuchsia.fs/Query, the fuchsia.fs/FilesystemInfo.fs_id field may be used to disambiguate IDs from different backing instances.
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.