Man page - busctl(1)

Packages contains this manual

Available languages:

en sv uk zh_TW zh_CN de

Manual

BUSCTL

NAME
SYNOPSIS
描 述
選 項
命 令
引 數 格 式
例 子
參 見
NOTES
跋

NAME

busctl - 內 省 與 監 視 D-Bus 匯 流 排

SYNOPSIS

busctl [OPTIONS...] [COMMAND] [ NAME ...]

描 述

busctl 可 用 於 內 省 與 監 視 D-Bus 匯 流 排

選 項

能 夠 識 別 的 命 令 列 選 項 如 下 ：

--address= ADDRESS

連 線 到 ADDRESS 指 定 的 匯 流 排 ， 而 不 是 預 設 的 匯 流 排 (無 論 是 --system 系 統 匯 流 排 還 是 --user 使 用 者 匯 流 排 )。

--show-machine

在 使 用 list 命 令 顯 示 總 線 上 的 所 有 peer 列 表 時 ， 額 外 顯 示 一 個 "MACHINE"列 ， 指 明 其 所 屬 容 器 的 名 稱 。 參 見 systemd-machined.service (8) 手 冊 。

--unique

在 使 用 list 命 令 顯 示 總 線 上 的 所 有 peer 列 表 時 ， 僅 顯 示 ": number . number " 格 式 的 "唯 一 名 "(UniqueName)。

--acquired

在 使 用 list 命 令 顯 示 總 線 上 的 所 有 peer 列 表 時 ， 與 --unique 選 項 正 好 相 反 ， 僅 顯 示 "易 讀 名 "(well-known name)。

--activatable

在 使 用 list 命 令 顯 示 總 線 上 的 所 有 peer 列 表 時 ， 僅 顯 示 當 前 未 被 啟 用 並 且 可 以 在 被 訪 問 時 自 動 啟 用 的 peer 。

--match= MATCH

在 使 用 monitor 命 令 監 視 已 交 換 的 訊 息 時 ， 僅 顯 示 與 MATCH 匹 配 的 訊 息 。 參 見 sd_bus_add_match (3)

--size=

在 使 用 capture 命 令 捕 獲 已 交 換 的 訊 息 時 ， 指 定 允 許 捕 獲 的 最 大 訊 息 尺 寸 ("snaplen")， 預 設 值 是 4096 位 元 組 。

--list

在 使 用 tree 命 令 顯 示 物 件 路 徑 時 ， 不 以 樹 形 縮 排 顯 示 ， 而 是 以 平 鋪 列 表 的 格 式 顯 示 。

--quiet

與 call 命 令 連 用 ， 禁 止 顯 示 應 答 訊 息 。 注 意 ： 錯 誤 訊 息 依 然 會 被 顯 示 出 來 ， 並 且 依 然 可 以 用 返 回 值 判 斷 成 敗 。

--verbose

與 call 或 get-property 命 令 連 用 ， 表 示 以 詳 細 模 式 顯 示 輸 出 。

--expect-reply= BOOL

與 call 命 令 連 用 ， 設 定 是 否 等 待 被 呼 叫 的 方 法 執 行 完 成 。 "yes" 表 示 等 待 方 法 執 行 完 成 並 且 返 回 應 答 資 料 ， 然 後 busctl 將 返 回 一 個 可 用 於 判 斷 方 法 執 行 成 敗 的 返 回 碼 。 "no" 表 示 呼 叫 方 法 之 後 不 等 待 其 執 行 完 成 也 不 顯 示 應 答 資 料 ， 而 是 直 接 退 出 ， 並 且 不 返 回 有 意 義 的 返 回 碼 。 如 果 只 是 想 遮 蔽 應 答 資 料 ， 應 該 使 用 --quiet 選 項 。 預 設 值 為 "yes"

--auto-start= BOOL

與 call 命 令 連 用 ， 設 定 是 否 應 該 隱 含 的 啟 動 當 前 尚 未 執 行 、 但 是 被 配 置 為 自 動 啟 動 的 服 務 。 預 設 是 "yes"

--allow-interactive-authorization= BOOL

與 call 命 令 連 用 ， 設 定 服 務 在 執 行 操 作 時 ， 是 否 應 該 強 制 進 行 互 動 式 授 權 (在 安 全 策 略 已 配 置 的 時 候 )。 預 設 是 "yes"

--timeout= SECS

與 call 命 令 連 用 ， 設 定 等 候 方 法 完 成 的 最 大 秒 數 。 注 意 ， 此 處 的 超 時 設 定 對 --expect-reply=no 無 效 。 可 使 用 明 確 的 時 間 單 位 字 尾 ： us, ms, s, min, h, d, w, month, y 。 預 設 值 是 "25s" (注 意 ， 設 為 "0"也 等 價 於 "25s")。

--augment-creds= BOOL

設 定 list / status 命 令 報 告 的 憑 據 資 料 是 否 應 該 被 擴 充 套 件 為 包 含 來 自 /proc 的 資 料 。 若 設 為 "yes"(預 設 值 )， 那 麼 顯 示 的 資 料 可 能 會 不 一 致 ， 因 為 /proc 中 的 資 料 可 能 會 更 新 。

--user

與 當 前 呼 叫 使 用 者 的 使 用 者 服 務 管 理 器 (systemd 使 用 者 例 項 )通 訊 ， 而 不 是 預 設 的 系 統 服 務 管 理 器 (systemd 系 統 例 項 )。

--system

與 系 統 服 務 管 理 器 (systemd 系 統 例 項 )通 訊 ， 這 是 預 設 值 。

-H , --host=

操 作 指 定 的 遠 端 主 機 。 可 以 僅 指 定 一 個 主 機 名 (hostname)， 也 可 以 使 用 "username@hostname" 格 式 。 hostname 後 面 還 可 以 加 上 容 器 名 (以 冒 號 分 隔 )， 也 就 是 形 如 "hostname:container" 的 格 式 ， 以 表 示 直 接 連 線 到 指 定 主 機 的 指 定 容 器 內 。 操 作 將 透 過 SSH協 議 進 行 ， 以 確 保 安 全 。 可 以 透 過 machinectl -H HOST 命 令 列 出 遠 端 主 機 上 的 所 有 容 器 名 稱 。

-M , --machine=

在 本 地 容 器 內 執 行 操 作 。 必 須 明 確 指 定 容 器 的 名 稱 。

--no-pager

不 將 程 式 的 輸 出 內 容 管 道 (pipe)給 分 頁 程 式 。

--no-legend

不 輸 出 列 標 題 ， 也 就 是 不 在 輸 出 列 表 的 頭 部 和 尾 部 顯 示 欄 位 的 名 稱 。

-h , --help

顯 示 簡 短 的 幫 助 資 訊 並 退 出 。

--version

顯 示 簡 短 的 版 本 資 訊 並 退 出 。

命 令

能 夠 識 別 的 命 令 如 下 ：

list

顯 示 總 線 上 的 所 有 peer(依 據 服 務 名 稱 )， 這 是 預 設 命 令 。 默 認 同 時 顯 示 "唯 一 名 "(UniqueName)與 "易 讀 名 "(well-known name)， 但 是 可 以 使 用 --unique 與 --acquired 選 項 進 行 修 改 。

status [ SERVICE ]

如 果 SERVICE 是 一 個 匯 流 排 服 務 的 "唯 一 名 "或 "易 讀 名 "， 那 麼 顯 示 該 服 務 的 程 序 資 訊 及 憑 證 資 訊 。 如 果 SERVICE 是 一 個 程 序 的 PID， 那 麼 顯 示 該 程 序 的 程 序 資 訊 及 憑 證 資 訊 。 如 果 未 指 定 SERVICE 引 數 ， 那 麼 顯 示 匯 流 排 所 有 者 的 程 序 資 訊 及 憑 證 資 訊 。

monitor [ SERVICE ...]

監 視 已 交 換 的 訊 息 ， 可 使 用 Ctrl-C 中 斷 監 視 。 如 果 未 指 定 SERVICE 引 數 ， 那 麼 顯 示 總 線 上 的 所 有 訊 息 。 如 果 指 定 了 SERVICE 引 數 ("唯 一 名 "或 "易 讀 名 ")， 那 麼 僅 顯 示 到 達 此 peer或 者 從 此 peer發 出 的 訊 息 。

capture [ SERVICE ...]

與 monitor 命 令 類 似 ， 不 同 之 處 在 於 以 pcap 格 式 輸 出 (詳 見 Libpcap File Format [1] )。 強 烈 推 薦 將 STDOUT 重 定 向 到 一 個 檔 案 中 ， 然 後 使 用 wireshark (1) 工 具 檢 視 與 分 析 。

tree [ SERVICE ...]

顯 示 服 務 的 物 件 樹 。 如 果 給 出 了 SERVICE 引 數 ， 那 麼 僅 顯 示 指 定 服 務 的 物 件 樹 ， 否 則 顯 示 總 線 上 所 有 具 有 "易 讀 名 "服 務 的 物 件 樹 。

introspect SERVICE OBJECT [ INTERFACE ]

顯 示 SERVICE服 務 上 OBJECT物 件 (以 路 徑 表 示 )的 interface, method, property, signal 值 。 如 果 指 定 了 INTERFACE 引 數 ， 那 麼 僅 輸 出 指 定 介 面 上 的 成 員 。

call SERVICE OBJECT INTERFACE METHOD [ SIGNATURE [ ARGUMENT ...]]

呼 叫 一 個 方 法 並 顯 示 應 答 。 必 須 指 定 服 務 名 稱 (SERVICE)、 物 件 路 徑 (OBJECT)、 介 面 名 稱 (INTERFACE)、 方 法 名 稱 (METHOD)。 如 果 要 給 方 法 傳 遞 引 數 ， 那 麼 必 須 使 用 型 別 標 記 (SIGNATURE)後 跟 一 個 引 數 字 串 (ARGUMENT)。 格 式 細 節 參 見 下 面 的 "引 數 格 式 "小 節 。 可 以 使 用 --quiet 選 項 抑 制 輸 出 。

get-property SERVICE OBJECT INTERFACE PROPERTY ...

顯 示 物 件 屬 性 的 當 前 值 。 必 須 指 定 服 務 名 稱 (SERVICE)、 物 件 路 徑 (OBJECT)、 介 面 名 稱 (INTERFACE)、 屬 性 名 稱 (PROPERTY)。 如 果 同 時 指 定 了 多 個 屬 性 名 稱 ， 那 麼 將 按 照 每 行 一 個 ， 依 次 顯 示 每 個 屬 性 的 當 前 值 。 預 設 以 精 簡 格 式 輸 出 ， 但 是 可 以 使 用 --verbose 選 項 以 詳 細 格 式 輸 出 。

set-property SERVICE OBJECT INTERFACE PROPERTY SIGNATURE ARGUMENT ...

設 定 物 件 屬 性 的 當 前 值 。 必 須 指 定 下 列 引 數 ： 服 務 名 稱 (SERVICE)、 物 件 路 徑 (OBJECT)、 介 面 名 稱 (INTERFACE)、 屬 性 名 稱 (PROPERTY)、 型 別 標 記 (SIGNATURE)、 引 數 字 串 (ARGUMENT)。

help

顯 示 語 法 幫 助

引 數 格 式

call 與 set-property 命 令 都 接 收 一 個 型 別 標 記 (SIGNATURE)與 多 個 引 數 字 串 (ARGUMENT)。 有 關 "型 別 標 記 "的 詳 細 說 明 ， 參 見 Type system chapter of the D-Bus specification [2] 文 件 的 "Type System"小 節 。 對 於 簡 單 型 別 (Basic types)， 型 別 標 記 (SIGNATURE)後 面 的 每 個 引 數 (ARGUMENT)都 必 須 是 引 數 值 的 字 串 表 示 。 布 林 型 別 真 值 可 以 表 示 為 "true", "yes", "on", "1" ； 布 林 型 別 假 值 可 以 表 示 為 "false", "no", "off", "0" 。 對 於 陣 列 ， 先 是 一 個 表 示 陣 列 項 數 的 數 字 ， 然 後 跟 著 陣 列 中 的 每 一 項 。 對 於 變 數 ， 先 是 一 個 表 示 變 數 型 別 的 字 元 ， 然 後 跟 著 變 數 的 值 。 對 於 字 典 與 結 構 ， 直 接 指 定 其 內 容 即 可 。

例 如 ，

s jawoll

是 一 個 簡 單 的 字 串 "jawoll" ， "s"是 型 別 標 記 ， "jawoll"是 引 數 字 串 。

as 3 hello world foobar

是 一 個 字 串 陣 列 ， 包 含 3個 成 員 ， 分 別 是 "hello", "world", "foobar"

a{sv} 3 One s Eins Two u 2 Yes b true

是 一 個 字 典 陣 列 ， 該 字 典 將 字 串 對 映 為 變 數 ， 包 含 3個 成 員 ， 分 別 是 ： 字 串 "One" 對 映 到 字 串 "Eins" ， 字 串 "Two" 對 映 到 32位 無 符 號 整 數 "2"， 字 串 "Yes" 對 映 到 布 林 真 值 。

注 意 ， call , get-property , introspect 命 令 在 輸 出 應 答 時 也 同 樣 是 這 個 格 式 。 由 於 這 個 格 式 過 於 精 簡 不 易 理 解 ， 所 以 call 與 get-property 命 令 提 供 了 --verbose 選 項 用 於 輸 出 詳 細 的 、 易 於 理 解 的 多 行 輸 出 格 式 。

例 子

Example 1. 讀 寫 屬 性

下 面 的 兩 個 命 令 ， 首 先 寫 入 一 個 屬 性 ， 然 後 再 讀 取 它 。 該 屬 性 位 於 "org.freedesktop.systemd1" 服 務 的 "/org/freedesktop/systemd1" 物 件 中 ， 屬 性 名 是 "org.freedesktop.systemd1.Manager" 介 面 上 的 "LogLevel" ， 此 屬 性 是 一 個 簡 單 的 字 串 ：

# busctl set-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel s debug
# busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel s "debug"

Example 2. 精 簡 輸 出 與 詳 細 輸 出

下 面 的 兩 個 命 令 ， 兩 次 讀 取 同 一 個 屬 性 (字 串 陣 列 型 別 )， 第 一 次 以 精 簡 格 式 顯 示 ， 第 二 次 以 詳 細 格 式 顯 示 ：

$ busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
as 2 "LANG=en_US.utf8" "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"
$ busctl get-property --verbose org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
ARRAY "s" {
STRING "LANG=en_US.utf8";
STRING "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin";
};

Example 3. 呼 叫 方 法

下 面 的 命 令 ， 在 "org.freedesktop.systemd1" 服 務 的 "/org/freedesktop/systemd1" 物 件 的 "org.freedesktop.systemd1.Manager" 介 面 上 呼 叫 了 "StartUnit" 方 法 ， 並 且 給 此 方 法 傳 遞 了 "cups.service" 與 "replace" 兩 個 字 串 。 而 此 方 法 返 回 了 一 個 物 件 路 徑 ：

# busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager StartUnit ss "cups.service" "replace"
o "/org/freedesktop/systemd1/job/42684"

參 見

dbus-daemon (1), D-Bus [3] , sd-bus (3), systemd (1), machinectl (1), wireshark (1)

NOTES

1.

Libpcap File Format

http://wiki.wireshark.org/Development/LibpcapFileFormat

2.

Type system chapter of the D-Bus specification

http://dbus.freedesktop.org/doc/dbus-specification.html#type-system

3.

D-Bus

http://freedesktop.org/wiki/Software/dbus

跋

本 頁 面 中 文 版 由 中 文 man 手 冊 頁 計 劃 提 供 。

翻 譯 人 員 ： 金 步 國
金 步 國 作 品 集 ： http://www.jinbuguo.com
中 文 man 手 冊 頁 計 劃 ： https://github.com/man-pages-zh/manpages-zh