D 2018-09-28T09:51:19.060
L Manual\spage
P 4f42a7d3fa95948eed010b13a38d3649480a20e43a072ce23e6c6dcbcc334c2a
U schelte
W 27661
<h1>Tcl DBus extension</h1>
<p>dbus - Tcl library for interacting with the DBus
<hr>
<h2>Synopsis</h2>
<p>
package require <b>Tcl 8.5</b><br>
package require <b>dbus 3.0</b><br>
<p>
[#1|<b>dbus</b> <b>call</b> ?<i>busID</i>? ?<b>-autostart</b> ?<i>boolean</i>?? ?<b>-dest</b> <i>target</i>? ?<b>-details</b> ?<i>boolean</i>?? ?<b>-handler</b> <i>script</i>? ?<b>-signature</b> <i>string</i>? ?<b>-timeout</b> <i>ms</i>? <i>path</i> <i>interface</i> <i>method</i> ?<i>arg</i> <i>...</i>?]<br>
[#2|<b>dbus</b> <b>close</b> ?<i>busID</i>?]<br>
[#3|<b>dbus</b> <b>connect</b> ?<i>address</i>?]<br>
[#4|<b>dbus</b> <b>error</b> ?<i>busID</i>? ?<b>-name</b> <i>string</i>? <i>destination</i> <i>serial</i> ?message?]<br>
[#5|<b>dbus</b> <b>filter</b> ?<i>busID</i>? <i>subcommand</i> <b>-option</b> <i>value</i> ?<i>...</i>?]<br>
[#6|<b>dbus</b> <b>info</b> ?<i>busID</i>? <i>option</i>]<br>
[#7|<b>dbus</b> <b>listen</b> ?<i>busID</i>? ?<b>-details</b>? ?<i>path</i> ?<i>member</i> ?<i>script</i>???]<br>
[#8|<b>dbus</b> <b>method</b> ?<i>busID</i>? ?<b>-details</b>? ?<i>path</i> ?<i>member</i> ?<i>script</i>???]<br>
[#9|<b>dbus</b> <b>monitor</b> ?<i>busID</i>? ?<b>-details</b>? <i>script</i>]<br>
[#10|<b>dbus</b> <b>name</b> ?<i>busID</i>? ?<b>-option</b> <i>...</i>? <i>name</i>]<br>
[#11|<b>dbus</b> <b>release</b> ?<i>busID</i>? <i>name</i>]<br>
[#12|<b>dbus</b> <b>return</b> ?<i>busID</i>? ?<b>-signature</b> <i>string</i>? <i>destination</i> <i>serial</i> ?<i>arg</i> <i>...</i>?]<br>
[#13|<b>dbus</b> <b>signal</b> ?<i>busID</i>? ?<b>-signature</b> <i>string</i>? <i>object</i> <i>interface</i> <i>name</i> ?<i>arg</i> <i>...</i>?]<br>
[#14|<b>dbus</b> <b>unknown</b> ?<i>busID</i>? ?<b>-details</b>? ?<i>path</i> ?<i>script</i>??]<br>
[#15|<b>dbus</b> <b>validate</b> <i>class</i> <i>string</i>]<br>
<hr>
<h2>Description</h2>
The <b>dbus</b> package provides commands to interact with DBus
message busses. There are three well-known bus names: <b class="const">session</b>,
<b class="const">system</b>, and <b class="const">starter</b>. The starter bus only applies when the
application has been started as a result of a method call from another
application. A connection to the starter bus will effectively be an
alternative connection to either the session or the system bus.
<p>
Most subcommands take a <i>busID</i> argument. This is the DBus handle as
returned by the <b>dbus</b> <b>connect</b> subcommand. For the
well-known busses the handle for the first connection matches the name of
the bus. If the <i>busID</i> argument is not specified, it defaults to
<b class="const">session</b>.
<dl>
<dt><a name="1"></a><b>dbus</b> <b>call</b> ?<i>busID</i>? ?<b>-autostart</b> ?<i>boolean</i>?? ?<b>-dest</b> <i>target</i>? ?<b>-details</b> ?<i>boolean</i>?? ?<b>-handler</b> <i>script</i>? ?<b>-signature</b> <i>string</i>? ?<b>-timeout</b> <i>ms</i>? <i>path</i> <i>interface</i> <i>method</i> ?<i>arg</i> <i>...</i>?
<dd>Send a method call onto the dbus and optionally wait for a reply.
If the signature of the DBus <b class="const">method_return</b> reply only contains one
top-level element, the arguments of the <b class="const">method_return</b> message are
returned as a single value. More complex structures are returned as a list.
<p>
If the response to the DBus <b class="const">method_call</b> message is a DBus
<b class="const">error</b> message, the command will produce an error. In that case the
errorCode variable will be set to <b class="const">DBUS</b> <b class="const">DBUS_MESSAGE_TYPE_ERROR</b>.
<p>
The <b>-autostart</b> option specifies whether the bus server should
attempt to start an associated application if the destination name does not
currently exist on the bus. <i>Boolean</i> may have any proper boolean value,
such as <b class="const">1</b> or <b class="const">no</b>. Defaults to 1 (true).
<p>
The <b>-timeout</b> option specifies the maximum time to wait for a
response. A negative timeout indicates that no response should be requested.
<p>
If a script is specified with the <b>-handler</b> option, the call will be
asynchronous. In that case the command returns the serial of the request.
The script will be executed when a response comes back or when there is an
error.
<p>
The <b>-signature</b> option defines the types of arguments to be sent on
the dbus. See the <b>Signatures</b> section for more information.
If no signature is specified, all arguments will be sent as strings.
<p>
The <b>-details</b> option specifies how variant arguments in the return
value are represented. With the default value of FALSE, only the value of a
variant argument is provided. But in some situations the Tcl code may need
to be able to also obtain the argument type. When this option is set to TRUE,
each variant argument is represented as a list with two elements. The first
list element contains the signature of the argument and the second list
element is the value.
<p>
<dt><a name="2"></a><b>dbus</b> <b>close</b> ?<i>busID</i>?
<dd>Close the connection to the DBus. This will cleanup all handlers, listeners,
and the optional monitor script registered for the <i>busID</i>.
<p>
<dt><a name="3"></a><b>dbus</b> <b>connect</b> ?<i>address</i>?
<dd>Connect to the DBus. The <i>address</i> argument specifies the bus to connect
to. This can be either one of the well-known busses ('session', 'system' or
'starter'), or a transport name followed by a colon, and then an optional,
comma-separated list of keys and values in the form key=value.
The command returns a handle that can be used as the <i>busID</i> argument
in other dbus commands.
<p>
It is possible to create multiple connections to the same DBus. But that should
normally be avoided, unless there is a good reason. One good reason would be if
the program uses normal DBus operations, but also needs to monitor the traffic
on the DBus using the BecomeMonitor method.
<p>
<dt><a name="4"></a><b>dbus</b> <b>error</b> ?<i>busID</i>? ?<b>-name</b> <i>string</i>? <i>destination</i> <i>serial</i> ?message?
<dd>Send a DBus <b class="const">error</b> message with the specified <i>serial</i> and
<i>destination</i>. If the <b>-name</b> option is not specified, it
defaults to "org.freedesktop.DBus.Error.Failed".
The values for <i>destination</i> and <i>serial</i> can be obtained from event
information fields 'sender' and 'serial' correspondingly.
See <b>Event Handlers</b> below for more information.
<p>
When employing this subcommand, make sure the result of the
<b>dbus</b> <b>method</b> script isn't automatically returned
to the caller by using the <b>-async</b> option of the <b>return</b>
command. See <b>dbus</b> <b>method</b> for more information.
<p>
<dt><a name="5"></a><b>dbus</b> <b>filter</b> ?<i>busID</i>? <i>subcommand</i> <b>-option</b> <i>value</i> ?<i>...</i>?
<dd>The <b>add</b> subcommand adds a match rule to match messages going through
the message bus. The <b>remove</b> subcommand removes the most recently
added rule that exactly matches the specified option settings. If there is no
matching rule, the command is silently ignored. Available options are:
<b>-destination</b>, <b>-eavesdrop</b>, <b>-interface</b>,
<b>-member</b>, <b>-path</b>, <b>-sender</b>, and <b>-type</b>.
The command returns the match rule passed to libdbus.
<p>
<dt><a name="6"></a><b>dbus</b> <b>info</b> ?<i>busID</i>? <i>option</i>
<dd>The info command can be used to obtain information about the DBus.
Available <b>info</b> options are:
<dl>
<dt><b><b>capabilities</b></b>
<dd>Returns a dict describing the capabilities of
the dbus connection. Currently only one capability has been defined: unixfd,
which indicates if file descriptor passing is supported on the dbus connection.
<dt><b><b>local</b></b>
<dd>The object path used in local/in-process-generated
messages (<b class="const">/org/freedesktop/DBus/Local</b>).
<dt><b><b>machineid</b></b>
<dd>Get the UUID of the local machine.
<dt><b><b>name</b></b>
<dd>Get the unique name of the connection as assigned by
the message bus.
<dt><b><b>path</b></b>
<dd>The object path used to talk to the bus itself
(<b class="const">/org/freedesktop/DBus</b>).
<dt><b><b>pending</b></b>
<dd>Report if any messages are in the queue to be sent.
<dt><b><b>serverid</b></b>
<dd>Get the UUID of the server we are authenticated to.
<dt><b><b>service</b></b>
<dd>The bus name used to talk to the bus itself
(<b class="const">org.freedesktop.DBus</b>).
<dt><b><b>version</b></b>
<dd>Returns the version of libdbus.
</dl>
<p>
<dt><a name="7"></a><b>dbus</b> <b>listen</b> ?<i>busID</i>? ?<b>-details</b>? ?<i>path</i> ?<i>member</i> ?<i>script</i>???
<dd>Register a <i>script</i> to be called when the signal named "<i>member</i>" at
<i>path</i> appears on the DBus.
See <b>Event Handlers</b> below for more information.
<p>
If the <i>path</i> argument is an empty string, <i>script</i> will be executed
whenever a signal message is received for any path, unless a dedicated
listener for the exact path has been defined.
The <i>member</i> argument may be specified as either a signal name or an
interface and signal name joined by a period. If no interface is specified,
the script will be called for signals with any interface.
<p>
If <i>script</i> is an empty string, the currently registered command for the
specified signal and path will be unregistered.
If the <i>script</i> argument is not specified, the currently registered
command for the specified signal and path, if any, is returned.
If no <i>member</i> argument is specified a list of all registered signals
and associated commands at the specified path is returned.
If no <i>path</i> argument is specified a list of all paths and their
registered signals and associated commands is returned.
<p>
The <b>-details</b> option causes variant arguments to be represented as a
list with two elements: The first list element contains the signature of the
argument and the second list element is the value.
<p>
<dt><a name="8"></a><b>dbus</b> <b>method</b> ?<i>busID</i>? ?<b>-details</b>? ?<i>path</i> ?<i>member</i> ?<i>script</i>???
<dd>Register a <i>script</i> to be called when method <i>member</i> is invoked at
the specified <i>path</i>.
See <b>Event Handlers</b> below for more information.
<p>
If the <i>path</i> argument is an empty string, <i>script</i> will be executed
whenever a method call message is received for any path, unless a dedicated
method handler for the exact path has been defined.
The <i>member</i> argument may be specified as either a method name or an
interface and method name joined by a period. If no interface is specified,
the script will be called for methods with any interface, unless another
handler is specified for the method including the interface.
If <i>script</i> is an empty string, the currently registered command for the
specified method and path will be unregistered.
<p>
If the <i>script</i> argument is not specified, the currently registered
command for the specified method and path, if any, is returned.
If no <i>member</i> argument is specified a list of all registered methods
and associated commands at the specified path is returned.
If no <i>path</i> argument is specified a list of all paths and their
registered methods and associated commands is returned.
<p>
When <i>script</i> is evaluated, the return value of the script will normally
be returned to the caller using a DBus <b class="const">method_return</b> message in a
string argument.
If the execution of <i>script</i> ends with an error, the error message is
returned to the caller in a DBus <b class="const">error</b> message. Any DBus errors that
happen while sending these messages back to the caller are silently ignored.
If the caller specified the <b class="const">no_reply</b> flag in the <b class="const">method_call</b>
as TRUE, no <b class="const">method_return</b> or <b class="const">error</b> message will be returned.
<p>
The script code recognizes an additional <b>-async</b> option for the Tcl
<b>return</b> command. When that option is specified with a true boolean
value (<b class="const">true</b>, <b class="const">yes</b>, <b class="const">1</b>), the return value from the body
will not automatically be returned to the caller. A response message should
then be generated using the <b>dbus</b> <b>return</b> or
<b>dbus</b> <b>error</b> subcommands.
<p>
This method provides more advanced control over the returned messages. It
allows for more complex data structures than just a string to be returned.
It also makes it possible to generate a return message some time after
<i>script</i> has already finished. Additionally, any dbus errors while
sending back the return message can be detected and handled.
<p>
The <b>-details</b> option causes variant arguments to be represented as a
list with two elements: The first list element contains the signature of the
argument and the second list element is the value.
<p>
<dt><a name="9"></a><b>dbus</b> <b>monitor</b> ?<i>busID</i>? ?<b>-details</b>? <i>script</i>
<dd>Register a <i>script</i> to be executed when any DBus message is received.
See <b>Event Handlers</b> below for more information.
<p>
This can be useful for building special purpose programs that need to see
all activity on the DBus, for example a DBus monitoring program.
If <i>script</i> is an empty string, the currently configured monitor script
will be removed.
<p>
The <b>-details</b> option causes variant arguments to be represented as a
list with two elements: The first list element contains the signature of the
argument and the second list element is the value.
<p>
<dt><a name="10"></a><b>dbus</b> <b>name</b> ?<i>busID</i>? ?<b>-option</b> <i>...</i>? <i>name</i>
<dd>Request the bus to assign a given name to the connection. The command will
generate an error in all cases where it was unsuccessful in making the
application the primary owner of the name.
<p>
The <b>-yield</b> option specifies that the application will release the
requested name when some other application requests the same name and has
indicated that it wants to take over ownership of the name. The application
will be informed by a <em>NameLost</em> signal when it loses ownership of the
name.
The following command can be used to exit the application when the name is
taken over by another process:
<pre class="example">
dbus listen [dbus info path] [dbus info service].NameLost \
[list apply {{name info str} {if {$str eq $name} exit}} $name]
</pre>
The <b>-replace</b> option indicates that the application wants to take
over the ownership of the name from the application that is currently the
primary owner, if any. This request will only be honoured if the current
owner has indicated that it will release the name on request.
See also the <b>-yield</b> option.
<p>
If the requested name is currently in use and the <b>-replace</b> option
has not been specified, or the <b>-replace</b> option was specified but
the current owner is unwilling to give up its ownership, the name request
will normally be queued. Then when the name is released by current owner it
is assigned to the next requester in the queue and a signal is sent to inform
that requester that it is now the primary owner of the name.
The <b>-noqueue</b> option may be specified to indicate that the name
request should not be queued.
<p>
Note that even if the request has been queued, the command will generate an
error because the goal of becoming the primary owner of the name has not
been achieved.
<p>
<dt><a name="11"></a><b>dbus</b> <b>release</b> ?<i>busID</i>? <i>name</i>
<dd>Asks the bus to unassign the given name from this connection.
<p>
<dt><a name="12"></a><b>dbus</b> <b>return</b> ?<i>busID</i>? ?<b>-signature</b> <i>string</i>? <i>destination</i> <i>serial</i> ?<i>arg</i> <i>...</i>?
<dd>Send a DBus <b class="const">method_return</b> message with the specified <i>serial</i>
and <i>destination</i>.
The values for <i>destination</i> and <i>serial</i> can be obtained from event
information fields 'sender' and 'serial' correspondingly.
See <b>Event Handlers</b> below for more information.
<p>
When employing this subcommand, make sure the result of the
<b>dbus</b> <b>method</b> script isn't automatically returned
to the caller by using the <b>-async</b> option of the <b>return</b>
command. See <b>dbus</b> <b>method</b> for more information.
<p>
<dt><a name="13"></a><b>dbus</b> <b>signal</b> ?<i>busID</i>? ?<b>-signature</b> <i>string</i>? <i>object</i> <i>interface</i> <i>name</i> ?<i>arg</i> <i>...</i>?
<dd>Send a signal onto the dbus with the specified type signature. If no
<b>-signature</b> option is provided, all <i>arg</i>s will be sent as
strings. The command returns the serial number of the dbus message.
<p>
<dt><a name="14"></a><b>dbus</b> <b>unknown</b> ?<i>busID</i>? ?<b>-details</b>? ?<i>path</i> ?<i>script</i>??
<dd>Register a <i>script</i> to be called when an unknown method is invoked at
the specified <i>path</i>.
See <b>Event Handlers</b> below for more information.
<p>
If the <i>path</i> argument is an empty string, <i>script</i> will be executed
whenever an unknown method call message is received for any path, unless a
dedicated unknown handler for the exact path has been defined.
If <i>script</i> is an empty string, the currently registered command for the
specified path will be unregistered.
<p>
If the <i>script</i> argument is not specified, the currently registered
command for the specified path, if any, is returned.
If no <i>path</i> argument is specified, a list of all paths and their
registered unknown handlers is returned.
<p>
An unknown handler will usually return an error, but it is also possible to
return a non-error response. The <b>dbus</b> <b>error</b> and
<b>dbus</b> <b>return</b> subcommands should be used for this
purpose.
Contrary to the <b>dbus</b> <b>method</b> subcommand, the return
value of the handler will not automatically be returned to the caller.
Any uncaught error in the evaluation of <i>script</i> will be reported back
to the caller.
<p>
The <b>-details</b> option causes variant arguments to be represented as a
list with two elements: The first list element contains the signature of the
argument and the second list element is the value.
<p>
It will generally not be necessary to set up unknown handlers. If no unknown
handler is specified, the package returns an
<b class="const">org.freedesktop.dbus.error.unknownmethod</b> error back to the caller of
an unknown method.
<p>
<dt><a name="15"></a><b>dbus</b> <b>validate</b> <i>class</i> <i>string</i>
<dd>Validates <i>string</i> against the rules of the D-Bus specification for
the type of value specified by <i>class</i>. Returns 1 if validation passes,
otherwise returns 0. The following classes are recognized (the class name
can be abbreviated):
<dl>
<dt><b class="const">interface</b>
<dd>Two or more dot-separated non-empty elements.
Each element only contains the ASCII characters
"[A-Z][a-z][0-9]_" and does not begin with a digit.
<dt><b class="const">member</b>
<dd>A string that only contains the ASCII characters
"[A-Z][a-z][0-9]_" and does not begin with a digit.
<dt><b class="const">name</b>
<dd>Either a unique connection name, or a well-known
connection name. Unique connection names begin with a colon and consist of
at least two dot-separated non-empty elements. Each element only contains
the ASCII characters "[A-Z][a-z][0-9]_".
Well-known connection names consist of at least two dot-separated
non-empty elements. Each element only contains the ASCII characters
"[A-Z][a-z][0-9]_" and does not begin with a digit.
<dt><b class="const">path</b>
<dd>A slash followed by zero or more slash-separated
non-empty elements. Each element only contains the ASCII characters
"[A-Z][a-z][0-9]_".
<dt><b class="const">signature</b>
<dd>A valid D-Bus message type signature. See
<b>Signatures</b> below for more information on what constitutes a
valid signature.
</dl>
<p>
</dl>
<h2>Event Handlers</h2>
The <b>call</b>, <b>listen</b>, <b>method</b>, <b>monitor</b>, and
<b>unknown</b> methods provide the ability to define event handlers. The
specified script will be used as the prefix for a command that will be
evaluated whenever the corresponding DBus event occurs. When the DBus event
occurs, a Tcl command will be generated by concatenating the script with one
or more arguments. The first argument is a dict containing information about
the event. If the DBus event contained any arguments they will be appended to
the command as seperate arguments.
<p>
The dict with the event details contains the following information:
<dl>
<dt>member
<dd>The interface member being invoked (for methods) or emitted
(for signals).
<dt>interface
<dd>The interface this message is being sent to (for methods)
or being emitted from (for signals). The interface name is fully-qualified.
<dt>path
<dd>The object path this message is being sent to (for methods) or
being emitted from (for signals).
<dt>sender
<dd>The unique name of the connection which originated this message,
or the empty string if unknown or inapplicable. The sender is filled in by
the message bus. Note, the returned sender is always the unique bus name.
Connections may own multiple other bus names, but those are not found in the
sender field.
<dt>destination
<dd>The destination of a message or the empty string if there
is none set.
<dt>messagetype
<dd>The type of a message. Possible values are
<b class="const">method_call</b>, <b class="const">method_return</b>, <b class="const">error</b>, and <b class="const">signal</b>.
<dt>signature
<dd>The type signature of the message, i.e. the type specification
of the arguments in the message payload. See <b>Signatures</b> below for
more information.
<dt>serial
<dd>The serial of a message or 0 if none has been specified. The
message's serial number is provided by the application sending the message
and is used to identify replies to this message. All messages received on a
connection will have a serial provided by the remote application. When
sending messages a serial will automatically be assigned by the dbus
library.
<dt>replyserial
<dd>The serial that the message is a reply to or 0 if none.
<dt>noreply
<dd>Flag indicating if the sender expects a reply. Set to 1 if a
reply is <em>not</em> required.
<dt>autostart
<dd>Flag indicating if the message will cause an owner for
destination name to be auto-started.
<dt>errorname
<dd>The error name of a received error message. An empty string
for all other message types.
</dl>
The event handlers are excuted at global level (outside the context of any
Tcl procedure) in the interpreter in which the event handler was installed.
<h2>Signatures</h2>
The DBus specification defines typed arguments. This doesn't fit well with
the Tcl philosophy of <i class="term">everything is a string</i>. To be able to closely
control the type of the arguments to be sent onto the DBus a <b class="const">signature</b>
can be supplied. The signature definition is exactly the same as in the DBus
specification. A signature is a string where a single character or group of
characters specifies the type of an argument. The following types exist:
<dl>
<dt>s
<dd>A UTF-8 encoded, nul-terminated Unicode string.
<dt>b
<dd>A boolean, FALSE (0), or TRUE (1).
<dt>y
<dd>A byte (8-bit unsigned integer).
<dt>n
<dd>A 16-bit signed integer.
<dt>q
<dd>A 16-bit unsigned integer.
<dt>i
<dd>A 32-bit signed integer.
<dt>u
<dd>A 32-bit unsigned integer.
<dt>x
<dd>A 64-bit signed integer.
<dt>t
<dd>A 64-bit unsigned integer.
<dt>d
<dd>An 8-byte double in IEEE 754 format.
<dt>h
<dd>A file descriptor.
<dt>g
<dd>A type signature.
<dt>o
<dd>An object path.
<dt>a#
<dd>A D-Bus array type, which is similar to a Tcl list. The # specifies
the type of the array elements. This can be any type, including another
array, a struct or a dict entry.
<dt>v
<dd>A D-Bus variant type. The provided value should be a two-element list,
containing a signature and the actual value. See <b>Variant Arguments</b>
for more information.
<dt>(...)
<dd>A struct. The string inside the parentheses defines the types of
the arguments within the struct, which may consist of a combination of any
of the existing types.
<dt>{##}
<dd>A dict entry. Dict entries may only occur as array elements. The
first # specifies the type of the dict key. This must be a basic type
(one of 'sbynqiuxtdgo'). The second # specifies the type of the dict value.
This can again be any existing type.
</dl>
<em>Example</em>: The signature 'vaas(id)a{i(ss)}' specifies four arguments and
translates to Tcl terminology as follows: The type of the first argument
('v') is extracted from its value. The second argument ('aas') is a list
containing lists of strings. The third argument ('(id)') is a list containing
an integer and a double. The last argument ('a{i(ss)}') is a dict (an array
of dict entries) with integer keys and each value is a list of two strings.
<div id="subsection1" class="subsection"><h3>Variant Arguments</h3>
When a signature specifies that an argument is of type "variant", the
argument can still be almost anything. Additional information needs to be
located to determine how to package the value for transmission onto the
dbus. The preferred way is for the argument to be a two-element list where
the first element specifies the signature for the value and the second
element is the actual value.
<p>
The signature for a variant argument has to specify a single complete type.
The value of the second list element must match the signature, otherwise an
error will be reported.
<p>
If the value provided for a variant argument is not a two-element list, or
the first element is not a valid signature for a single complete type, the
code will attempt to automatically determine the type of the provided value.
It does this by selecting a signature based on the internal representation
of the value according to the following table:
<dl>
<dt>string: s
<dd>
<dt>int: i
<dd>
<dt>wideInt: x
<dd>
<dt>double: d
<dd>
<dt>boolean: b
<dd>
<dt>list: as
<dd>
<dt>dict: a{ss}
<dd>
<dt>anything else: s
<dd>
</dl>
</div>
<div id="subsection2" class="subsection"><h3>File descriptors</h3>
On output, the value provided for a file handler argument must be an open Tcl
channel (such as has been created with the open or socket commands). An error
will be thrown if the value does not represent an open channel, or if the dbus
connection does not support passing file handler arguments.
<p>
On input, a new channel will be created and its name passed to the script. The
new channel is opened for both reading and writing. If this is not desired,
either direction may be closed using the appropriate half-close version of the
close command.
<p>
The channel name is likely to be different in the two involved applications.
When finished with the channel, both parties are responsible for closing the
channel using their own channel reference.
</div>
Z a9c6663dc7cc5a20036a5099fcbf8b33