fuchsia.hardware.pty

PTY (虛擬終端機) 會模擬終端機裝置,其中包含「伺服器」端 (代表終端機的鍵盤 + 螢幕端,可透過開啟 /dev/misc/ptmx 取得) 和多個「用戶端」端,可透過呼叫 OpenClient 取得。

用戶端 PTY 會透過 OpenClient 呼叫中使用的 id 進行識別。第一個用戶端 PTY 必須為 0,且只有這個用戶端 PTY 可以建立其他用戶端 PTY、接收事件等。這是控制 PTY。

新增:11

PROTOCOLS

裝置

fuchsia.hardware.pty/pty.fidl 中定義

複製

新增:NEXT

要求

名稱類型
request server_end:fuchsia.unknown/Cloneable

關閉

終止連線。

呼叫 Close 後,用戶端不得傳送任何其他要求。

伺服器在傳送狀態回應後,應關閉連線,無論狀態為何,都不要傳送碑文。

關閉管道的用戶端端點,在語意上應等同於呼叫 Close,但不必知道關閉完成的時間或狀態。

要求

<EMPTY>

回應

ClrSetFeature

允許用於用戶端 PTY

清除及/或設定 PTY 功能

要求

名稱類型
clr uint32
set uint32

回應

名稱類型
status zx/Status
features uint32

說明

要求

<EMPTY>

回應

名稱類型
payload DeviceDescribeResponse

GetWindowSize

取得視窗大小 (以字元儲存格為單位)

要求

<EMPTY>

回應

名稱類型
status zx/Status
size WindowSize

MakeActive

允許在控制 PTY 上

選取要接收輸入內容的 Client PTY。讀取作業會在非活動的 PTY 上阻斷。

要求

名稱類型
client_pty_id uint32

回應

名稱類型
status zx/Status

OpenClient

使用專屬的 id 開啟用戶端 PTY 裝置。client 應為管道一個端點的句柄,在成功時會成為與新建立裝置的開放連線。如果失敗,管道就會關閉。關閉管道會關閉連線並釋放裝置。如果提供的 id 為 0,則新用戶端為控制用戶端,且具有開啟其他用戶端的能力。如果目前的裝置不是控制端用戶端,系統會傳回 ZX_ERR_ACCESS_DENIED。如果 id 不是唯一值,系統會傳回 ZX_ERR_INVALID_ARGS。否則,系統會傳遞 device_add 的狀態碼。

要求

名稱類型
id uint32
client server_end:Device

回應

名稱類型
s zx/Status

查詢

要求

<EMPTY>

回應

名稱類型
protocol vector<uint8>

閱讀

在搜尋偏移量中讀取最多「count」個位元組。尋軌偏移量會向前移動讀取的位元組數。

不變量

  • 傳回的 data.length 絕不會大於 count
  • 如果 data.length 小於 count,表示在該作業中,搜尋偏移量已達檔案結尾。
  • 如果 data.length 為零,而 count 不是,表示尋找偏移量已達檔案結尾或超出檔案結尾,因此無法讀取任何資料。
  • 如果 count 為零,伺服器應執行所有檢查,確保讀取權限不必實際讀取任何內容,並傳回空白 data 向量。

這個方法需要 Rights.READ_BYTES 權限。

如果 count 大於 MAX_TRANSFER_SIZE,則會傳回 ZX_ERR_OUT_OF_RANGE

要求

名稱類型
count uint64

回應

名稱類型
payload fuchsia.io/Readable_Read_Result

ReadEvents

傳回待處理的 OOB 事件,並同時清除這些事件

要求

<EMPTY>

回應

名稱類型
status zx/Status
events uint32

SetWindowSize

在伺服器 PTY 上允許

設定視窗大小

要求

名稱類型
size WindowSize

回應

名稱類型
status zx/Status

寫入

在搜尋偏移處寫入資料。尋找偏移量會向前移動已寫入的位元組數。如果檔案處於附加模式,系統會先將搜尋偏移量設為檔案結尾,然後在單一原子步驟中進行寫入。

如果尋找偏移量加上 data.length 超出目前的檔案結尾,檔案大小可能會增加。

  • 要求 data 位元組緩衝區,以便寫入檔案。
  • response actual_count 寫入的位元組數。

不變量

  • 傳回的 actual_count 絕不會大於 data.length
  • 如果伺服器因空間不足等原因而無法寫入所有資料,actual_count 可能會小於 data.length。如果無法寫入任何位元組,系統會傳回錯誤。
  • 如果 data.length 為零,伺服器應執行所有檢查,確保寫入權限不會變更檔案,並傳回成功寫入的零位元組。在附加模式下,尋找偏移值仍會更新。

這個方法需要 Rights.WRITE_BYTES 權限。

要求

名稱類型
data fuchsia.io/Transfer

回應

名稱類型
payload fuchsia.io/Writable_Write_Result

STRUCTS

WindowSize

fuchsia.hardware.pty/pty.fidl 中定義

欄位類型說明預設
width uint32 無預設
height uint32 無預設

TABLES

DeviceDescribeResponse resource

fuchsia.hardware.pty/pty.fidl 中定義

序數欄位類型說明
event handle<eventpair>

可選事件,用於傳送裝置狀態相關資訊。

這個事件可能會顯示 DeviceSignal 值。

常數

名稱類型說明
DEVICE_PROTOCOL_NAME fuchsia.hardware.pty/Device String
EVENT_HANGUP 1 uint32

終端機沒有任何有效的用戶端。

EVENT_INTERRUPT 2 uint32

終端機收到 ^C 控制字元。

EVENT_MASK 15 uint32

所有活動

EVENT_SUSPEND 4 uint32

終端機收到 ^Z 控制字元。

EVENT_WINDOW_SIZE 8 uint32

終端機視窗已調整大小。

FEATURE_RAW 1 uint32

啟用原始功能後,系統就不會產生 ^c、^z 等 OOB 事件。而是從 read() 輸入路徑讀取字元。