| Emeric Vigier | 2f62582 | 2012-08-06 11:09:52 -0400 | [diff] [blame] | 1 | .\" |
| 2 | .\" dbus-send manual page. |
| 3 | .\" Copyright (C) 2003 Red Hat, Inc. |
| 4 | .\" |
| 5 | .TH dbus-send 1 |
| 6 | .SH NAME |
| 7 | dbus-send \- Send a message to a message bus |
| 8 | .SH SYNOPSIS |
| 9 | .PP |
| 10 | .B dbus-send |
| 11 | [\-\-system | \-\-session] [\-\-dest=NAME] [\-\-print-reply] |
| 12 | [\-\-type=TYPE] <destination object path> <message name> [contents ...] |
| 13 | |
| 14 | .SH DESCRIPTION |
| 15 | |
| 16 | The \fIdbus-send\fP command is used to send a message to a D-Bus message |
| 17 | bus. See http://www.freedesktop.org/software/dbus/ for more |
| 18 | information about the big picture. |
| 19 | |
| 20 | .PP |
| 21 | There are two well-known message buses: the systemwide message bus |
| 22 | (installed on many systems as the "messagebus" service) and the |
| 23 | per-user-login-session message bus (started each time a user logs in). |
| 24 | The \-\-system and \-\-session options direct \fIdbus-send\fP to send |
| 25 | messages to the system or session buses respectively. If neither is |
| 26 | specified, \fIdbus-send\fP sends to the session bus. |
| 27 | |
| 28 | .PP |
| 29 | Nearly all uses of \fIdbus-send\fP must provide the \-\-dest argument |
| 30 | which is the name of a connection on the bus to send the message to. If |
| 31 | \-\-dest is omitted, no destination is set. |
| 32 | |
| 33 | .PP |
| 34 | The object path and the name of the message to send must always be |
| 35 | specified. Following arguments, if any, are the message contents |
| 36 | (message arguments). These are given as type-specified values and |
| 37 | may include containers (arrays, dicts, and variants) as described below. |
| 38 | |
| 39 | .nf |
| 40 | <contents> ::= <item> | <container> [ <item> | <container>...] |
| 41 | <item> ::= <type>:<value> |
| 42 | <container> ::= <array> | <dict> | <variant> |
| 43 | <array> ::= array:<type>:<value>[,<value>...] |
| 44 | <dict> ::= dict:<type>:<type>:<key>,<value>[,<key>,<value>...] |
| 45 | <variant> ::= variant:<type>:<value> |
| 46 | <type> ::= string | int16 | uint 16 | int32 | uint32 | int64 | uint64 | double | byte | boolean | objpath |
| 47 | .fi |
| 48 | |
| 49 | D-Bus supports more types than these, but \fIdbus-send\fP currently |
| 50 | does not. Also, \fIdbus-send\fP does not permit empty containers |
| 51 | or nested containers (e.g. arrays of variants). |
| 52 | |
| 53 | .PP |
| 54 | Here is an example invocation: |
| 55 | .nf |
| 56 | |
| 57 | dbus-send \-\-dest=org.freedesktop.ExampleName \\ |
| 58 | /org/freedesktop/sample/object/name \\ |
| 59 | org.freedesktop.ExampleInterface.ExampleMethod \\ |
| 60 | int32:47 string:'hello world' double:65.32 \\ |
| 61 | array:string:"1st item","next item","last item" \\ |
| 62 | dict:string:int32:"one",1,"two",2,"three",3 \\ |
| 63 | variant:int32:-8 \\ |
| 64 | objpath:/org/freedesktop/sample/object/name |
| 65 | |
| 66 | .fi |
| 67 | |
| 68 | Note that the interface is separated from a method or signal |
| 69 | name by a dot, though in the actual protocol the interface |
| 70 | and the interface member are separate fields. |
| 71 | |
| 72 | .SH OPTIONS |
| 73 | The following options are supported: |
| 74 | .TP |
| 75 | .I "--dest=NAME" |
| 76 | Specify the name of the connection to receive the message. |
| 77 | .TP |
| 78 | .I "--print-reply" |
| 79 | Block for a reply to the message sent, and print any reply received. |
| 80 | .TP |
| 81 | .I "--system" |
| 82 | Send to the system message bus. |
| 83 | .TP |
| 84 | .I "--session" |
| 85 | Send to the session message bus. (This is the default.) |
| 86 | .TP |
| 87 | .I "--type=TYPE" |
| 88 | Specify "method_call" or "signal" (defaults to "signal"). |
| 89 | |
| 90 | .SH AUTHOR |
| 91 | dbus-send was written by Philip Blundell. |
| 92 | |
| 93 | .SH BUGS |
| 94 | Please send bug reports to the D-Bus mailing list or bug tracker, |
| 95 | see http://www.freedesktop.org/software/dbus/ |