X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fbusctl.xml;h=285725e684df82fd9da6146d95757d3449dc2b0d;hp=730a3344d6cb90610ec1d34136cc4f8cb67fff60;hb=9b15b7846d4de01bb5d9700a24077787e984e8ab;hpb=d55192add75584f55932ad463ee6b4cc30370c63 diff --git a/man/busctl.xml b/man/busctl.xml index 730a3344d..285725e68 100644 --- a/man/busctl.xml +++ b/man/busctl.xml @@ -1,4 +1,4 @@ - + @@ -156,8 +156,93 @@ along with systemd; If not, see . - When used with the call command suppresses - display of the response message. + When used with the call command + suppresses display of the response message payload. Note that even + if this option is specified errors returned will still be + printed and the tool will indicate success or failure with + the process exit code. + + + + + + + + When used with the call or + get-property command shows output in a + more verbose format. + + + + + BOOL + + + When used with the call command + specifies whether busctl shall wait for + completion of the method call, output the returned method + response data, and return success or failure via the process + exit code. If this is set to no the + method call will be issued but no response is expected, the + tool terminates immediately, and thus no response can be + shown, and no success or failure is returned via the exit + code. To only suppress output of the reply message payload + use above. Defaults to + yes. + + + + + BOOL + + + When used with the call command specifies + whether the method call should implicitly activate the + called service should it not be running yet but is + configured to be auto-started. Defaults to + yes. + + + + + BOOL + + + When used with the call command + specifies whether the services may enforce interactive + authorization while executing the operation, if the security + policy is configured for this. Defaults to + yes. + + + + + SECS + + + When used with the call command + specifies the maximum time to wait for method call + completion. If no time unit is specified assumes + seconds. The usual other units are understood, too (ms, us, + s, min, h, d, w, month, y). Note that this timeout does not + apply if is used as the + tool does not wait for any reply message then. When not + specified or when set to 0 the default of + 25s is assumed. + + + + + BOOL + + + Controls whether credential data reported by + list or status shall + be augmented with data from + /proc. When this is turned on the data + shown is possibly inconsistent, as the data read from + /proc might be more recent than rest of + the credential information. Defaults to yes. @@ -186,13 +271,13 @@ along with systemd; If not, see . - tree SERVICE + status SERVICE - Shows an object tree of one or more - services. If SERVICE is specified, - show object tree of the specified services only. Otherwise, - show all object trees of all services on the bus that acquired - at least one well-known name. + Show process information and credentials of a + bus service (if one is specified by its unique or well-known + name), a process (if one is specified by its numeric PID), or + the owner of the bus (if no parameter is + specified). @@ -201,7 +286,7 @@ along with systemd; If not, see . Dump messages being exchanged. If SERVICE is specified, show messages to or from this endpoint. Otherwise, show all messages on the - bus. + bus. Use Ctrl-C to terminate dump. @@ -218,33 +303,54 @@ along with systemd; If not, see . - status SERVICE + tree SERVICE - Show process information and credentials of a - bus service. + Shows an object tree of one or more + services. If SERVICE is specified, + show object tree of the specified services only. Otherwise, + show all object trees of all services on the bus that acquired + at least one well-known name. + + + + introspect SERVICE OBJECT + + Show interfaces, methods, properties and + signals of the specified object (identified by its path) on + the specified service. - call SERVICE OBJECT INTERFACE METHOD SIGNATURE PARAMETERS + call SERVICE OBJECT INTERFACE METHOD SIGNATURE ARGUMENT Invoke a method and show the response. Takes a service name, object path, interface name and method name. If parameters shall be passed to the method call a signature - string is required, followed by the individual parameters, - individually formatted as textual arguments. + string is required, followed by the arguments, individually + formatted as strings. For details on the formatting used, see + below. To suppress output of the returned data use the + option. - get-property SERVICE OBJECT INTERFACE PROPERTIES - - Retrieve the current value one or more object - properties. Takes a service name and object path. Optionally - takes an interface name and property name. If the property - name is omited, shows all properties on the selected - interface. If the interface is also omitted shows the - properties of all interfaces. Multiple properties may be + get-property SERVICE OBJECT INTERFACE PROPERTY + + Retrieve the current value of one or more + object properties. Takes a service name, object path, + interface name and property name. Multiple properties may be specified at once in which case their values will be shown one - after the other. + after the other, separated by newlines. The output is by + default in terse format. Use for a + more elaborate output format. + + + + set-property SERVICE OBJECT INTERFACE PROPERTY SIGNATURE ARGUMENT + + Set the current value an object + property. Takes a service name, object path, interface name, + property name, property signature, followed by a list of + parameters formatted as strings. @@ -255,6 +361,113 @@ along with systemd; If not, see . + + Parameter Formatting + + The call and + set-property commands take a signature string + followed by a list of parameters formatted as string (for details + on D-Bus signature strings see the Type + system chapter of the D-Bus specification). For simple + types each parameter following the signature should simply be the + parameter's value formatted as string. Positive boolean values may + be formatted as true, yes, + on, 1; negative boolean + values may be specified as false, + no, off, + 0. For arrays, a numeric argument for the + number of entries followed by the entries shall be specified. For + variants the signature of the contents shall be specified, + followed by the contents. For dictionaries and structs the + contents of them shall be directly specified. + + For example, + s jawoll is the formatting + of a single string jawoll. + + + as 3 hello world foobar + is the formatting of a string array with three entries, + hello, world and + foobar. + + + a{sv} 3 One s Eins Two u 2 Yes b true + is the formatting of a dictionary + array that maps strings to variants, consisting of three + entries. The string One is assigned the + string Eins. The string + Two is assigned the 32bit unsigned + integer 2. The string Yes is assigned a + positive boolean. + + Note that the call, + get-property, introspect + commands will also generate output in this format for the returned + data. Since this format is sometimes too terse to be easily + understood, the call and + get-property commands may generate a more + verbose, multi-line output when passed the + option. + + + + Examples + + + Write and Read a Property + + The following two commands first write a property and then + read it back. The property is found on the + /org/freedesktop/systemd1 object of the + org.freedesktop.systemd1 service. The name of + the property is LogLevel on the + org.freedesktop.systemd1.Manager + interface. The property contains a single string: + + # 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" + + + + + Terse and Verbose Output + + The following two commands read a property that contains + an array of strings, and first show it in terse format, followed + by verbose format: + + $ busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment +as 2 "LANG=en_US.UTF-8" "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.UTF-8"; + STRING "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"; +}; + + + + Invoking a Method + + The following command invokes a the + StartUnit method on the + org.freedesktop.systemd1.Manager + interface of the + /org/freedesktop/systemd1 object + of the org.freedesktop.systemd1 + service, and passes it two strings + cups.service and + replace. As result of the method + call a single object path parameter is received and + shown: + + # busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager StartUnit ss "cups.service" "replace" +o "/org/freedesktop/systemd1/job/42684" + + + See Also