KSH93 Bit Manipulation

When programmers think about bitwise manipulation, they usually think about using C or C++ to solve their problem since both programming languages provide a rich set of features which make it easy to perform bitwise manipulation.

However it is possible to just as easily perform such operations using the ksh93 shell.  This post will explain what bitwise manipulation and number conversion facilities are available in ksh93 and provide some hopefully useful utilities and examples.

Many programmers are unaware that ksh93 has builtin support for different numeral radices (AKA arithmetic bases) as shown in the following example.

$ print $(( 10 + 20 ))
30
$ print $(( 2#10 + 20 ))
22
$ print $(( 2#10 + 4#20 ))
10
$

where base 2 is denoted by 2#, base 4 by #4 and so on.  The general case syntax is [base#]n where base is a decimal number between 2 and 36 representing the arithmetic base and n is a number in that base.  You can mix and match bases within expressions.  As you would expect, the default base, i.e. if [base#] is omitted, is decimal(10).

Here is an example of how to convert decimal 255 to base 2, base 8 and base 16 respectively using the typeset command.

$ typeset -i2 a=255
$ echo $a
2#11111111
$ typeset -i8 a=255
$ echo $a
8#377
$ typeset -i16 a=255
$ echo $a
16#ff
$

Note that ksh93 displays the base prefix before each number unless it is a decimal number, i.e. base 10. 

The bitwise manipulation operators in ksh93 are AND, OR, XOR, SHIFT LEFT and SHIFT RIGHT.  There are no SHIFT ROTATE or COMPLEMENT operators.  The following is the list of supported bitwise operators in decreasing order of precedence which, by the way, is the same as in the C programming language.

<< >>	Bitwise shift left, shift right
&	Bitwise AND
^	Bitwise XOR
|	Bitwise OR

The following shell script includes both logical and bitwise operators together with the expected output for each statement.  Notice the difference in output between a logical and bitwise operator.

#!/bin/ksh93

integer -i2 a=5
integer -i2 b=6

# expected output 1
print $(( a < b ))
# expected output 0
print $(( a > b ))
# expected output 3
print $(( a ^ b ))
# expected output 4
print $(( a & b ))
# expected output 1
print $(( a && b ))
# expected output 7
print $(( a | b ))
# expected output 1
print $(( a || b ))

A useful feature of bitwise operators is that by using the shift left and shift right bitwise operators you can mimic multiplication or division by 2 or a power of 2.

$ x=4
$ print $((x << 1))
8
$ print $(( x << 2 ))
16
$ print $(( x >> 1 ))
2
$ print $(( x >> 2 ))
1

Here is a fairly simple shell script which uses numeric base conversion and bitwise operators to calculate the network and broadcast addresses for a given IP address and subnet mask.

#!/bin/ksh93

typeset -i2 mask=255

[[ $# != 2 ]] && {
   echo "Usage: $0 ipaddress subnetmask"
   exit 1
}

SaveIFS=$IFS
IFS=.
typeset -a IParr=($1)
typeset -a NMarr=($2)
IFS=$SaveIFS

typeset -i2 ip1=${IParr[0]}
typeset -i2 ip2=${IParr[1]}
typeset -i2 ip3=${IParr[2]}
typeset -i2 ip4=${IParr[3]}

typeset -i2 nm1=${NMarr[0]}
typeset -i2 nm2=${NMarr[1]}
typeset -i2 nm3=${NMarr[2]}
typeset -i2 nm4=${NMarr[3]}

echo
echo "       IP Address: $1"
echo "      Subnet Mask: $2"
echo "  Network Address: $((ip1 & nm1)).$((ip2 & nm2)).$((ip3 & nm3)).$((ip4 & nm4))"
echo "Broadcast Address: $((ip1 | (mask ^ nm1))).$((ip2 | (mask ^ nm2))).$((ip3 | (mask ^ nm3))).$(( ip4 | (mask ^ nm4)))"
echo

exit 0

Some sample output for this script.

$ ./calculate-address 10.150.12.1 255.255.255.0

       IP Address: 10.150.12.1
      Subnet Mask: 255.255.255.0
  Network Address: 10.150.12.0
Broadcast Address: 10.150.12.255

$ ./calculate-address 10.150.12.1 255.255.254.0

       IP Address: 10.150.12.1
      Subnet Mask: 255.255.254.0
  Network Address: 10.150.12.0
Broadcast Address: 10.150.13.255

The next example calculates the network and broadcast addresses for a Classless Inter-Domain Routing (CIDR) compliant IP address.  Note the use of the shift right operator in calculating the network mask.

#!/bin/ksh93

[[ $# != 1 ]] && {
   echo "Usage: $0 ipaddress/netmask"
   exit 1
}

SaveIFS=$IFS
IFS="./"
typeset -a IParr=($1)
IFS=$SaveIFS

typeset -i2 ip1=${IParr[0]}
typeset -i2 ip2=${IParr[1]}
typeset -i2 ip3=${IParr[2]}
typeset -i2 ip4=${IParr[3]}
typeset -i2 cidr=${IParr[4]}

typeset -i2 nm1=0 nm2=0 nm3=0 nm4=0

typeset -i quad=$(( cidr / 8 ))
sigbits=$(( cidr % 8 ))
if (( sigbits != 0 )); then
   slot=$(( 256 - ( 256 >> $sigbits ) ))
fi

for (( i=1; i < 5; i++ ))
do
   nameref nm=nm${i}
   if (( quad != 0 )); then
      nm=255
      (( --quad ))
   elif (( quad == 0 )); then
      nm=slot
      break
   fi
done

typeset -i2 mask=255

print
print "           IP Address: $((ip1)).$((ip2)).$((ip3)).$((ip4))"
print "    CIDR Netmask Mask: $((nm1)).$((nm2)).$((nm3)).$((nm4))"
print " CIDR Network (Route): $((ip1 & nm1)).$((ip2 & nm2)).$((ip3 & nm3)).$((ip4 & nm4))"
print "    Broadcast Address: $((ip1 | (mask ^ nm1))).$((ip2 | (mask ^ nm2))).$((ip3 | (mask ^ nm3))).$((ip4 | (mask ^ n
m4)))"
print

exit 0

Sample output:

$ ./calculate-address "192.168.21.12/18"

           IP Address: 192.168.21.12
    CIDR Network Mask: 255.255.192.0
 CIDR Network (Route): 192.168.0.0
    Broadcast Address: 192.168.63.255

While both the bash and zsh shells also provide a full set of bitwise operators, only ksh93 and zsh with their builtin support for numeric base conversions makes such bitwise operators truly useful in shell scripts.
 

Monitoring D-Bus

Because D-Bus operates for the most part under the hood invisible to the user, means of monitoring D-Bus messages is important for both activation and debugging purposes.  In this post I examine how to monitor and act on such messages.  I assume that you are relatively familiar with D-Bus.  If not, you should look at my previous posts on D-Bus to gain an understanding of the basic concepts.

Probably the most commonly used tool is the command line utility dbus-monitor which was written by Philip Blundell as part of the reference D-Bus implementation and which is standard on most D-Bus enabled platforms.  It is a very powerful utility but unfortunately it's man page is terse and fails to explain the most powerful feature of dbus-monitor i.e. watch expressions.

Suppose, for example, I want to monitor the creation, saving and deletion of Tomboy notes using D-Bus signals.  To get the list of the supported signals I could introspect Tomboy using qdbus i.e.

$ qdbus org.gnome.Tomboy /org/gnome/Tomboy/RemoteControl | grep signal
signal void org.gnome.Tomboy.RemoteControl.NoteAdded(QString uri)
signal void org.gnome.Tomboy.RemoteControl.NoteDeleted(QString uri, QString title)
signal void org.gnome.Tomboy.RemoteControl.NoteSaved(QString uri)
$

or I could use dbus-monitor to look at the signals generated when Tomboy creates, saves and deletes a note.

$ dbus-monitor type=signal interface="org.gnome.Tomboy.RemoteControl"
signal sender=org.freedesktop.DBus -> dest=:1.102 path=/org/freedesktop/DBus; interface=org.freedesktop.DBus; member=NameAcquired
   string ":1.102"
signal sender=:1.63 -> dest=(null destination) path=/org/gnome/Tomboy/RemoteControl; interface=org.gnome.Tomboy.RemoteControl; member=NoteAdded
   string "note://tomboy/0ae6b0b3-9394-44e9-ad4a-46726e68cebc"
signal sender=:1.63 -> dest=(null destination) path=/org/gnome/Tomboy/RemoteControl; interface=org.gnome.Tomboy.RemoteControl; member=NoteSaved
   string "note://tomboy/0ae6b0b3-9394-44e9-ad4a-46726e68cebc"
signal sender=:1.63 -> dest=(null destination) path=/org/gnome/Tomboy/RemoteControl; interface=org.gnome.Tomboy.RemoteControl; member=NoteDeleted
   string "note://tomboy/0ae6b0b3-9394-44e9-ad4a-46726e68cebc"
   string "New Note 1"
$

As you can see Tomboy issues three signals - NoteAdded when a note is added, NoteSaved when a note is saved, and NoteDeleted when a note is deleted.  Interestingly, for some reason NoteDeleted provides both the uri and the title of the note whereas the other two signals only provide the uri.

Suppose I just want to to monitor when a Tomboy note is saved by a user.  I can use a dbus-monitor watch expression for this purpose as shown in the following example.

dbus-monitor "type='signal',sender='org.gnome.Tomboy',interface='org.gnome.Tomboy.RemoteControl',path='/org/gnome/Tomboy/RemoteControl',member='NoteSaved'"

A watch expression is essentially a message filter.  Note the syntax!  Everything between the two double quotes is part of the watch expression.

Unfortunately the syntax of a watch expression is not documented in the dbus-monitor man page.  However from looking at the source code for dbus-monitor, it appears that a watch expression consists of one or more name-value pairs, e.g. sender='org.gnome.Tomboy' separated by commas.  The following are valid names: type, sender, destination, path, interface, member and error_name.  The value of type must be one of the following: signal, method_call, method_return or error. 

Probably the most powerful feature of dbus-monitor is the fact that you are not limited to using just one watch expression at a time.  The following example simultaneously monitors all 3 Tomboy signals and uses awk to parse the output from dbus-monitor and display a meaningful message.

#!/bin/bash

OJECT="'org.gnome.Tomboy'"
IFACE="'org.gnome.Tomboy.RemoteControl'"
DPATH="'/org/gnome/Tomboy/RemoteControl'"

WATCH1="type='signal', sender=${OJECT}, interface=${IFACE}, path=${DPATH}, member='NoteAdded'"
WATCH2="type='signal', sender=${OJECT}, interface=${IFACE}, path=${DPATH}, member='NoteSaved'"
WATCH3="type='signal', sender=${OJECT}, interface=${IFACE}, path=${DPATH}, member='NoteDeleted'"

dbus-monitor "${WATCH1}" "${WATCH2}" "${WATCH3}" | \
awk '
/member=NoteAdded/ { getline; print "Created note " substr($2,7) }
/member=NoteSaved/ { getline; print "Added note " substr($2,7) }
/member=NoteDeleted/ { getline; print "Deleted note " substr($2,7) }
'

Here is the output generated when I clicked on the Tomboy icon to create a new note, waited for the automatic save and then selected the delete option to delete the note.

$ ./test
Created note //tomboy/3da026dc-f6ee-4637-8a94-bec6e2844824"
Added note //tomboy/3da026dc-f6ee-4637-8a94-bec6e2844824"
Deleted note //tomboy/3da026dc-f6ee-4637-8a94-bec6e2844824"

Well that is all for this post.  Enjoy!

P.S. I tested these examples using Fedora 10. I have no idea whether they will work on previous versions of Fedora or other Linux distributions.
 

Scripting Tomboy

Tomboy is an open source GNOME desktop note-taking application which is written in C# and utilizing the Mono runtime, Gtk# and the GtkSpell spell-checker.

The actual release of Tomboy which comes with Fedora 10 is version 0.12.0.  This includes a comprehensive D-Bus interface which makes it possible to create, modify and display Tomcat notes from your shell scripts.  This post provides an overview of the available D-Bus methods and includes a number of examples for you to experiment with.  See my previous post on D-Bus scripting if you are unfamilar with the basic concepts of D-Bus scripting.

First we will list the available objects using qdbus.

$ qdbus org.gnome.Tomboy
/
/org
/org/gnome
/org/gnome/Tomboy
/org/gnome/Tomboy/RemoteControl

Next, we list all the available signals and methods for RemoteControl.

$ qdbus org.gnome.Tomboy /org/gnome/Tomboy/RemoteControl
method QString org.freedesktop.DBus.Introspectable.Introspect()
method bool org.gnome.Tomboy.RemoteControl.AddTagToNote(QString uri, QString tag_name)
method QString org.gnome.Tomboy.RemoteControl.CreateNamedNote(QString linked_title)
method QString org.gnome.Tomboy.RemoteControl.CreateNote()
method bool org.gnome.Tomboy.RemoteControl.DeleteNote(QString uri)
method bool org.gnome.Tomboy.RemoteControl.DisplayNote(QString uri)
method bool org.gnome.Tomboy.RemoteControl.DisplayNoteWithSearch(QString uri, QString search)
method void org.gnome.Tomboy.RemoteControl.DisplaySearch()
method void org.gnome.Tomboy.RemoteControl.DisplaySearchWithText(QString search_text)
method QString org.gnome.Tomboy.RemoteControl.FindNote(QString linked_title)
method QString org.gnome.Tomboy.RemoteControl.FindStartHereNote()
method QStringList org.gnome.Tomboy.RemoteControl.GetAllNotesWithTag(QString tag_name)
method qlonglong org.gnome.Tomboy.RemoteControl.GetNoteChangeDate(QString uri)
method QString org.gnome.Tomboy.RemoteControl.GetNoteCompleteXml(QString uri)
method QString org.gnome.Tomboy.RemoteControl.GetNoteContents(QString uri)
method QString org.gnome.Tomboy.RemoteControl.GetNoteContentsXml(QString uri)
method qlonglong org.gnome.Tomboy.RemoteControl.GetNoteCreateDate(QString uri)
method QString org.gnome.Tomboy.RemoteControl.GetNoteTitle(QString uri)
method QStringList org.gnome.Tomboy.RemoteControl.GetTagsForNote(QString uri)
method bool org.gnome.Tomboy.RemoteControl.HideNote(QString uri)
method QStringList org.gnome.Tomboy.RemoteControl.ListAllNotes()
signal void org.gnome.Tomboy.RemoteControl.NoteAdded(QString uri)
signal void org.gnome.Tomboy.RemoteControl.NoteDeleted(QString uri, QString title)
method bool org.gnome.Tomboy.RemoteControl.NoteExists(QString uri)
signal void org.gnome.Tomboy.RemoteControl.NoteSaved(QString uri)
method bool org.gnome.Tomboy.RemoteControl.RemoveTagFromNote(QString uri, QString tag_name)
method QStringList org.gnome.Tomboy.RemoteControl.SearchNotes(QString query, bool case_sensitive)
method bool org.gnome.Tomboy.RemoteControl.SetNoteCompleteXml(QString uri, QString xml_contents)
method bool org.gnome.Tomboy.RemoteControl.SetNoteContents(QString uri, QString text_contents)
method bool org.gnome.Tomboy.RemoteControl.SetNoteContentsXml(QString uri, QString xml_contents)
method QString org.gnome.Tomboy.RemoteControl.Version()

As a simple example of how to use a published method, we invoke the Version method to return the version of Tomboy that we are using.

$ qdbus org.gnome.Tomboy /org/gnome/Tomboy/RemoteControl org.gnome.Tomboy.RemoteControl.Version
0.12.0

We can use dbus-send instead of qdbus as shown below but, as you can, see qdbus syntax is more compact.  Also note that we have to use the session bus.

$ dbus-send --type=method_call --session --print-reply \
    --dest='org.gnome.Tomboy' /org/gnome/Tomboy/RemoteControl \
    org.gnome.Tomboy.RemoteControl.Version
0.12.0

In the following example, we create the equivalant of "Hello World" using a note, display it for 5 seconds and then delete the note.

#!/bin/bash
DPATH="/org/gnome/Tomboy/RemoteControl"
INTERFACE="org.gnome.Tomboy.RemoteControl"

TMP=`qdbus org.gnome.Tomboy ${DPATH} ${INTERFACE}.CreateNamedNote "My Note" 2>/dev/null`
RESULT=$?
if [[ $RESULT != 0 ]]
then
    exit 1
fi

# figure out note uri string which is of the form
# note://0xaf3356abcdefg
OID=${TMP#note:}

# set the contents of the note using the uid
qdbus org.gnome.Tomboy ${DPATH} ${INTERFACE}.SetNoteContents note:$OID "Hello World"
qdbus org.gnome.Tomboy ${DPATH} ${INTERFACE}.DisplayNote note:$OID
sleep 5
qdbus org.gnome.Tomboy ${DPATH} ${INTERFACE}.DeleteNote note:$OID

Here is a screenshot of the note created by this shell script.



Incidentally, if you create one or more notes by accident while experimenting and need to delete them, the following script will delete all notes.

#!/bin/bash
OJECT="org.gnome.Tomboy"
DPATH="/org/gnome/Tomboy/RemoteControl"
IFACE="org.gnome.Tomboy.RemoteControl"

qdbus ${OJECT} ${DPATH} ${IFACE}.ListAllNotes |
while read TMP
do
  echo "$TMP"
  OID=${TMP#note:}
  qdbus ${OJECT} ${DPATH} ${IFACE}.DeleteNote note:$OID
done

You can also add one or more tags to a note and extract comprehensive metadata in XML format as shown in the following example.

#!/bin/bash
OJECT="org.gnome.Tomboy"
DPATH="/org/gnome/Tomboy/RemoteControl"
IFACE="org.gnome.Tomboy.RemoteControl"

TMP=`qdbus ${OJECT} ${DPATH} ${IFACE}.CreateNamedNote "My Note" 2>/dev/null`
RESULT=$?
OID=${TMP#note:}

qdbus ${OJECT} ${DPATH} ${IFACE}.SetNoteContents note:$OID "Hello World"
qdbus ${OJECT} ${DPATH} ${IFACE}.AddTagToNote note:$OID "blog example"
qdbus ${OJECT} ${DPATH} ${IFACE}.DisplayNote note:$OID
sleep 4
qdbus ${OJECT} ${DPATH} ${IFACE}.GetNoteCompleteXml note:$OID
qdbus ${OJECT} ${DPATH} ${IFACE}.DeleteNote note:$OID

# this is the output from the GetNoteCompleteXml
<?xml version="1.0" encoding="utf-16"?>
<note version="0.3" xmlns:link="http://beatniksoftware.com/tomboy/link" xmlns:size="http://beatniksoftware.com/tomboy/size" xmlns="http://beatniksoftware.com/tomboy">
  <title>My Note</title>
  <text xml:space="preserve"><note-content version="0.1">Hello World</note-content></text>
  <last-change-date>2009-02-08T10:44:46.3741020-05:00</last-change-date>
  <last-metadata-change-date>2009-02-08T10:44:46.3940970-05:00</last-metadata-change-date>
  <create-date>2009-02-08T10:44:46.3441770-05:00</create-date>
  <cursor-position>37</cursor-position>
  <width>450</width>
  <height>360</height>
  <x>3</x>
  <y>48</y>
  <tags>
    <tag>blog example</tag>
  </tags>
  <open-on-startup>False</open-on-startup>
</note>

You can also create a note in a single call to dbus-send or qdbus by passing the appropriate XML formatted details to the SetNoteCompleteXml method.

#!/bin/bash
OJECT="org.gnome.Tomboy"
DPATH="/org/gnome/Tomboy/RemoteControl"
IFACE="org.gnome.Tomboy.RemoteControl"

TMP=`qdbus ${OJECT} ${DPATH} ${IFACE}.CreateNamedNote "My Note" 2>/dev/null`
RESULT=$?
OID=${TMP#note:}

qdbus ${OJECT} ${DPATH} ${IFACE}.SetNoteCompleteXml note:$OID \
"<?xml version='1.0' encoding='utf-16'?>
 <note version='0.3' xmlns:link='http://beatniksoftware.com/tomboy/link'
     xmlns:size='http://beatniksoftware.com/tomboy/size'
     xmlns='http://beatniksoftware.com/tomboy'>
  <title>My Note</title>
  <text xml:space='preserve'>
      <note-content version='0.1'>Hello World</note-content>
  </text>
  <tags>
    <tag>first tag</tag>
    <tag>second tag</tag>#!/bin/bash
  </tags>
  <open-on-startup>False</open-on-startup>
</note>"

qdbus ${OJECT} ${DPATH} ${IFACE}.DisplayNote note:$OID
sleep 4
qdbus ${OJECT} ${DPATH} ${IFACE}.DeleteNote note:$OID

Interestingly, for some reason or other you cannot set the position or size of the resulting note.  If anybody knows how to overcome this limitation, please let me know.

Well that is all for this particular post as I have to head off to the airport for another boring long flight to Europe.  In my next post I will show you how to handle D-Bus signals in your shell scripts.
 

Scripting D-Bus

D-Bus (Desktop Bus) is a low-latency, low-overhead, easy-to-use message bus technology which supports application launch and linking.  It is primarly used on GNU/Linux desktops but has been ported to other platforms including Microsoft Windows and Apple Mac OS X.  This post provides a quick overview of D-Bus concepts, some history, and some examples of how to use D-Bus in your shell scripts.

Originally both the KDE and GNOME desktop projects used CORBA for inter-application communication.  Over time however, for various reasons, KDE migrated from CORBA to Desktop Comunications Protocol (DCOP) and GNOME migrated to Bonono.  This lead to the situation where GNU/Linux desktop distributions had to support two different inter-application lauch and linking models and many standard desktop applications could not communicate seamlessly with each other.  To ameliorate this unsatisfactory situation, D-Bus (the name was suggested by Harri Porten) was conceived and developed by Red Hat as part of the freedesktop.org project.  The design of D-Bus was heavily influenced by DCOP.  From the start, it was designed to be a replacement for the two competing technologies.   The initial source code module was created by Havoc Pennington in late 2002.  Development was quite slow with many changes to the wire protocol.  However by 2006 the specification was relatively stable.  First GNOME and then KDE made the decision to transition to D-Bus in order to support a single unified applcation linking and lauching technology on GNU/linux desktops.

In many ways D-Bus is similar to Sun Microsystems ToolTalk which is the undelying technology in Common Desktop Environment, and Microsoft's Object Linking and Embedding (OLE) technology.



The basic D-Bus protocol is a low latancy peer-to-peer or client-server binary protocol.  It is not intended for inter-machine use but rather for intra-machine use.  It works in terms of messages rather than byte streams.  A message bus is used when many-to-many communication is desired.  Normally applications communicate via such a message bus but direct application-to-application communication is also possible.

When communicating on a message bus, applications can query which other applications and services are available, as well as activate one on demand.  A daemon, or service, must be launched before any applications can connect to a message bus. This daemon is responsible for keeping track of the applications that are connected and for properly routing messages from source to destination.  The D-Bus specification defines two well-known buses called the system bus and the session bus.  These buses are special in that they have well-defined semantics and associated services.

A message bus can start (launch) an application on behalf of another application.  An application that can be started in this way is called a service and must have a well-known name.  To find an application corresponding to a particular name, the bus daemon looks for service description files which are XML files that map names to applications.  Different message buses will look for these files in different places on a system. Once the application is launched, it registers a service name.  Service names use reverse domain syntax (similar to Java), e.g org.freedesktop.Notifications.

D-Bus is object-orientated and supports the notion of named object interfaces.  As in C++, a method is an operation on an instantiated object.  Methods may have optional typed parameters and may return typed values.  Signals are broadcasts from an object to any interested observer.  All methods, method returns, signals, errors, etc. are encoded as D-Bus messages consisting of a packet header with source and destination addresses, a type signature and the body containing the parameters (for signals and method calls) or the return values (for a method return).  The type signature describes the types of the data contained within the message.  D-Bus uses interfaces to provide a namespacing mechanism for methods.  An interface is a group of related methods and signals, identified by a name which is a series of dot-separated components starting with a reversed domain name.

An application can expose one or more objects.  An object path is used to specify the address of each object.  The syntax of an object path is similar to that of the full pathname of a file on a Unix platform.  For example, /org/freedesktop/Notification is the object path to an object provided by the org.freedesktop.Notification service.  Service names, interface names and object paths do not have to be related in terms of their names but in many cases they are with the with the object path typically being a slashed version of the dotted service name as in the above example.  Messages buses can also expose interfaces, i.e. org.freedesktop.DBus.

The D-Bus specification mandates two special D-Bus interfaces - org.freedesktop.DBus.Introspect and org.freedesktop.DBus.Properties.  For our first example, let us ask the system message bus to list all it's methods.

dbus-send --system --print-reply --reply-timeout=2000 \
   --type=method_call --dest=org.freedesktop.DBus \
   /org/freedesktop/DBus \
   org.freedesktop.DBus.Introspectable.Introspect

method return sender=org.freedesktop.DBus -> dest=:1.51 reply_serial=2
   string "<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
<node>
  <interface name="org.freedesktop.DBus.Introspectable">
    <method name="Introspect">
      <arg name="data" direction="out" type="s"/>
    </method>
  </interface>
  <interface name="org.freedesktop.DBus">
    <method name="Hello">
      <arg direction="out" type="s"/>
    </method>
    <method name="RequestName">
      <arg direction="in" type="s"/>
      <arg direction="in" type="u"/>
      <arg direction="out" type="u"/>
    </method>
    <method name="ReleaseName">
      <arg direction="in" type="s"/>
      <arg direction="out" type="u"/>
    </method>
    <method name="StartServiceByName">
      <arg direction="in" type="s"/>
      <arg direction="in" type="u"/>
      <arg direction="out" type="u"/>
    </method>
    <method name="UpdateActivationEnvironment">
      <arg direction="in" type="a{ss}"/>
    </method>
    <method name="NameHasOwner">
      <arg direction="in" type="s"/>
      <arg direction="out" type="b"/>
    </method>
    <method name="ListNames">
      <arg direction="out" type="as"/>
    </method>
    <method name="ListActivatableNames">
      <arg direction="out" type="as"/>
    </method>
    <method name="AddMatch">
      <arg direction="in" type="s"/>
    </method>
    <method name="RemoveMatch">
      <arg direction="in" type="s"/>
    </method>
    <method name="GetNameOwner">
      <arg direction="in" type="s"/>
      <arg direction="out" type="s"/>
    </method>
    <method name="ListQueuedOwners">
      <arg direction="in" type="s"/>
      <arg direction="out" type="as"/>
    </method>
    <method name="GetConnectionUnixUser">
      <arg direction="in" type="s"/>
      <arg direction="out" type="u"/>
    </method>
    <method name="GetConnectionUnixProcessID">
      <arg direction="in" type="s"/>
      <arg direction="out" type="u"/>
    </method>
    <method name="GetAdtAuditSessionData">
      <arg direction="in" type="s"/>
      <arg direction="out" type="ay"/>
    </method>
    <method name="GetConnectionSELinuxSecurityContext">
      <arg direction="in" type="s"/>
      <arg direction="out" type="ay"/>
    </method>
    <method name="ReloadConfig">
    </method>
    <method name="GetId">
      <arg direction="out" type="s"/>
    </method>
    <signal name="NameOwnerChanged">
      <arg type="s"/>
      <arg type="s"/>
      <arg type="s"/>
    </signal>
    <signal name="NameLost">
      <arg type="s"/>
    </signal>
    <signal name="NameAcquired">
      <arg type="s"/>
    </signal>
  </interface>
</node>
"

The following command lists out the names of services which can be activated (launched).

dbus-send --system --print-reply --reply-timeout=2000 \
   --type=method_call --dest=org.freedesktop.DBus \
   /org/freedesktop/DBus \
   org.freedesktop.DBus.ListActivableNames

method return sender=org.freedesktop.DBus -> dest=:1.68 reply_serial=2
   array [
      string "org.freedesktop.DBus"
      string "org.fedoraproject.Config.Services"
      string "org.gnome.CPUFreqSelector"
      string "org.freedesktop.ConsoleKit"
      string "org.freedesktop.PackageKitAptBackend"
      string "org.freedesktop.PackageKit"
      string "org.freedesktop.NetworkManagerSystemSettings"
      string "org.freedesktop.PackageKitTestBackend"
      string "org.gnome.ClockApplet.Mechanism"
      string "org.freedesktop.PolicyKit"
      string "fi.epitest.hostap.WPASupplicant"
      string "org.gnome.GConf.Defaults"
      string "org.gnome.SystemMonitor.Mechanism"
      string "org.freedesktop.nm_dispatcher"
   ]

Instead of using dbus-send which requires a number of parameters, a simpler utility to use is dbus which is part of the Google dbus-cli package.  Here is some sample output.

bash-3.2$ ./dbus
org.freedesktop.DBus
org.freedesktop.Notifications
org.freedesktop.PowerManagement
com.redhat.imsettings.IMInfo
org.gnome.SessionManager
org.gnome.GConf
org.freedesktop.PackageKit
com.redhat.imsettings
org.gnome.SettingsDaemon
com.redhat.setroubleshoot
org.gnome.ScreenSaver
org.bluez.applet
com.redhat.imsettings.GConf

Another useful utility is qdbus.

# list all GNOME-related  buses 
$ qdbus | grep gnome
 org.gnome.SessionManager
 org.gnome.SettingsDaemon
 org.gnome.ScreenSaver
 org.gnome.GConf

# list ScreenSaver interfaces            
bash-3.2$ qdbus org.gnome.ScreenSaver
/

# list methods for ScreenSaver interface
$ qdbus org.gnome.ScreenSaver /ScreenSaver
method QString org.freedesktop.DBus.Introspectable.Introspect()
signal void org.gnome.ScreenSaver.ActiveChanged(bool new_value)
signal void org.gnome.ScreenSaver.AuthenticationRequestBegin()
signal void org.gnome.ScreenSaver.AuthenticationRequestEnd()
method void org.gnome.ScreenSaver.Cycle()
method bool org.gnome.ScreenSaver.GetActive()
method uint org.gnome.ScreenSaver.GetActiveTime()
method QStringList org.gnome.ScreenSaver.GetInhibitors()
method bool org.gnome.ScreenSaver.GetSessionIdle()
method uint org.gnome.ScreenSaver.GetSessionIdleTime()
method uint org.gnome.ScreenSaver.Inhibit(QString application_name, QString reason)
method void org.gnome.ScreenSaver.Lock()
signal void org.gnome.ScreenSaver.SessionIdleChanged(bool new_value)
signal void org.gnome.ScreenSaver.SessionPowerManagementIdleChanged(bool new_value)
method void org.gnome.ScreenSaver.SetActive(bool value)
method void org.gnome.ScreenSaver.SimulateUserActivity()
method uint org.gnome.ScreenSaver.Throttle(QString application_name, QString reason)
method void org.gnome.ScreenSaver.UnInhibit(uint cookie)
method void org.gnome.ScreenSaver.UnThrottle(uint cookie)

# retrieve session idle time. Zero in this case as I have been working on this post.
$ qdbus org.gnome.ScreenSaver /ScreenSaver org.gnome.ScreenSaver.GetSessionIdleTime
0

# activate the screen saver - may or may not lock depending on settings
$ qdbus org.gnome.ScreenSaver /ScreenSaver org.gnome.ScreenSaver.SetActive True

# lock screen using the screensaver
$ qdbus org.gnome.ScreenSaver /ScreenSaver org.gnome.ScreenSaver.Lock

# query whether this computer can be suspended?
$ qdbus org.freedesktop.PowerManagement /org/freedesktop/PowerManagement org.freedesktop.PowerManagement.CanSuspend
true

You can also query devices via HAL as the following examples show.

$ dbus-send --system --print-reply --dest=org.freedesktop.Hal \
             /org/freedesktop/Hal/devices/computer             \
             org.freedesktop.DBus.Introspectable.Introspect

method return sender=:1.0 -> dest=:1.106 reply_serial=2
   string "<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
<node>
  <interface name="org.freedesktop.DBus.Introspectable">
    <method name="Introspect">
      <arg name="data" direction="out" type="s"/>
    <method>
  <interface>
  <interface name="org.freedesktop.Hal.Device">
     ........
  <interface>
  <interface name="org.freedesktop.Hal.Device.SystemPowerManagement">
    ........
  <interface>
  <interface name="org.freedesktop.Hal.Device.CPUFreq">
    ........
    <method name="GetCPUFreqAvailableGovernors">
      <arg name="return_code" direction="out" type="as"/>
    <method>
  <interface>
<node>
"

$ dbus-send --system --print-reply --dest=org.freedesktop.Hal \
            /org/freedesktop/Hal/devices/computer \
            org.freedesktop.Hal.Device.CPUFreq.GetCPUFreqAvailableGovernors

method return sender=:1.0 -> dest=:1.109 reply_serial=2
   array [
      string "ondemand"
      string "userspace"
      string "performance"
   ]

$ dbus-send --system --print-reply --dest=org.freedesktop.Hal  \
           /org/freedesktop/Hal/Manager  \
           org.freedesktop.Hal.Manager.GetAllDevices

method return sender=:1.0 -> dest=:1.115 reply_serial=2
   array [
      string "/org/freedesktop/Hal/devices/volume_part_1_size_403367936"
      string "/org/freedesktop/Hal/devices/net_46_b2_32_e5_29_04"
      string "/org/freedesktop/Hal/devices/computer_logicaldev_input_0"
      string "/org/freedesktop/Hal/devices/usb_device_45e_734_noserial_if0_logicaldev_input"
      string "/org/freedesktop/Hal/devices/usb_device_45e_734_noserial_if1_logicaldev_input"
      string "/org/freedesktop/Hal/devices/computer_logicaldev_input"
      string "/org/freedesktop/Hal/devices/volume_uuid_9e1859de_0cf0_4048_96f5_4ef32ac904f7"
      string "/org/freedesktop/Hal/devices/computer"
      string "/org/freedesktop/Hal/devices/volume_part2_size_205632000"
      string "/org/freedesktop/Hal/devices/volume_uuid_a332a6d6_a034_4f19_b470_bacf7ffa81e2"
      string "/org/freedesktop/Hal/devices/volume_uuid_RyytQp_f73U_LzdN_6JjC_08yN_Aw3e_p3fNF1"
      string "/org/freedesktop/Hal/devices/storage_model_DVD_Writer_1070d"
      string "/org/freedesktop/Hal/devices/platform_serial8250_serial_platform_1"
      string "/org/freedesktop/Hal/devices/storage_serial_SATA_ST3500320AS_9QM49NMQ"
      string "/org/freedesktop/Hal/devices/storage_serial_SATA_ST3500320AS_9QM4GKDK"
      .........
   ]

$ dbus-send --system --print-reply --dest=org.freedesktop.Hal \
       /org/freedesktop/Hal/devices/storage_model_DVD_Writer_1070d
       org.freedesktop.Hal.Device.GetProperty string:'info.vendor'

method return sender=:1.0 -> dest=:1.120 reply_serial=2
   string "HP"

While D-Bus was not really designed with shell scripting in mind, it is possible to use various utilities to access system and session data via D-Bus.  I hope you have not found this post too long-winded and that you will go away and experiment with D-Bus on your own computer.  Unfortunately there is a lot of out-of-date information, terminology and examples on the Internet relating to D-Bus.  Always refer back to the specification when in doubt.  All the examples included on this port were tested on Fedora 10.

P.S.  I plan to cover scripting D-Bus signals in a future post.