Google is committed to advancing racial equity for Black communities. See how.

fuchsia.hardware.pty

A PTY (pseudoterminal) emulates terminal devices, with a "server" side (which represents the keyboard+monitor side of the terminal and is obtained by opening /dev/misc/ptmx) and a number of "client" sides which are obtained by calling OpenClient.

Client PTYs are identified by the id used in the OpenClient call. The first Client PTY must be 0, and it is the only Client PTY that is allowed to create additional Client PTYs, receive Events, etc. It is the Controlling PTY.

PROTOCOLS

Device

Defined in fuchsia.hardware.pty/pty.fidl

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:

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

NameType
request fuchsia.io2/AdvisoryLockRequest

Response

NameType
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

NameType
flags uint32
object request<fuchsia.io/Node>

Close

Terminates connection with object.

This method does not require any rights.

Request

<EMPTY>

Response

NameType
s zx/status

Close2

Terminates connection with object.

This method does not require any rights.

Request

<EMPTY>

Response

NameType
result fuchsia.io/Node_Close2_Result

ClrSetFeature

allowed on Client PTYs

Clear and/or Set PTY Features

Request

NameType
clr uint32
set uint32

Response

NameType
status zx/status
features uint32

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

<EMPTY>

Response

NameType
info fuchsia.io/NodeInfo

Describe2

Returns extra connection information and auxiliary handles.

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

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

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

This method does not require any rights.

Request

NameType
query fuchsia.io/ConnectionInfoQuery

Response

NameType
info fuchsia.io/ConnectionInfo

GetAttr

Acquires information about the node.

This method does not require any rights.

Request

<EMPTY>

Response

NameType
s zx/status
attributes fuchsia.io/NodeAttributes

GetAttributes

Acquires information about the node.

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

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

This method requires the Rights.GET_ATTRIBUTES right.

Request

NameType
query fuchsia.io/NodeAttributesQuery

Response

NameType
result fuchsia.io/Node_GetAttributes_Result

GetBackingMemory

Acquires a zx.handle:VMO representing this file, if there is one, with the requested access rights.

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

This method requires the following rights:

Request

NameType
flags fuchsia.io/VmoFlags

Response

NameType
result fuchsia.io/File_GetBackingMemory_Result

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.
  • OPEN_RIGHT_EXECUTABLE if flags includes VMO_FLAG_EXEC.

Request

NameType
flags uint32

Response

NameType
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

<EMPTY>

Response

NameType
s zx/status
flags uint32

GetWindowSize

Obtain the window size (in character cells)

Request

<EMPTY>

Response

NameType
status zx/status
size WindowSize

IoToIo2Placeholder

This message should never be sent or received.

This declaration exists to let keep the Rust bindings compiling as we add and remove transitional elements from the fuchsia.io protocols. Without this declaration, the users of the Rust bindings fail to compile when there aren't any transitional protocol elements.

DEPRECATED

Request

<EMPTY>

MakeActive

allowed on the Controlling PTY

Select which Client PTY receives input. Reads will simply block on non-active PTYs.

Request

NameType
client_pty_id uint32

Response

NameType
status 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

<EMPTY>

Response

NameType
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

NameType
flags uint32

Response

NameType
s zx/status

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.

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

Response

NameType
info fuchsia.io/ConnectionInfo

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

NameType
s zx/status
info fuchsia.io/NodeInfo?

OpenClient

Open a client PTY device with a unique id. client should be a handle to one endpoint of a channel that (on success) will become an open connection to the newly created device. On failure, the channel will be closed. Closing the channel will close the connection and release the device. If the provided id is 0, then the new client is a controlling client and has the capability to open additional clients. If the current device is not a controlling client, ZX_ERR_ACCESS_DENIED will be returned. If id is not unique, ZX_ERR_INVALID_ARGS will be returned. Otherwise the status code from device_add is passed on.

Request

NameType
id uint32
client request<Device>

Response

NameType
s zx/status

Read

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

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

Returns ZX_ERR_OUT_OF_RANGE if count is greater than MAX_BUF.

Request

NameType
count uint64

Response

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

Read2

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.

Returns ZX_ERR_OUT_OF_RANGE if count is greater than MAX_TRANSFER_SIZE.

Request

NameType
count uint64

Response

NameType
result fuchsia.io/File_Read2_Result

ReadAt

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

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

Returns ZX_ERR_OUT_OF_RANGE if count is greater than MAX_BUF.

Request

NameType
count uint64
offset uint64

Response

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

ReadAt2

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.

Returns ZX_ERR_OUT_OF_RANGE if count is greater than MAX_TRANSFER_SIZE.

Request

NameType
count uint64
offset uint64

Response

NameType
result fuchsia.io/File_ReadAt2_Result

ReadEvents

Returns pending OOB events, simultaneously clearing them

Request

<EMPTY>

Response

NameType
status zx/status
events uint32

Reopen

Creates another connection to the same node.

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

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

Request

NameType
options fuchsia.io/ConnectionOptions
object_request handle<channel>

Resize

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

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

This method requires the Rights.WRITE_BYTES right.

Request

NameType
length uint64

Response

NameType
result fuchsia.io/File_Resize_Result

Seek

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

This method does not require any rights.

Request

NameType
offset int64
start fuchsia.io/SeekOrigin

Response

NameType
s zx/status
offset uint64

Seek2

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

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

This method does not require any rights.

Request

NameType
origin fuchsia.io/SeekOrigin
offset int64

Response

NameType
result fuchsia.io/File_Seek2_Result

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

NameType
flags uint32
attributes fuchsia.io/NodeAttributes

Response

NameType
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

NameType
flags uint32

Response

NameType
s zx/status

SetWindowSize

allowed on the Server PTY

Sets the window size

Request

NameType
size WindowSize

Response

NameType
status zx/status

Sync

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

This method does not require any rights.

Request

<EMPTY>

Response

NameType
s zx/status

Sync2

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

<EMPTY>

Response

NameType
result fuchsia.io/Node_Sync2_Result

Truncate

Shrinks the file size to 'length' bytes.

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

Request

NameType
length uint64

Response

NameType
s zx/status

UpdateAttributes

Updates information about the node.

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

This method requires the Rights.UPDATE_ATTRIBUTES right.

Request

NameType
attributes fuchsia.io/NodeAttributes2

Response

NameType
result fuchsia.io/Node_UpdateAttributes_Result

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

NameType
data vector<uint8>[8192]

Response

NameType
s zx/status
actual uint64

Write2

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

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

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

Invariants

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

This method requires the Rights.WRITE_BYTES right.

Request

NameType
data fuchsia.io/Transfer

Response

NameType
result fuchsia.io/File_Write2_Result

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

NameType
data vector<uint8>[8192]
offset uint64

Response

NameType
s zx/status
actual uint64

WriteAt2

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

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

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

Invariants

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

This method requires the Rights.WRITE_BYTES right.

Request

NameType
data fuchsia.io/Transfer
offset uint64

Response

NameType
result fuchsia.io/File_WriteAt2_Result

STRUCTS

WindowSize

Defined in fuchsia.hardware.pty/pty.fidl

FieldTypeDescriptionDefault
width uint32 No default
height uint32 No default

CONSTANTS

NameValueTypeDescription
EVENT_HANGUP 1 uint32

The terminal has no active client.

EVENT_INTERRUPT 2 uint32

The terminal received a ^C control character.

EVENT_MASK 7 uint32

All events

EVENT_SUSPEND 4 uint32

The terminal received a ^Z control character.

FEATURE_RAW 1 uint32

When Feature Raw is enabled, OOB Events like ^c, ^z, etc are not generated. Instead the character is read from the read() input path.

SIGNAL_EVENT 33554432 uint32

When an event is pending, this signal is asserted on the Controlling PTY.