'\" t
.TH "BUSCTL" "1" "" "systemd 231" "busctl"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
busctl \- 內省與監視 D\-Bus 總線
.SH "SYNOPSIS"
.HP \w'\fBbusctl\fR\ 'u
\fBbusctl\fR [OPTIONS...] [COMMAND] [\fINAME\fR...]
.SH "描述"
.PP
\fBbusctl\fR
可用於內省與監視 D\-Bus 總線
.SH "選項"
.PP
能夠識別的命令行選項如下：
.PP
\fB\-\-address=\fR\fB\fIADDRESS\fR\fR
.RS 4
連接到
\fIADDRESS\fR
指定的總線， 而不是默認的總線(無論是
\fB\-\-system\fR
系統總線還是
\fB\-\-user\fR
用戶總線)。
.RE
.PP
\fB\-\-show\-machine\fR
.RS 4
在使用
\fBlist\fR
命令顯示總線上的所有 peer 列表時， 額外顯示一個"MACHINE"列，指明其所屬容器的名稱。參見
\fBsystemd-machined.service\fR(8)
手冊。
.RE
.PP
\fB\-\-unique\fR
.RS 4
在使用
\fBlist\fR
命令顯示總線上的所有 peer 列表時，僅顯示
":\fInumber\fR\&.\fInumber\fR"
格式的"唯一名"(UniqueName)。
.RE
.PP
\fB\-\-acquired\fR
.RS 4
在使用
\fBlist\fR
命令顯示總線上的所有 peer 列表時，與
\fB\-\-unique\fR
選項正好相反， 僅顯示"易讀名"(well\-known name)。
.RE
.PP
\fB\-\-activatable\fR
.RS 4
在使用
\fBlist\fR
命令顯示總線上的所有 peer 列表時， 僅顯示當前未被激活並且可以在被訪問時自動激活的 peer 。
.RE
.PP
\fB\-\-match=\fR\fB\fIMATCH\fR\fR
.RS 4
在使用
\fBmonitor\fR
命令監視已交換的消息時， 僅顯示與
\fIMATCH\fR
匹配的消息。 參見
\fBsd_bus_add_match\fR(3)
.RE
.PP
\fB\-\-size=\fR
.RS 4
在使用
\fBcapture\fR
命令捕獲已交換的消息時， 指定允許捕獲的最大消息尺寸("snaplen")， 默認值是 4096 字節。
.RE
.PP
\fB\-\-list\fR
.RS 4
在使用
\fBtree\fR
命令顯示對象路徑時， 不以樹形縮進顯示，而是以平鋪列表的格式顯示。
.RE
.PP
\fB\-\-quiet\fR
.RS 4
與
\fBcall\fR
命令連用，禁止顯示應答消息。 注意： 錯誤消息依然會被顯示出來，並且依然可以用返回值判斷成敗。
.RE
.PP
\fB\-\-verbose\fR
.RS 4
與
\fBcall\fR
或
\fBget\-property\fR
命令連用， 表示以詳細模式顯示輸出。
.RE
.PP
\fB\-\-expect\-reply=\fR\fIBOOL\fR
.RS 4
與
\fBcall\fR
命令連用， 設置是否等待被調用的方法執行完成。
"yes"
表示等待方法執行完成並且返回應答數據， 然後
\fBbusctl\fR
將返回一個可用於判斷方法執行成敗的返回碼。
"no"
表示調用方法之後不等待其執行完成也不顯示應答數據， 而是直接退出，並且不返回有意義的返回碼。 如果只是想屏蔽應答數據， 應該使用
\fB\-\-quiet\fR
選項。 默認值爲
"yes"
.RE
.PP
\fB\-\-auto\-start=\fR\fIBOOL\fR
.RS 4
與
\fBcall\fR
命令連用， 設置是否應該隱含的啓動當前尚未運行、 但是被配置爲自動啓動的服務。 默認是
"yes"
.RE
.PP
\fB\-\-allow\-interactive\-authorization=\fR\fIBOOL\fR
.RS 4
與
\fBcall\fR
命令連用， 設置服務在執行操作時， 是否應該強制進行交互式授權(在安全策略已配置的時候)。 默認是
"yes"
.RE
.PP
\fB\-\-timeout=\fR\fISECS\fR
.RS 4
與
\fBcall\fR
命令連用， 設置等候方法完成的最大秒數。 注意，此處的超時設置對
\fB\-\-expect\-reply=no\fR
無效。 可使用明確的時間單位後綴： us, ms, s, min, h, d, w, month, y 。 默認值是"25s"
(注意，設爲"0"也等價於"25s")。
.RE
.PP
\fB\-\-augment\-creds=\fR\fIBOOL\fR
.RS 4
設置
\fBlist\fR/\fBstatus\fR
命令報告的憑據數據 是否應該被擴展爲包含來自
/proc
的數據。 若設爲"yes"(默認值)， 那麼顯示的數據可能會不一致， 因爲
/proc
中的數據可能會更新。
.RE
.PP
\fB\-\-user\fR
.RS 4
與當前調用用戶的用戶服務管理器(systemd 用戶實例)通信， 而不是默認的系統服務管理器(systemd 系統實例)。
.RE
.PP
\fB\-\-system\fR
.RS 4
與系統服務管理器(systemd 系統實例)通信， 這是默認值。
.RE
.PP
\fB\-H\fR, \fB\-\-host=\fR
.RS 4
操作指定的遠程主機。可以僅指定一個主機名(hostname)， 也可以使用
"username@hostname"
格式。 hostname 後面還可以加上容器名(以冒號分隔)， 也就是形如
"hostname:container"
的格式， 以表示直接連接到指定主機的指定容器內。 操作將通過SSH協議進行，以確保安全。 可以通過
\fBmachinectl \-H \fR\fB\fIHOST\fR\fR
命令列出遠程主機上的所有容器名稱。
.RE
.PP
\fB\-M\fR, \fB\-\-machine=\fR
.RS 4
在本地容器內執行操作。 必須明確指定容器的名稱。
.RE
.PP
\fB\-\-no\-pager\fR
.RS 4
不將程序的輸出內容管道(pipe)給分頁程序。
.RE
.PP
\fB\-\-no\-legend\fR
.RS 4
不輸出列標題， 也就是不在輸出列表的頭部和尾部顯示字段的名稱。
.RE
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
顯示簡短的幫助信息並退出。
.RE
.PP
\fB\-\-version\fR
.RS 4
顯示簡短的版本信息並退出。
.RE
.SH "命令"
.PP
能夠識別的命令如下：
.PP
\fBlist\fR
.RS 4
顯示總線上的所有peer(依據服務名稱)，這是默認命令。 默認同時顯示"唯一名"(UniqueName)與"易讀名"(well\-known name)， 但是可以使用
\fB\-\-unique\fR
與
\fB\-\-acquired\fR
選項進行修改。
.RE
.PP
\fBstatus\fR [\fISERVICE\fR]
.RS 4
如果 SERVICE 是一個總線服務的"唯一名"或"易讀名"， 那麼顯示該服務的進程信息及憑證信息。 如果 SERVICE 是一個進程的PID，那麼顯示該進程的進程信息及憑證信息。 如果未指定 SERVICE 參數，那麼顯示總線所有者的進程信息及憑證信息。
.RE
.PP
\fBmonitor\fR [\fISERVICE\fR...]
.RS 4
監視已交換的消息，可使用 Ctrl\-C 中斷監視。 如果未指定
\fISERVICE\fR
參數，那麼顯示總線上的所有消息。 如果指定了
\fISERVICE\fR
參數("唯一名"或"易讀名")， 那麼僅顯示到達此peer或者從此peer發出的消息。
.RE
.PP
\fBcapture\fR [\fISERVICE\fR...]
.RS 4
與
\fBmonitor\fR
命令類似， 不同之處在於以 pcap 格式輸出(詳見
\m[blue]\fBLibpcap File Format\fR\m[]\&\s-2\u[1]\d\s+2)。 強烈推薦將 STDOUT 重定向到一個文件中，然後使用
\fBwireshark\fR(1)
工具查看與分析。
.RE
.PP
\fBtree\fR [\fISERVICE\fR...]
.RS 4
顯示服務的對象樹。 如果給出了
\fISERVICE\fR
參數， 那麼僅顯示指定服務的對象樹， 否則顯示總線上所有具有"易讀名"服務的對象樹。
.RE
.PP
\fBintrospect\fR \fISERVICE\fR \fIOBJECT\fR [\fIINTERFACE\fR]
.RS 4
顯示SERVICE服務上OBJECT對象(以路徑表示)的 interface, method, property, signal 值。 如果指定了 INTERFACE 參數， 那麼僅輸出指定接口上的成員。
.RE
.PP
\fBcall\fR \fISERVICE\fR \fIOBJECT\fR \fIINTERFACE\fR \fIMETHOD\fR [\fISIGNATURE\fR\ [\fIARGUMENT\fR...]]
.RS 4
調用一個方法並顯示應答。 必須指定服務名稱(SERVICE)、對象路徑(OBJECT)、接口名稱(INTERFACE)、方法名稱(METHOD)。 如果要給方法傳遞參數， 那麼必須使用類型標記(SIGNATURE)後跟一個參數字符串(ARGUMENT)。 格式細節參見下面的"參數格式"小節。 可以使用
\fB\-\-quiet\fR
選項抑制輸出。
.RE
.PP
\fBget\-property\fR \fISERVICE\fR \fIOBJECT\fR \fIINTERFACE\fR \fIPROPERTY\fR...
.RS 4
顯示對象屬性的當前值。 必須指定服務名稱(SERVICE)、對象路徑(OBJECT)、接口名稱(INTERFACE)、屬性名稱(PROPERTY)。 如果同時指定了多個屬性名稱，那麼將按照每行一個，依次顯示每個屬性的當前值。 默認以精簡格式輸出， 但是可以使用
\fB\-\-verbose\fR
選項以詳細格式輸出。
.RE
.PP
\fBset\-property\fR \fISERVICE\fR \fIOBJECT\fR \fIINTERFACE\fR \fIPROPERTY\fR \fISIGNATURE\fR \fIARGUMENT\fR...
.RS 4
設置對象屬性的當前值。 必須指定下列參數： 服務名稱(SERVICE)、對象路徑(OBJECT)、接口名稱(INTERFACE)、 屬性名稱(PROPERTY)、類型標記(SIGNATURE)、參數字符串(ARGUMENT)。
.RE
.PP
\fBhelp\fR
.RS 4
顯示語法幫助
.RE
.SH "參數格式"
.PP
\fBcall\fR
與
\fBset\-property\fR
命令都接收一個類型標記(SIGNATURE)與多個參數字符串(ARGUMENT)。 有關"類型標記"的詳細說明， 參見
\m[blue]\fBType system chapter of the D\-Bus specification\fR\m[]\&\s-2\u[2]\d\s+2
文檔的"Type System"小節。 對於簡單類型(Basic types)， 類型標記(SIGNATURE)後面的每個參數(ARGUMENT)都必須是參數值的字符串表示。 布爾類型真值可以表示爲
"true",
"yes",
"on",
"1"
； 布爾類型假值可以表示爲
"false",
"no",
"off",
"0"
。 對於數組，先是一個表示數組項數的數字，然後跟着數組中的每一項。 對於變量，先是一個表示變量類型的字符，然後跟着變量的值。 對於字典與結構，直接指定其內容即可。
.PP
例如，
.sp
.if n \{\
.RS 4
.\}
.nf
s jawoll
.fi
.if n \{\
.RE
.\}
.sp
是一個簡單的字符串
"jawoll"
， "s"是類型標記，"jawoll"是參數字符串。
.PP
.if n \{\
.RS 4
.\}
.nf
as 3 hello world foobar
.fi
.if n \{\
.RE
.\}
.sp
是一個字符串數組，包含3個成員，分別是
"hello",
"world",
"foobar"
.PP
.if n \{\
.RS 4
.\}
.nf
a{sv} 3 One s Eins Two u 2 Yes b true
.fi
.if n \{\
.RE
.\}
.sp
是一個字典數組， 該字典將字符串映射爲變量，包含3個成員，分別是： 字符串
"One"
映射到字符串
"Eins"
， 字符串
"Two"
映射到32位無符號整數"2"， 字符串
"Yes"
映射到布爾真值。
.PP
注意，
\fBcall\fR,
\fBget\-property\fR,
\fBintrospect\fR
命令在輸出應答時也同樣是這個格式。 由於這個格式過於精簡不易理解， 所以
\fBcall\fR
與
\fBget\-property\fR
命令提供了
\fB\-\-verbose\fR
選項用於輸出詳細的、 易於理解的多行輸出格式。
.SH "例子"
.PP
\fBExample\ \&1.\ \&讀寫屬性\fR
.PP
下面的兩個命令，首先寫入一個屬性，然後再讀取它。 該屬性位於
"org\&.freedesktop\&.systemd1"
服務的
"/org/freedesktop/systemd1"
對象中， 屬性名是
"org\&.freedesktop\&.systemd1\&.Manager"
接口上的
"LogLevel"
， 此屬性是一個簡單的字符串：
.sp
.if n \{\
.RS 4
.\}
.nf
# 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"
.fi
.if n \{\
.RE
.\}
.PP
\fBExample\ \&2.\ \&精簡輸出與詳細輸出\fR
.PP
下面的兩個命令，兩次讀取同一個屬性(字符串數組類型)， 第一次以精簡格式顯示， 第二次以詳細格式顯示：
.sp
.if n \{\
.RS 4
.\}
.nf
$ 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";
};
.fi
.if n \{\
.RE
.\}
.PP
\fBExample\ \&3.\ \&調用方法\fR
.PP
下面的命令， 在
"org\&.freedesktop\&.systemd1"
服務的
"/org/freedesktop/systemd1"
對象的
"org\&.freedesktop\&.systemd1\&.Manager"
接口上調用了
"StartUnit"
方法， 並且給此方法傳遞了
"cups\&.service"
與
"replace"
兩個字符串。 而此方法返回了一個對象路徑：
.sp
.if n \{\
.RS 4
.\}
.nf
# busctl call org\&.freedesktop\&.systemd1 /org/freedesktop/systemd1 org\&.freedesktop\&.systemd1\&.Manager StartUnit ss "cups\&.service" "replace"
o "/org/freedesktop/systemd1/job/42684"
.fi
.if n \{\
.RE
.\}
.SH "參見"
.PP
\fBdbus-daemon\fR(1),
\m[blue]\fBD\-Bus\fR\m[]\&\s-2\u[3]\d\s+2,
\fBsd-bus\fR(3),
\fBsystemd\fR(1),
\fBmachinectl\fR(1),
\fBwireshark\fR(1)
.SH "NOTES"
.IP " 1." 4
Libpcap File Format
.RS 4
\%http://wiki.wireshark.org/Development/LibpcapFileFormat
.RE
.IP " 2." 4
Type system chapter of the D-Bus specification
.RS 4
\%http://dbus.freedesktop.org/doc/dbus-specification.html#type-system
.RE
.IP " 3." 4
D-Bus
.RS 4
\%http://freedesktop.org/wiki/Software/dbus
.RE
.SH "跋"
.br
本頁面中文版由中文 man 手冊頁計劃提供。
.PP
翻譯人員：金步國
.br
金步國作品集：http://www.jinbuguo.com
.br
.br
中文 man 手冊頁計劃：\fBhttps://github.com/man-pages-zh/manpages-zh\fR