Provided by: manpages-zh_1.6.3.2-1_all bug

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 命令顯示對象路徑時, 不以樹形縮進顯示,而是以平鋪列表的格式顯示。

       --quietcall 命令連用,禁止顯示應答消息。 注意:
           錯誤消息依然會被顯示出來,並且依然可以用返回值判斷成敗。

       --verbosecallget-property 命令連用, 表示以詳細模式顯示輸出。

       --expect-reply=BOOLcall 命令連用, 設置是否等待被調用的方法執行完成。 "yes"
           表示等待方法執行完成並且返回應答數據, 然後 busctl
           將返回一個可用於判斷方法執行成敗的返回碼。 "no"
           表示調用方法之後不等待其執行完成也不顯示應答數據,
           而是直接退出,並且不返回有意義的返回碼。 如果只是想屏蔽應答數據, 應該使用 --quiet
           選項。 默認值爲 "yes"

       --auto-start=BOOLcall 命令連用, 設置是否應該隱含的啓動當前尚未運行、 但是被配置爲自動啓動的服務。
           默認是 "yes"

       --allow-interactive-authorization=BOOLcall 命令連用, 設置服務在執行操作時,
           是否應該強制進行交互式授權(在安全策略已配置的時候)。 默認是 "yes"

       --timeout=SECScall 命令連用, 設置等候方法完成的最大秒數。 注意,此處的超時設置對
           --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
           顯示語法幫助

參數格式

       callset-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 命令在輸出應答時也同樣是這個格式。
       由於這個格式過於精簡不易理解, 所以 callget-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