1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3                   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
4<!-- lifted from troff+man by doclifter -->
5<refentry id='dbussend1'>
6<!--   -->
7<!--  dbus\-send manual page. -->
8<!--  Copyright (C) 2003 Red Hat, Inc. -->
9
10<refmeta>
11<refentrytitle>dbus-send</refentrytitle>
12<manvolnum>1</manvolnum>
13</refmeta>
14<refnamediv id='name'>
15<refname>dbus-send</refname>
16<refpurpose>Send a message to a message bus</refpurpose>
17</refnamediv>
18<!-- body begins here -->
19<refsynopsisdiv id='synopsis'>
20<cmdsynopsis>
21  <command>dbus-send</command>
22    <group choice='opt'><arg choice='plain'>--system </arg><arg choice='plain'>--session </arg></group>
23    <arg choice='opt'>--dest=<replaceable>NAME</replaceable></arg>
24    <arg choice='opt'>--print-reply </arg>
25    <arg choice='opt'>--type=<replaceable>TYPE</replaceable></arg>
26    <arg choice='plain'><replaceable>&lt;destination</replaceable></arg>
27    <arg choice='plain'><replaceable>object</replaceable></arg>
28    <arg choice='plain'><replaceable>path&gt;</replaceable></arg>
29    <arg choice='plain'><replaceable>&lt;message</replaceable></arg>
30    <arg choice='plain'><replaceable>name&gt;</replaceable></arg>
31    <arg choice='opt' rep='repeat'><replaceable>contents</replaceable></arg>
32    <sbr/>
33</cmdsynopsis>
34</refsynopsisdiv>
35
36
37<refsect1 id='description'><title>DESCRIPTION</title>
38<para>The <command>dbus-send</command> command is used to send a message to a D-Bus message
39bus. See <ulink url='http://www.freedesktop.org/software/dbus/'>http://www.freedesktop.org/software/dbus/</ulink> for more
40information about the big picture.</para>
41
42
43<para>There are two well-known message buses: the systemwide message bus
44(installed on many systems as the "messagebus" service) and the
45per-user-login-session message bus (started each time a user logs in).
46The --system and --session options direct <command>dbus-send</command> to send
47messages to the system or session buses respectively.  If neither is
48specified, <command>dbus-send</command> sends to the session bus.</para>
49
50
51<para>Nearly all uses of <command>dbus-send</command> must provide the --dest argument
52which is the name of a connection on the bus to send the message to. If
53--dest is omitted, no destination is set.</para>
54
55
56<para>The object path and the name of the message to send must always be
57specified. Following arguments, if any, are the message contents
58(message arguments).  These are given as type-specified values and
59may include containers (arrays, dicts, and variants) as described below.</para>
60
61<literallayout remap='.nf'>
62&lt;contents&gt;   ::= &lt;item&gt; | &lt;container&gt; [ &lt;item&gt; | &lt;container&gt;...]
63&lt;item&gt;       ::= &lt;type&gt;:&lt;value&gt;
64&lt;container&gt;  ::= &lt;array&gt; | &lt;dict&gt; | &lt;variant&gt;
65&lt;array&gt;      ::= array:&lt;type&gt;:&lt;value&gt;[,&lt;value&gt;...]
66&lt;dict&gt;       ::= dict:&lt;type&gt;:&lt;type&gt;:&lt;key&gt;,&lt;value&gt;[,&lt;key&gt;,&lt;value&gt;...]
67&lt;variant&gt;    ::= variant:&lt;type&gt;:&lt;value&gt;
68&lt;type&gt;       ::= string | int16 | uint 16 | int32 | uint32 | int64 | uint64 | double | byte | boolean | objpath
69</literallayout> <!-- .fi -->
70
71<para>D-Bus supports more types than these, but <command>dbus-send</command> currently
72does not.  Also, <command>dbus-send</command> does not permit empty containers
73or nested containers (e.g. arrays of variants).</para>
74
75
76<para>Here is an example invocation:</para>
77<literallayout remap='.nf'>
78
79  dbus-send --dest=org.freedesktop.ExampleName               \
80            /org/freedesktop/sample/object/name              \
81            org.freedesktop.ExampleInterface.ExampleMethod   \
82            int32:47 string:'hello world' double:65.32       \
83            array:string:"1st item","next item","last item"  \
84            dict:string:int32:"one",1,"two",2,"three",3      \
85            variant:int32:-8                                 \
86            objpath:/org/freedesktop/sample/object/name
87
88</literallayout> <!-- .fi -->
89
90<para>Note that the interface is separated from a method or signal
91name by a dot, though in the actual protocol the interface
92and the interface member are separate fields.</para>
93
94</refsect1>
95
96<refsect1 id='options'><title>OPTIONS</title>
97<para>The following options are supported:</para>
98<variablelist remap='TP'>
99  <varlistentry>
100  <term><option>--dest=NAME</option></term>
101  <listitem>
102<para>Specify the name of the connection to receive the message.</para>
103  </listitem>
104  </varlistentry>
105  <varlistentry>
106  <term><option>--print-reply</option></term>
107  <listitem>
108<para>Block for a reply to the message sent, and print any reply received.</para>
109  </listitem>
110  </varlistentry>
111  <varlistentry>
112  <term><option>--system</option></term>
113  <listitem>
114<para>Send to the system message bus.</para>
115  </listitem>
116  </varlistentry>
117  <varlistentry>
118  <term><option>--session</option></term>
119  <listitem>
120<para>Send to the session message bus.  (This is the default.)</para>
121  </listitem>
122  </varlistentry>
123  <varlistentry>
124  <term><option>--type=TYPE</option></term>
125  <listitem>
126<para>Specify "method_call" or "signal" (defaults to "signal").</para>
127
128  </listitem>
129  </varlistentry>
130</variablelist>
131</refsect1>
132
133<refsect1 id='author'><title>AUTHOR</title>
134<para>dbus-send was written by Philip Blundell.</para>
135
136</refsect1>
137
138<refsect1 id='bugs'><title>BUGS</title>
139<para>Please send bug reports to the D-Bus mailing list or bug tracker,
140see <ulink url='http://www.freedesktop.org/software/dbus/'>http://www.freedesktop.org/software/dbus/</ulink></para>
141</refsect1>
142</refentry>
143
144