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
| Name | Type |
|---|---|
flags |
uint32
|
object |
request<fuchsia.io/Node>
|
Close
Terminates connection with object.
This method does not require any rights.
Request
| Name | Type |
|---|
Response
| Name | Type |
|---|---|
s |
int32
|
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 |
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
| Name | Type |
|---|---|
s |
int32
|
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
| Name | Type |
|---|
Response
| Name | Type |
|---|---|
s |
int32
|
GetAttr
Acquires information about the node.
This method does not require any rights.
Request
| Name | Type |
|---|
Response
| Name | Type |
|---|---|
s |
int32
|
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
| Name | Type |
|---|---|
flags |
uint32
|
attributes |
fuchsia.io/NodeAttributes
|
Response
| Name | Type |
|---|---|
s |
int32
|
Ioctl
Deprecated. Only for use with compatibility with devhost.
Request
| Name | Type |
|---|---|
opcode |
uint32
|
max_out |
uint64
|
handles |
vector<handle>[2]
|
in |
vector<uint8>[8192]
|
Response
| Name | Type |
|---|---|
s |
int32
|
handles |
vector<handle>[2]
|
out |
vector<uint8>[8192]
|
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
| Name | Type |
|---|---|
count |
uint64
|
Response
| Name | Type |
|---|---|
s |
int32
|
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
| Name | Type |
|---|---|
count |
uint64
|
offset |
uint64
|
Response
| Name | Type |
|---|---|
s |
int32
|
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
| Name | Type |
|---|---|
data |
vector<uint8>[8192]
|
Response
| Name | Type |
|---|---|
s |
int32
|
actual |
uint64
|
WriteAt
Writes data to the provided offset. Does not affect the seek offset.
This method requires following rights: OPEN_RIGHT_WRITABLE.
Request
| Name | Type |
|---|---|
data |
vector<uint8>[8192]
|
offset |
uint64
|
Response
| Name | Type |
|---|---|
s |
int32
|
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
| Name | Type |
|---|---|
offset |
int64
|
start |
fuchsia.io/SeekOrigin
|
Response
| Name | Type |
|---|---|
s |
int32
|
offset |
uint64
|
Truncate
Shrinks the file size to 'length' bytes.
This method requires following rights: OPEN_RIGHT_WRITABLE.
Request
| Name | Type |
|---|---|
length |
uint64
|
Response
| Name | Type |
|---|---|
s |
int32
|
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 |
int32
|
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
| Name | Type |
|---|---|
flags |
uint32
|
Response
| Name | Type |
|---|---|
s |
int32
|
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 |
int32
|
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
| Name | Type |
|---|---|
id |
uint32
|
client |
handle<channel>
|
Response
| Name | Type |
|---|---|
s |
int32
|
ClrSetFeature
allowed on Client PTYs
Clear and/or Set PTY Features
Request
| Name | Type |
|---|---|
clr |
uint32
|
set |
uint32
|
Response
| Name | Type |
|---|---|
status |
int32
|
features |
uint32
|
GetWindowSize
Obtain the window size (in character cells)
Request
| Name | Type |
|---|
Response
| Name | Type |
|---|---|
status |
int32
|
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 |
int32
|
ReadEvents
Returns pending OOB events, simultaneously clearing them
Request
| Name | Type |
|---|
Response
| Name | Type |
|---|---|
status |
int32
|
events |
uint32
|
SetWindowSize
allowed on the Server PTY
Sets the window size
Request
| Name | Type |
|---|---|
size |
WindowSize
|
Response
| Name | Type |
|---|---|
status |
int32
|
STRUCTS
WindowSize
Defined in fuchsia.hardware.pty/pty.fidl
| Name | Type | Description | Default |
|---|---|---|---|
width |
uint32
|
No default | |
height |
uint32
|
No default |
CONSTANTS
| Name | Value | Type | Description |
|---|---|---|---|
| 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. |