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:
- 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.
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 |
zx/status
|
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
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
|
GetAttr
Acquires information about the node.
This method does not require any rights.
Request
Name | Type |
---|
Response
Name | Type |
---|---|
s |
zx/status
|
attributes |
fuchsia.io/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
ifflags
includesVMO_FLAG_WRITE
.OPEN_RIGHT_READABLE
ifflags
includesVMO_FLAG_READ
orVMO_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
|
GetWindowSize
Obtain the window size (in character cells)
Request
Name | Type |
---|
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
|
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 |
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
Name | Type |
---|---|
id |
uint32
|
client |
handle<channel>
|
Response
Name | Type |
---|---|
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
, 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]
|
ReadEvents
Returns pending OOB events, simultaneously clearing them
Request
Name | Type |
---|
Response
Name | Type |
---|---|
status |
zx/status
|
events |
uint32
|
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 |
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
.
Request
Name | Type |
---|---|
flags |
uint32
|
attributes |
fuchsia.io/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
|
SetWindowSize
allowed on the Server PTY
Sets the window size
Request
Name | Type |
---|---|
size |
WindowSize
|
Response
Name | Type |
---|---|
status |
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
|
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 |
---|---|---|---|
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. |