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

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. 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

NameType

Response

NameType
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

NameType

Response

NameType
info fuchsia.io/NodeInfo

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?

Sync

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

This method does not require any rights.

Request

NameType

Response

NameType
s zx/status

GetAttr

Acquires information about the node.

This method does not require any rights.

Request

NameType

Response

NameType
s zx/status
attributes fuchsia.io/NodeAttributes

SetAttr

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

This method requires following rights: OPEN_RIGHT_WRITABLE.

Request

NameType
flags uint32
attributes fuchsia.io/NodeAttributes

Response

NameType
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

NameType

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

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.

Request

NameType
count uint64

Response

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

Request

NameType
count uint64
offset uint64

Response

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

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.

Request

NameType
data vector<uint8>[8192]

Response

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

Request

NameType
data vector<uint8>[8192]
offset uint64

Response

NameType
s zx/status
actual uint64

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

Truncate

Shrinks the file size to 'length' bytes.

This method requires following rights: OPEN_RIGHT_WRITABLE.

Request

NameType
length uint64

Response

NameType
s zx/status

GetFlags

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

This method does not require any rights.

Request

NameType

Response

NameType
s zx/status
flags uint32

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

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

NameType
flags uint32

Response

NameType
s zx/status
buffer fuchsia.mem/Buffer?

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 handle<channel>

Response

NameType
s zx/status

ClrSetFeature

allowed on Client PTYs

Clear and/or Set PTY Features

Request

NameType
clr uint32
set uint32

Response

NameType
status zx/status
features uint32

GetWindowSize

Obtain the window size (in character cells)

Request

NameType

Response

NameType
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

NameType
client_pty_id uint32

Response

NameType
status zx/status

ReadEvents

Returns pending OOB events, simultaneously clearing them

Request

NameType

Response

NameType
status zx/status
events uint32

SetWindowSize

allowed on the Server PTY

Sets the window size

Request

NameType
size WindowSize

Response

NameType
status zx/status

STRUCTS

WindowSize

Defined in fuchsia.hardware.pty/pty.fidl

NameTypeDescriptionDefault
width uint32 No default
height uint32 No default

CONSTANTS

NameValueTypeDescription
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.

EVENT_HANGUP 1 uint32

The terminal has no active client.

EVENT_INTERRUPT 2 uint32

The terminal received a ^C control character.

EVENT_SUSPEND 4 uint32

The terminal received a ^Z control character.

EVENT_MASK 7 uint32

All events

SIGNAL_EVENT 33554432 uint32

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