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

Clone2

Request

Name	Type
request	server_end<fuchsia.unknown/Cloneable>

Close

Terminates the connection.

After calling Close, the client must not send any other requests.

Servers, after sending the status response, should close the connection regardless of status and without sending an epitaph.

Closing the client end of the channel should be semantically equivalent to calling Close without knowing when the close has completed or its status.

Request

<EMPTY>

Response

Name	Type
payload	fuchsia.unknown/Closeable_Close_Result

ClrSetFeature

allowed on Client PTYs

Clear and/or Set PTY Features

Request

Name	Type
clr	uint32
set	uint32

Response

Name	Type
status	zx/Status
features	uint32

Describe

Request

<EMPTY>

Response

Name	Type
payload	DeviceDescribeResponse

GetWindowSize

Obtain the window size (in character cells)

Request

<EMPTY>

Response

Name	Type
status	zx/Status
size	WindowSize

MakeActive

allowed on the Controlling PTY

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

Request

Name	Type
client_pty_id	uint32

Response

Name	Type
status	zx/Status

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

Name	Type
id	uint32
client	server_end<Device>

Response

Name	Type
s	zx/Status

Query

Request

<EMPTY>

Response

Name	Type
protocol	vector<uint8>

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.

Returns ZX_ERR_OUT_OF_RANGE if count is greater than MAX_TRANSFER_SIZE.

Request

Name	Type
count	uint64

Response

Name	Type
payload	fuchsia.io/Readable_Read_Result

ReadEvents

Returns pending OOB events, simultaneously clearing them

Request

<EMPTY>

Response

Name	Type
status	zx/Status
events	uint32

SetWindowSize

allowed on the Server PTY

Sets the window size

Request

Name	Type
size	WindowSize

Response

Name	Type
status	zx/Status

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 no bytes could be written, an error is returned.
• If data.length is zero, the server should perform all the checks ensuring write access without mutating the file and return a successful write of zero bytes. The seek offset is still updated if in append mode.

This method requires the Rights.WRITE_BYTES right.

Request

Name	Type
data	fuchsia.io/Transfer

Response

Name	Type
payload	fuchsia.io/Writable_Write_Result

STRUCTS

WindowSize

Defined in fuchsia.hardware.pty/pty.fidl

Field	Type	Description	Default
width	uint32		No default
height	uint32		No default

TABLES

DeviceDescribeResponse resource

Defined in fuchsia.hardware.pty/pty.fidl

Ordinal	Field	Type	Description
1	event	handle<eventpair>	An optional event which transmits information about a device's state. The DeviceSignal values may be observed on this event.

CONSTANTS

Name	Value	Type	Description
DEVICE_PROTOCOL_NAME	fuchsia.hardware.pty/Device	String
EVENT_HANGUP	1	uint32	The terminal has no active client.
EVENT_INTERRUPT	2	uint32	The terminal received a ^C control character.
EVENT_MASK	15	uint32	All events
EVENT_SUSPEND	4	uint32	The terminal received a ^Z control character.
EVENT_WINDOW_SIZE	8	uint32	The terminal window has resized.
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.