PROTOCOLS

Directory

Defined in fuchsia.io/io.fidl

Directory defines a node which is capable of containing other Objects.

AddInotifyFilter

Adds a new inotify filter for an object relative to this directory object.

• 'filters` is a mask of different inotify events that need to be watched by the server for a specific file/directory.

• path may contain multiple segments, separated by "/" characters, and should never be empty; i.e., "" is an invalid path. Paths should not contain a leading "/".

+watch_descriptor is client assigned value to identify a filter. Server shouldn't trust the client-assigned watch_descriptor. They should just send it back to the client in the socket. This value is not used by server, but it is returned back as part of InotifyEvent, to help the client correlate filters with events on these filters.

• socket is shared between different filter objects i.e every new filter will have a different server end of the socket and there will be a single client end per inotify instance on inotify init.

Request

Name	Type
path	fuchsia.io2/Path
filters	fuchsia.io2/InotifyWatchMask
watch_descriptor	uint32
socket	handle<socket>

Response

Name	Type

Clone

Create another connection to the same remote object.

flags may be any of:

• OPEN_RIGHT_*
• OPEN_FLAG_APPEND
• OPEN_FLAG_NO_REMOTE
• OPEN_FLAG_DESCRIBE
• CLONE_FLAG_SAME_RIGHTS

All other flags are ignored.

The OPEN_RIGHT_* bits in flags request corresponding rights over the resulting cloned object. The cloned object must have rights less than or equal to the original object, otherwise returns ZX_ERR_ACCESS_DENIED. Alternatively, pass CLONE_FLAG_SAME_RIGHTS to inherit the rights on the source connection. It is invalid to pass any of the OPEN_RIGHT_* flags together with CLONE_FLAG_SAME_RIGHTS.

Request

Name	Type
flags	uint32
object	request<Node>

Close

Terminates connection with object.

This method does not require any rights.

Request

Name	Type

Response

Name	Type
s	zx/status

Describe

Returns extra information about the type of the object. If the Describe operation fails, the connection is closed.

This method does not require any rights.

Request

Name	Type

Response

Name	Type
info	NodeInfo

GetAttr

Acquires information about the node.

This method does not require any rights.

Request

Name	Type

Response

Name	Type
s	zx/status
attributes	NodeAttributes

GetToken

Acquires a token to a Directory which can be used to identify access to it at a later point in time.

This method requires following rights: OPEN_RIGHT_WRITABLE, otherwise returns ZX_ERR_BAD_HANDLE.

Request

Name	Type

Response

Name	Type
s	zx/status
token	handle<handle>?

Link

Creates a link to an object named src by the name dst, within a directory represented by token.

src must be a resolved object name. Including "/" in the string will return ZX_ERR_INVALID_ARGS.

dst must be a resolved object name. Including "/" in the string will return ZX_ERR_INVALID_ARGS.

This method requires following rights: OPEN_RIGHT_WRITABLE, otherwise returns ZX_ERR_BAD_HANDLE.

Request

Name	Type
src	string[4096]
dst_parent_token	handle<handle>
dst	string[4096]

Response

Name	Type
s	zx/status

NodeGetFlags

Acquires the Directory.Open rights and flags used to access this file.

This method does not require any rights. This method has the same functionality as GetFlags for File and is meant as an in-progress replacement.

Request

Name	Type

Response

Name	Type
s	zx/status
flags	uint32

NodeSetFlags

Changes the Directory.Open flags used to access the file. Supported flags which can be turned on / off:

• OPEN_FLAG_APPEND

This method does not require any rights. This method has the same functionality as SetFlags for File and is meant as an in-progress replacement.

Request

Name	Type
flags	uint32

Response

Name	Type
s	zx/status

OnOpen

An event produced eagerly by a FIDL server if requested by OPEN_FLAG_DESCRIBE.

Indicates the success or failure of the open operation, and optionally describes the object. If the status is ZX_OK, info contains descriptive information about the object (the same as would be returned by Describe).

Response

Name	Type
s	zx/status
info	NodeInfo?

Open

Opens a new object relative to this directory object.

path may contain multiple segments, separated by "/" characters, and should never be empty; i.e., "" is an invalid path. Paths should not contain a leading "/".

flags may be any of the OPEN_FLAG_* and OPEN_RIGHT_* values, bitwise ORed together. The OPEN_FLAG_DESCRIBE flag may cause an OnOpen event to be transmitted on the object handle, indicating the type of object opened.

If an unknown value is sent for either flags or mode, the connection should be closed.

OPEN_RIGHT_* flags provided in flags will restrict access rights on the object channel which will be connected to the opened entity.

Rights are never increased. When you open a nested entity within a directory, you may only request the same rights as what the directory connection already has, or a subset of those. Exceeding those rights causes an access denied error to be transmitted in the OnOpen event if applicable, and the object connection closed.

The caller must specify either one or more of the OPEN_RIGHT_* flags, or the OPEN_FLAG_NODE_REFERENCE flag.

Request

Name	Type
flags	uint32
mode	uint32
path	string[4096]
object	request<Node>

ReadDirents

Reads a collection of variably sized dirents into a buffer. The number of dirents 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 ReadDirents.

These dirents are of the form:

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

This method does not require any rights, since one could always probe for directory contents by triggering name conflicts during file creation.

Request

Name	Type
max_bytes	uint64

Response

Name	Type
s	zx/status
dirents	vector<uint8>[8192]

Rename

Renames an object named src to the name dst, in a directory represented by token.

src/dst must be resolved object names. Including "/" in any position other than the end of the string will return ZX_ERR_INVALID_ARGS. Returning "/" at the end of either string implies that it must be a directory, or else ZX_ERR_NOT_DIR should be returned.

This method requires following rights: OPEN_RIGHT_WRITABLE, otherwise returns ZX_ERR_BAD_HANDLE.

Request

Name	Type
src	string[4096]
dst_parent_token	handle<handle>
dst	string[4096]

Response

Name	Type
s	zx/status

Rewind

Resets the directory seek offset.

This method does not require any rights, similar to ReadDirents.

Request

Name	Type

Response

Name	Type
s	zx/status

SetAttr

Updates information about the node. flags may be any of NODE_ATTRIBUTE_FLAG_*.

This method requires following rights: OPEN_RIGHT_WRITABLE, otherwise returns ZX_ERR_BAD_HANDLE.

Request

Name	Type
flags	uint32
attributes	NodeAttributes

Response

Name	Type
s	zx/status

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
s	zx/status

Unlink

Detaches an object from this directory object.

The underlying object may or may not be deleted after this method completes: 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 removed.

If a directory is unlinked while it still has an open reference, it must become read-only, preventing new entries from being created until all references close and the directory is destroyed.

path identifies the file which should be detached. If path contains multiple segments, separated by "/" characters, then the directory is traversed, one segment at a time, relative to the originally accessed Directory.

Returns: ZX_ERR_ACCESS_DENIED if the connection (or the underlying filesystem) does not allow writable access. ZX_ERR_INVALID_ARGS if path contains ".." segments. ZX_ERR_NOT_EMPTY if path refers to a non-empty directory. ZX_ERR_UNAVAILABLE if path refers to a mount point, containing a remote channel. ZX_ERR_UNAVAILABLE if path is ".".

Other errors may be returned for filesystem-specific reasons.

This method requires following rights: OPEN_RIGHT_WRITABLE, otherwise returns ZX_ERR_BAD_HANDLE.

Request

Name	Type
path	string[4096]

Response

Name	Type
s	zx/status

Unlink2

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:

• Rights.ENUMERATE
• Rights.MODIFY_DIRECTORY

Request

Name	Type
path	fuchsia.io2/Path

Response

Name	Type
result	Directory_Unlink2_Result

Watch

Watches a directory, receiving events of added messages on the watcher request channel.

The watcher handle will send messages of the form:

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

Where names are NOT null-terminated.

This API is unstable; in the future, watcher will be a DirectoryWatcher client.

Mask specifies a bitmask of events to observe. Options must be zero; it is reserved.

This method does not require any rights, similar to ReadDirents.

Request

Name	Type
mask	uint32
options	uint32
watcher	handle<channel>

Response

Name	Type
s	zx/status

DirectoryAdmin

Defined in fuchsia.io/io.fidl

DirectoryAdmin defines a directory which is capable of handling administrator tasks within the filesystem.

AddInotifyFilter

Adds a new inotify filter for an object relative to this directory object.

• 'filters` is a mask of different inotify events that need to be watched by the server for a specific file/directory.

• path may contain multiple segments, separated by "/" characters, and should never be empty; i.e., "" is an invalid path. Paths should not contain a leading "/".

+watch_descriptor is client assigned value to identify a filter. Server shouldn't trust the client-assigned watch_descriptor. They should just send it back to the client in the socket. This value is not used by server, but it is returned back as part of InotifyEvent, to help the client correlate filters with events on these filters.

• socket is shared between different filter objects i.e every new filter will have a different server end of the socket and there will be a single client end per inotify instance on inotify init.

Request

Name	Type
path	fuchsia.io2/Path
filters	fuchsia.io2/InotifyWatchMask
watch_descriptor	uint32
socket	handle<socket>

Response

Name	Type

Clone

Create another connection to the same remote object.

flags may be any of:

• OPEN_RIGHT_*
• OPEN_FLAG_APPEND
• OPEN_FLAG_NO_REMOTE
• OPEN_FLAG_DESCRIBE
• CLONE_FLAG_SAME_RIGHTS

All other flags are ignored.

The OPEN_RIGHT_* bits in flags request corresponding rights over the resulting cloned object. The cloned object must have rights less than or equal to the original object, otherwise returns ZX_ERR_ACCESS_DENIED. Alternatively, pass CLONE_FLAG_SAME_RIGHTS to inherit the rights on the source connection. It is invalid to pass any of the OPEN_RIGHT_* flags together with CLONE_FLAG_SAME_RIGHTS.

Request

Name	Type
flags	uint32
object	request<Node>

Close

Terminates connection with object.

This method does not require any rights.

Request

Name	Type

Response

Name	Type
s	zx/status

Describe

Returns extra information about the type of the object. If the Describe operation fails, the connection is closed.

This method does not require any rights.

Request

Name	Type

Response

Name	Type
info	NodeInfo

GetAttr

Acquires information about the node.

This method does not require any rights.

Request

Name	Type

Response

Name	Type
s	zx/status
attributes	NodeAttributes

GetDevicePath

Acquire the path to the device backing this filesystem, if there is one.

Request

Name	Type

Response

Name	Type
s	zx/status
path	string[4096]?

GetToken

Acquires a token to a Directory which can be used to identify access to it at a later point in time.

This method requires following rights: OPEN_RIGHT_WRITABLE, otherwise returns ZX_ERR_BAD_HANDLE.

Request

Name	Type

Response

Name	Type
s	zx/status
token	handle<handle>?

Link

Creates a link to an object named src by the name dst, within a directory represented by token.

src must be a resolved object name. Including "/" in the string will return ZX_ERR_INVALID_ARGS.

dst must be a resolved object name. Including "/" in the string will return ZX_ERR_INVALID_ARGS.

This method requires following rights: OPEN_RIGHT_WRITABLE, otherwise returns ZX_ERR_BAD_HANDLE.

Request

Name	Type
src	string[4096]
dst_parent_token	handle<handle>
dst	string[4096]

Response

Name	Type
s	zx/status

Mount

Mount a channel representing a remote filesystem onto this directory. All future requests to this node will be forwarded to the remote filesystem. To re-open a node without forwarding to the remote target, the node should be opened with OPEN_FLAG_NO_REMOTE.

Request

Name	Type
remote	Directory

Response

Name	Type
s	zx/status

MountAndCreate

Atomically create a directory with a provided path, and mount the remote handle to the newly created directory.

Request

Name	Type
remote	Directory
name	string[255]
flags	uint32

Response

Name	Type
s	zx/status

NodeGetFlags

Acquires the Directory.Open rights and flags used to access this file.

This method does not require any rights. This method has the same functionality as GetFlags for File and is meant as an in-progress replacement.

Request

Name	Type

Response

Name	Type
s	zx/status
flags	uint32

NodeSetFlags

Changes the Directory.Open flags used to access the file. Supported flags which can be turned on / off:

• OPEN_FLAG_APPEND

This method does not require any rights. This method has the same functionality as SetFlags for File and is meant as an in-progress replacement.

Request

Name	Type
flags	uint32

Response

Name	Type
s	zx/status

OnOpen

An event produced eagerly by a FIDL server if requested by OPEN_FLAG_DESCRIBE.

Indicates the success or failure of the open operation, and optionally describes the object. If the status is ZX_OK, info contains descriptive information about the object (the same as would be returned by Describe).

Response

Name	Type
s	zx/status
info	NodeInfo?

Open

Opens a new object relative to this directory object.

path may contain multiple segments, separated by "/" characters, and should never be empty; i.e., "" is an invalid path. Paths should not contain a leading "/".

flags may be any of the OPEN_FLAG_* and OPEN_RIGHT_* values, bitwise ORed together. The OPEN_FLAG_DESCRIBE flag may cause an OnOpen event to be transmitted on the object handle, indicating the type of object opened.

If an unknown value is sent for either flags or mode, the connection should be closed.

OPEN_RIGHT_* flags provided in flags will restrict access rights on the object channel which will be connected to the opened entity.

Rights are never increased. When you open a nested entity within a directory, you may only request the same rights as what the directory connection already has, or a subset of those. Exceeding those rights causes an access denied error to be transmitted in the OnOpen event if applicable, and the object connection closed.

The caller must specify either one or more of the OPEN_RIGHT_* flags, or the OPEN_FLAG_NODE_REFERENCE flag.

Request

Name	Type
flags	uint32
mode	uint32
path	string[4096]
object	request<Node>

QueryFilesystem

Query the filesystem for filesystem-specific information.

Request

Name	Type

Response

Name	Type
s	zx/status
info	FilesystemInfo?

ReadDirents

Reads a collection of variably sized dirents into a buffer. The number of dirents 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 ReadDirents.

These dirents are of the form:

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

This method does not require any rights, since one could always probe for directory contents by triggering name conflicts during file creation.

Request

Name	Type
max_bytes	uint64

Response

Name	Type
s	zx/status
dirents	vector<uint8>[8192]

Rename

Renames an object named src to the name dst, in a directory represented by token.

src/dst must be resolved object names. Including "/" in any position other than the end of the string will return ZX_ERR_INVALID_ARGS. Returning "/" at the end of either string implies that it must be a directory, or else ZX_ERR_NOT_DIR should be returned.

This method requires following rights: OPEN_RIGHT_WRITABLE, otherwise returns ZX_ERR_BAD_HANDLE.

Request

Name	Type
src	string[4096]
dst_parent_token	handle<handle>
dst	string[4096]

Response

Name	Type
s	zx/status

Rewind

Resets the directory seek offset.

This method does not require any rights, similar to ReadDirents.

Request

Name	Type

Response

Name	Type
s	zx/status

SetAttr

Updates information about the node. flags may be any of NODE_ATTRIBUTE_FLAG_*.

This method requires following rights: OPEN_RIGHT_WRITABLE, otherwise returns ZX_ERR_BAD_HANDLE.

Request

Name	Type
flags	uint32
attributes	NodeAttributes

Response

Name	Type
s	zx/status

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
s	zx/status

Unlink

Detaches an object from this directory object.

The underlying object may or may not be deleted after this method completes: 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 removed.

If a directory is unlinked while it still has an open reference, it must become read-only, preventing new entries from being created until all references close and the directory is destroyed.

path identifies the file which should be detached. If path contains multiple segments, separated by "/" characters, then the directory is traversed, one segment at a time, relative to the originally accessed Directory.

Returns: ZX_ERR_ACCESS_DENIED if the connection (or the underlying filesystem) does not allow writable access. ZX_ERR_INVALID_ARGS if path contains ".." segments. ZX_ERR_NOT_EMPTY if path refers to a non-empty directory. ZX_ERR_UNAVAILABLE if path refers to a mount point, containing a remote channel. ZX_ERR_UNAVAILABLE if path is ".".

Other errors may be returned for filesystem-specific reasons.

This method requires following rights: OPEN_RIGHT_WRITABLE, otherwise returns ZX_ERR_BAD_HANDLE.

Request

Name	Type
path	string[4096]

Response

Name	Type
s	zx/status

Unlink2

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:

• Rights.ENUMERATE
• Rights.MODIFY_DIRECTORY

Request

Name	Type
path	fuchsia.io2/Path

Response

Name	Type
result	Directory_Unlink2_Result

Unmount

Unmount this filesystem. After this function returns successfully, all connections to the filesystem will be terminated.

Request

Name	Type

Response

Name	Type
s	zx/status

UnmountNode

Detach a node which was previously attached to this directory with Mount.

Request

Name	Type

Response

Name	Type
s	zx/status
remote	Directory?

Watch

Watches a directory, receiving events of added messages on the watcher request channel.

The watcher handle will send messages of the form:

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

Where names are NOT null-terminated.

This API is unstable; in the future, watcher will be a DirectoryWatcher client.

Mask specifies a bitmask of events to observe. Options must be zero; it is reserved.

This method does not require any rights, similar to ReadDirents.

Request

Name	Type
mask	uint32
options	uint32
watcher	handle<channel>

Response

Name	Type
s	zx/status

DirectoryWatcher

Defined in fuchsia.io/io.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.

OnEvent

Request

Name	Type
events	vector<uint8>[8192]

File

Defined in fuchsia.io/io.fidl

File defines the interface of a node which contains a flat layout of data.

AdvisoryLock

Acquires an advisory lock on the underlying file.

The lock lasts until either this connection is closed or this method is called with |AdvisoryLockType.UNLOCK| to release the lock explicitly.

Advisory locks are purely advisory. They do not prevent actual read or write operations from occurring on the file, either through this connection or through other connections.

This method requires the following rights:

• Rights.READ_BYTES if request.type is AdvisoryLockType.READ.
• Rights.WRITE_BYTES if request.type is AdvisoryLockType.WRITE.

Errors

• ZX_ERR_BAD_STATE The specified type of lock cannot be acquired. For example, another connection might hold a conflicting lock type.
• ZX_ERR_NOT_SUPPORTED This file does not support advisory locking.
• ZX_ERR_ACCESS_DENIED This connection does not have sufficient rights to acquire the given type of lock.

Request

Name	Type
request	fuchsia.io2/AdvisoryLockRequest

Response

Name	Type
result	fuchsia.io2/AdvisoryLocking_AdvisoryLock_Result

Clone

Create another connection to the same remote object.

flags may be any of:

• OPEN_RIGHT_*
• OPEN_FLAG_APPEND
• OPEN_FLAG_NO_REMOTE
• OPEN_FLAG_DESCRIBE
• CLONE_FLAG_SAME_RIGHTS

All other flags are ignored.

The OPEN_RIGHT_* bits in flags request corresponding rights over the resulting cloned object. The cloned object must have rights less than or equal to the original object, otherwise returns ZX_ERR_ACCESS_DENIED. Alternatively, pass CLONE_FLAG_SAME_RIGHTS to inherit the rights on the source connection. It is invalid to pass any of the OPEN_RIGHT_* flags together with CLONE_FLAG_SAME_RIGHTS.

Request

Name	Type
flags	uint32
object	request<Node>

Close

Terminates connection with object.

This method does not require any rights.

Request

Name	Type

Response

Name	Type
s	zx/status

Describe

Returns extra information about the type of the object. If the Describe operation fails, the connection is closed.

This method does not require any rights.

Request

Name	Type

Response

Name	Type
info	NodeInfo

GetAttr

Acquires information about the node.

This method does not require any rights.

Request

Name	Type

Response

Name	Type
s	zx/status
attributes	NodeAttributes

GetBuffer

Acquires a buffer representing this file, if there is one, with the requested access rights.

flags may be any of VMO_FLAG_*.

This method requires following rights:

• OPEN_RIGHT_WRITABLE if flags includes VMO_FLAG_WRITE.
• OPEN_RIGHT_READABLE if flags includes VMO_FLAG_READ or VMO_FLAG_EXEC.

Request

Name	Type
flags	uint32

Response

Name	Type
s	zx/status
buffer	fuchsia.mem/Buffer?

GetFlags

Acquires the Directory.Open rights and flags used to access this file.

This method does not require any rights.

Request

Name	Type

Response

Name	Type
s	zx/status
flags	uint32

NodeGetFlags

Acquires the Directory.Open rights and flags used to access this file.

This method does not require any rights. This method has the same functionality as GetFlags for File and is meant as an in-progress replacement.

Request

Name	Type

Response

Name	Type
s	zx/status
flags	uint32

NodeSetFlags

Changes the Directory.Open flags used to access the file. Supported flags which can be turned on / off:

• OPEN_FLAG_APPEND

This method does not require any rights. This method has the same functionality as SetFlags for File and is meant as an in-progress replacement.

Request

Name	Type
flags	uint32

Response

Name	Type
s	zx/status

OnOpen

An event produced eagerly by a FIDL server if requested by OPEN_FLAG_DESCRIBE.

Indicates the success or failure of the open operation, and optionally describes the object. If the status is ZX_OK, info contains descriptive information about the object (the same as would be returned by Describe).

Response

Name	Type
s	zx/status
info	NodeInfo?

Read

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

This method requires following rights: OPEN_RIGHT_READABLE, otherwise returns ZX_ERR_BAD_HANDLE.

Request

Name	Type
count	uint64

Response

Name	Type
s	zx/status
data	vector<uint8>[8192]

ReadAt

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

This method requires following rights: OPEN_RIGHT_READABLE, otherwise returns ZX_ERR_BAD_HANDLE.

Request

Name	Type
count	uint64
offset	uint64

Response

Name	Type
s	zx/status
data	vector<uint8>[8192]

Seek

Moves the offset at which the next invocation of Read() or Write() will occur.

This method does not require any rights.

Request

Name	Type
offset	int64
start	SeekOrigin

Response

Name	Type
s	zx/status
offset	uint64

SetAttr

Updates information about the node. flags may be any of NODE_ATTRIBUTE_FLAG_*.

This method requires following rights: OPEN_RIGHT_WRITABLE, otherwise returns ZX_ERR_BAD_HANDLE.

Request

Name	Type
flags	uint32
attributes	NodeAttributes

Response

Name	Type
s	zx/status

SetFlags

Changes the Directory.Open flags used to access the file. Supported flags which can be turned on / off:

• OPEN_FLAG_APPEND

This method does not require any rights.

Request

Name	Type
flags	uint32

Response

Name	Type
s	zx/status

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
s	zx/status

Truncate

Shrinks the file size to 'length' bytes.

This method requires following rights: OPEN_RIGHT_WRITABLE, otherwise returns ZX_ERR_BAD_HANDLE.

Request

Name	Type
length	uint64

Response

Name	Type
s	zx/status

Write

Writes data at the seek offset. The seek offset is moved forward by the number of bytes written.

This method requires following rights: OPEN_RIGHT_WRITABLE, otherwise returns ZX_ERR_BAD_HANDLE.

Request

Name	Type
data	vector<uint8>[8192]

Response

Name	Type
s	zx/status
actual	uint64

WriteAt

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

This method requires following rights: OPEN_RIGHT_WRITABLE, otherwise returns ZX_ERR_BAD_HANDLE.

Request

Name	Type
data	vector<uint8>[8192]
offset	uint64

Response

Name	Type
s	zx/status
actual	uint64

Node

Defined in fuchsia.io/io.fidl

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

Clone

Create another connection to the same remote object.

flags may be any of:

• OPEN_RIGHT_*
• OPEN_FLAG_APPEND
• OPEN_FLAG_NO_REMOTE
• OPEN_FLAG_DESCRIBE
• CLONE_FLAG_SAME_RIGHTS

All other flags are ignored.

The OPEN_RIGHT_* bits in flags request corresponding rights over the resulting cloned object. The cloned object must have rights less than or equal to the original object, otherwise returns ZX_ERR_ACCESS_DENIED. Alternatively, pass CLONE_FLAG_SAME_RIGHTS to inherit the rights on the source connection. It is invalid to pass any of the OPEN_RIGHT_* flags together with CLONE_FLAG_SAME_RIGHTS.

Request

Name	Type
flags	uint32
object	request<Node>

Close

Terminates connection with object.

This method does not require any rights.

Request

Name	Type

Response

Name	Type
s	zx/status

Describe

Returns extra information about the type of the object. If the Describe operation fails, the connection is closed.

This method does not require any rights.

Request

Name	Type

Response

Name	Type
info	NodeInfo

GetAttr

Acquires information about the node.

This method does not require any rights.

Request

Name	Type

Response

Name	Type
s	zx/status
attributes	NodeAttributes

NodeGetFlags

Acquires the Directory.Open rights and flags used to access this file.

This method does not require any rights. This method has the same functionality as GetFlags for File and is meant as an in-progress replacement.

Request

Name	Type

Response

Name	Type
s	zx/status
flags	uint32

NodeSetFlags

Changes the Directory.Open flags used to access the file. Supported flags which can be turned on / off:

• OPEN_FLAG_APPEND

This method does not require any rights. This method has the same functionality as SetFlags for File and is meant as an in-progress replacement.

Request

Name	Type
flags	uint32

Response

Name	Type
s	zx/status

OnOpen

An event produced eagerly by a FIDL server if requested by OPEN_FLAG_DESCRIBE.

Indicates the success or failure of the open operation, and optionally describes the object. If the status is ZX_OK, info contains descriptive information about the object (the same as would be returned by Describe).

Response

Name	Type
s	zx/status
info	NodeInfo?

SetAttr

Updates information about the node. flags may be any of NODE_ATTRIBUTE_FLAG_*.

This method requires following rights: OPEN_RIGHT_WRITABLE, otherwise returns ZX_ERR_BAD_HANDLE.

Request

Name	Type
flags	uint32
attributes	NodeAttributes

Response

Name	Type
s	zx/status

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
s	zx/status

STRUCTS

DatagramSocket

Defined in fuchsia.io/io.fidl

The object may be cast to interface fuchsia.posix.socket.DatagramSocket.

Name	Type	Description	Default
event	handle<eventpair>	See fuchsia.posix.socket.DatagramSocket for details.	No default

Device

Defined in fuchsia.io/io.fidl

The object may be cast to interface 'Device'.

Name	Type	Description	Default
event	handle<eventpair>?	An optional event which transmits information about a device's state. The "DEVICE_SIGNAL_" values may be observed on this event.	No default

DirectoryObject

Defined in fuchsia.io/io.fidl

The object may be cast to interface 'Directory'.

Name	Type	Description	Default

Directory_Unlink2_Response

Defined in fuchsia.io/io.fidl

Name	Type	Description	Default

FileObject

Defined in fuchsia.io/io.fidl

The object may be cast to interface 'File'.

Name	Type	Description	Default
event	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. The "FILE_SIGNAL_" values may be observed on this event.	No default
stream	handle<stream>?	A placeholder for future stream support. Currently, servers are required not to send a handle in this field.	No default

FilesystemInfo

Defined in fuchsia.io/io.fidl

Name	Type	Description	Default
total_bytes	uint64	The number of data bytes which may be stored in a filesystem.	No default
used_bytes	uint64	The number of data bytes which are in use by the filesystem.	No default
total_nodes	uint64	The number of nodes which may be stored in the filesystem.	No default
used_nodes	uint64	The number of nodes used by the filesystem.	No default
free_shared_pool_bytes	uint64	The amount of space which may be allocated from the underlying volume manager. If unsupported, this will be zero.	No default
fs_id	uint64	A unique identifier for this filesystem instance. Will not be preserved across reboots.	No default
block_size	uint32	The size of a single filesystem block.	No default
max_filename_size	uint32	The maximum length of a filesystem name.	No default
fs_type	uint32	A unique identifier for the type of the underlying filesystem.	No default
padding	uint32		No default
name	int8[32]		No default

NodeAttributes

Defined in fuchsia.io/io.fidl

NodeAttributes defines generic information about a filesystem node.

Name	Type	Description	Default
mode	uint32	Protection bits and node type information describe in 'mode'.	No default
id	uint64	A filesystem-unique ID.	No default
content_size	uint64	Node size, in bytes.	No default
storage_size	uint64	Space needed to store node (possibly larger than size), in bytes.	No default
link_count	uint64	Hard link count.	No default
creation_time	uint64	Time of creation (may be updated manually after creation) in ns since Unix epoch, UTC.	No default
modification_time	uint64	Time of last modification in ns since Unix epoch, UTC.	No default

Pipe

Defined in fuchsia.io/io.fidl

The object is accompanied by a pipe.

Name	Type	Description	Default
socket	handle<socket>		No default

Service

Defined in fuchsia.io/io.fidl

The default protocol, interface information must be acquired some other way.

Name	Type	Description	Default

StreamSocket

Defined in fuchsia.io/io.fidl

The object may be cast to interface fuchsia.posix.socket.StreamSocket.

Name	Type	Description	Default
socket	handle<socket>		No default

Tty

Defined in fuchsia.io/io.fidl

The object may be cast to interface 'Tty'

Name	Type	Description	Default
event	handle<eventpair>?		No default

Vmofile

Defined in fuchsia.io/io.fidl

The object is a file which is represented as an immutable VMO. Although a VMO is returned as a part of this structure, this underlying object may represent multiple Vmofiles. To identify the logical portion of the VMO that represents the single file, an offset and length parameter are also supplied.

Name	Type	Description	Default
vmo	handle<vmo>	The VMO which backs this file.	No default
offset	uint64	The index into vmo which represents the first byte of the file.	No default
length	uint64	The number of bytes, starting at offset, which may be used to represent this file.	No default

WatchedEvent

Defined in fuchsia.io/io.fidl

WatchedEvent describes events returned from a DirectoryWatcher.

Name	Type	Description	Default
event	uint8		No default
len	uint8		No default
name	vector<uint8>[255]		No default

ENUMS

SeekOrigin

Type: uint32

Defined in fuchsia.io/io.fidl

Update the Seek offset.

Name	Value	Description
START	0	Seek from the start of the file.
CURRENT	1	Seek from the current position in the file.
END	2	Seek from the end of the file.

UNIONS

Directory_Unlink2_Result

Defined in fuchsia.io/io.fidl

Name	Type	Description
response	Directory_Unlink2_Response
err	zx/status

NodeInfo

Defined in fuchsia.io/io.fidl

Describes how the connection to an should be handled, as well as how to interpret the optional handle.

Refer to Node.Describe() and Node.OnOpen() for usage.

Name	Type	Description
service	Service
file	FileObject
directory	DirectoryObject
pipe	Pipe
vmofile	Vmofile
device	Device
tty	Tty
datagram_socket	DatagramSocket
stream_socket	StreamSocket

CONSTANTS

Name	Value	Type	Description
CLONE_FLAG_SAME_RIGHTS	67108864	uint32	When used during clone, the new connection inherits the rights on the source connection, regardless if it is a file or directory. Otherwise, clone attempts to use the requested rights. It is invalid to pass any of the OPEN_RIGHT_* flags together with CLONE_FLAG_SAME_RIGHTS.
DEVICE_SIGNAL_ERROR	134217728	uint32	Indicates the device has encountered an error state.
DEVICE_SIGNAL_HANGUP	268435456	uint32	Indicates the device has hung up on the current connection.
DEVICE_SIGNAL_OOB	33554432	uint32	Indicates an out-of-band state transition has occurred.
DEVICE_SIGNAL_READABLE	16777216	uint32	Indicates the device is ready for reading.
DEVICE_SIGNAL_WRITABLE	67108864	uint32	Indicates the device is ready for writing.
DIRENT_TYPE_BLOCK_DEVICE	6	uint8	A dirent representing a block device object.
DIRENT_TYPE_DIRECTORY	4	uint8	A dirent representing a directory object.
DIRENT_TYPE_FILE	8	uint8	A dirent representing a file object.
DIRENT_TYPE_SERVICE	16	uint8	A dirent representing a service object.
DIRENT_TYPE_SOCKET	12	uint8	A dirent representing a socket object.
DIRENT_TYPE_UNKNOWN	0	uint8	A dirent with an unknown type.
FILE_SIGNAL_READABLE	16777216	uint32	Indicates the file is ready for reading.
FILE_SIGNAL_WRITABLE	33554432	uint32	Indicates the file is ready for writing.
INO_UNKNOWN	18446744073709551615	uint64	Nodes which do not have ino values should return this value from Readdir and GetAttr.
MAX_BUF	8192	uint64	The maximal buffer size which can be transmitted for buffered operations. This capacity is currently set somewhat arbitrarily.
MAX_FILENAME	255	uint64	The maximum length, in bytes, of a single filesystem component.
MAX_FS_NAME_BUFFER	32	uint64
MAX_PATH	4096	uint64	The maximum length, in bytes, of a filesystem string.
MODE_PROTECTION_MASK	4095	uint32	Bits reserved for posix protections. Native fuchsia filesystems are not required to set bits contained within MODE_PROTECTION_MASK, but filesystems that wish to do so may refer to sys/stat.h for their definitions.
MODE_TYPE_BLOCK_DEVICE	24576	uint32
MODE_TYPE_DIRECTORY	16384	uint32
MODE_TYPE_FILE	32768	uint32
MODE_TYPE_MASK	1044480	uint32	Bits indicating node type. The canonical mechanism to check for a node type is to take 'mode', bitwise AND it with the MODE_TYPE_MASK, and check exact equality against a mode type.
MODE_TYPE_SERVICE	65536	uint32
MODE_TYPE_SOCKET	49152	uint32
MOUNT_CREATE_FLAG_REPLACE	1	uint32
NODE_ATTRIBUTE_FLAG_CREATION_TIME	1	uint32	The fields of 'attributes' which are used to update the Node are indicated by the 'flags' argument.
NODE_ATTRIBUTE_FLAG_MODIFICATION_TIME	2	uint32
OPEN_FLAGS_ALLOWED_WITH_NODE_REFERENCE	46661632	uint32	Binary OR of OPEN_FLAG_DIRECTORY, OPEN_FLAG_NOT_DIRECTORY, OPEN_FLAG_DESCRIBE, and OPEN_FLAG_NODE_REFERENCE. Flags used when opening a node reference must fall within this mask.
OPEN_FLAG_APPEND	1048576	uint32	Seek to the end of the object before all writes.
OPEN_FLAG_CREATE	65536	uint32	Create the object if it doesn't exist.
OPEN_FLAG_CREATE_IF_ABSENT	131072	uint32	(with Create) Fail if the object already exists.
OPEN_FLAG_DESCRIBE	8388608	uint32	Requests that an "OnOpen" event is sent to the interface request. The event will contain a non-null NodeInfo if the open/clone is successful.
OPEN_FLAG_DIRECTORY	524288	uint32	Assert that the object to be opened is a directory. Return an error if the target object is not a directory.
OPEN_FLAG_NODE_REFERENCE	4194304	uint32	Open a reference to the object, not the object itself. It is ONLY valid to pass the following flags together with OPEN_FLAG_NODE_REFERENCE: OPEN_FLAG_DIRECTORY OPEN_FLAG_NOT_DIRECTORY OPEN_FLAG_DESCRIBE otherwise an error is returned. If an object is opened or cloned using this method, the resulting connection does not carry any permission flags. The resulting node allows a limited set of operations: GetAttr, Clone, Close, Describe, and, if the node is a file, these extra operations: GetFlags, SetFlags.
OPEN_FLAG_NOT_DIRECTORY	33554432	uint32	Assert that the object to be opened is not a directory. Return an error if the target object is a directory.
OPEN_FLAG_NO_REMOTE	2097152	uint32	If the object is a mount point, open the local directory.
OPEN_FLAG_POSIX	16777216	uint32	Specify this flag to request POSIX-compatibility. Currently, it affects permission handling. During Open: If the target path is a directory, the rights on the new connection expand to include OPEN_RIGHT_WRITABLE if and only if the current connection and all intermediate mount points are writable, and to include OPEN_RIGHT_EXECUTABLE if and only if the current connection and all intermediate mount points are executable. Otherwise, this flag is ignored. It is an access denied error to request more rights than those on the current connection, or any intermediate mount points. If the posix compatibility flag is not specified, opening always uses the requested rights, failing the operation with access denied error if requested rights exceeds the rights attached to the current connection. If the requesting connection is read-only and the requested rights are read-only, the flag may be ignored by the server, and is not forwarded downstream. This is an implementation detail, necessary to enforce hierarchical permissions across mount points, and should have no effect on the expected behavior for clients.
OPEN_FLAG_TRUNCATE	262144	uint32	Truncate the object before usage.
OPEN_RIGHT_ADMIN	4	uint32	Connection can mount/umount filesystem.
OPEN_RIGHT_EXECUTABLE	8	uint32	Connection can map target object executable.
OPEN_RIGHT_READABLE	1	uint32	Can read from target object.
OPEN_RIGHT_WRITABLE	2	uint32	Can write to target object.
VMO_FLAG_EXACT	131072	uint32	Require an exact (non-cloned) handle to the underlying VMO. The request should fail if a handle to the exact VMO is not returned. May not be supplied with VMO_FLAG_PRIVATE.
VMO_FLAG_EXEC	4	uint32	Requests that the VMO be executable.
VMO_FLAG_PRIVATE	65536	uint32	Require a copy-on-write clone of the underlying VMO. The request should fail if the VMO is not cloned. May not be supplied with fuchsia_io_VMO_FLAG_EXACT.
VMO_FLAG_READ	1	uint32	Requests that the VMO be readable.
VMO_FLAG_WRITE	2	uint32	Requests that the VMO be writable.
WATCH_EVENT_ADDED	1	uint8	Indicates a node has been created (either new or moved) into a directory.
WATCH_EVENT_DELETED	0	uint8	Indicates the directory being watched has been deleted.
WATCH_EVENT_EXISTING	3	uint8	Identifies a node already existed in the directory when watching started.
WATCH_EVENT_IDLE	4	uint8	Identifies that no more WATCH_EVENT_EXISTING events will be sent.
WATCH_EVENT_REMOVED	2	uint8	Identifies a node has been removed (either deleted or moved) from the directory.
WATCH_MASK_ADDED	2	uint32	Used by Directory.Watch. Requests transmission of WATCH_EVENT_ADDED.
WATCH_MASK_ALL	31	uint32	Used by Directory.Watch. Requests transmission of all watcher events.
WATCH_MASK_DELETED	1	uint32	Used by Directory.Watch. Requests transmission of WATCH_EVENT_DELETED.
WATCH_MASK_EXISTING	8	uint32	Used by Directory.Watch. Requests transmission of WATCH_EVENT_EXISTING.
WATCH_MASK_IDLE	16	uint32	Used by Directory.Watch. Requests transmission of WATCH_EVENT_IDLE.
WATCH_MASK_REMOVED	4	uint32	Used by Directory.Watch. Requests transmission of WATCH_EVENT_REMOVED.