mirror of
https://gitlab.freedesktop.org/dbus/dbus.git
synced 2025-12-29 02:00:10 +01:00
46b9961be7
This will make integrating the building of HTML versions of these manpages into the build system way easier, at the cost of keeping manpages in a different directory to the source for the program they describe. I think this is an acceptable trade-off.
183 lines
6.8 KiB
Groff
183 lines
6.8 KiB
Groff
.\"
|
|
.\" dbus-launch manual page.
|
|
.\" Copyright (C) 2003 Red Hat, Inc.
|
|
.\"
|
|
.TH dbus-launch 1
|
|
.SH NAME
|
|
dbus-launch \- Utility to start a message bus from a shell script
|
|
.SH SYNOPSIS
|
|
.PP
|
|
.B dbus-launch [\-\-version] [\-\-sh-syntax] [\-\-csh-syntax] [\-\-auto-syntax] [\-\-exit-with-session] [\-\-autolaunch=MACHINEID] [\-\-config-file=FILENAME] [PROGRAM] [ARGS...]
|
|
|
|
.SH DESCRIPTION
|
|
|
|
The \fIdbus-launch\fP command is used to start a session bus
|
|
instance of \fIdbus-daemon\fP from a shell script.
|
|
It would normally be called from a user's login
|
|
scripts. Unlike the daemon itself, \fIdbus-launch\fP exits, so
|
|
backticks or the $() construct can be used to read information from
|
|
\fIdbus-launch\fP.
|
|
|
|
With no arguments, \fIdbus-launch\fP will launch a session bus
|
|
instance and print the address and pid of that instance to standard
|
|
output.
|
|
|
|
You may specify a program to be run; in this case, \fIdbus-launch\fP
|
|
will launch a session bus instance, set the appropriate environment
|
|
variables so the specified program can find the bus, and then execute the
|
|
specified program, with the specified arguments. See below for
|
|
examples.
|
|
|
|
If you launch a program, \fIdbus-launch\fP will not print the
|
|
information about the new bus to standard output.
|
|
|
|
When \fIdbus-launch\fP prints bus information to standard output, by
|
|
default it is in a simple key-value pairs format. However, you may
|
|
request several alternate syntaxes using the \-\-sh-syntax, \-\-csh-syntax,
|
|
\-\-binary-syntax, or
|
|
\-\-auto-syntax options. Several of these cause \fIdbus-launch\fP to emit shell code
|
|
to set up the environment.
|
|
|
|
With the \-\-auto-syntax option, \fIdbus-launch\fP looks at the value
|
|
of the SHELL environment variable to determine which shell syntax
|
|
should be used. If SHELL ends in "csh", then csh-compatible code is
|
|
emitted; otherwise Bourne shell code is emitted. Instead of passing
|
|
\-\-auto-syntax, you may explicity specify a particular one by using
|
|
\-\-sh-syntax for Bourne syntax, or \-\-csh-syntax for csh syntax.
|
|
In scripts, it's more robust to avoid \-\-auto-syntax and you hopefully
|
|
know which shell your script is written in.
|
|
|
|
.PP
|
|
See http://www.freedesktop.org/software/dbus/ for more information
|
|
about D-Bus. See also the man page for \fIdbus-daemon\fP.
|
|
|
|
.PP
|
|
Here is an example of how to use \fIdbus-launch\fP with an
|
|
sh-compatible shell to start the per-session bus daemon:
|
|
.nf
|
|
|
|
## test for an existing bus daemon, just to be safe
|
|
if test -z "$DBUS_SESSION_BUS_ADDRESS" ; then
|
|
## if not found, launch a new one
|
|
eval `dbus-launch --sh-syntax --exit-with-session`
|
|
echo "D-Bus per-session daemon address is: $DBUS_SESSION_BUS_ADDRESS"
|
|
fi
|
|
|
|
.fi
|
|
You might run something like that in your login scripts.
|
|
|
|
.PP
|
|
Another way to use \fIdbus-launch\fP is to run your main session
|
|
program, like so:
|
|
.nf
|
|
|
|
dbus-launch gnome-session
|
|
|
|
.fi
|
|
The above would likely be appropriate for ~/.xsession or ~/.Xclients.
|
|
|
|
.SH AUTOMATIC LAUNCHING
|
|
|
|
.PP
|
|
If DBUS_SESSION_BUS_ADDRESS is not set for a process that tries to use
|
|
D-Bus, by default the process will attempt to invoke dbus-launch with
|
|
the --autolaunch option to start up a new session bus or find the
|
|
existing bus address on the X display or in a file in
|
|
~/.dbus/session-bus/
|
|
|
|
.PP
|
|
Whenever an autolaunch occurs, the application that had to
|
|
start a new bus will be in its own little world; it can effectively
|
|
end up starting a whole new session if it tries to use a lot of
|
|
bus services. This can be suboptimal or even totally broken, depending
|
|
on the app and what it tries to do.
|
|
|
|
.PP
|
|
There are two common reasons for autolaunch. One is ssh to a remote
|
|
machine. The ideal fix for that would be forwarding of
|
|
DBUS_SESSION_BUS_ADDRESS in the same way that DISPLAY is forwarded.
|
|
In the meantime, you can edit the session.conf config file to
|
|
have your session bus listen on TCP, and manually set
|
|
DBUS_SESSION_BUS_ADDRESS, if you like.
|
|
|
|
.PP
|
|
The second common reason for autolaunch is an su to another user, and
|
|
display of X applications running as the second user on the display
|
|
belonging to the first user. Perhaps the ideal fix in this case
|
|
would be to allow the second user to connect to the session bus of the
|
|
first user, just as they can connect to the first user's display.
|
|
However, a mechanism for that has not been coded.
|
|
|
|
.PP
|
|
You can always avoid autolaunch by manually setting
|
|
DBUS_SESSION_BUS_ADDRESS. Autolaunch happens because the default
|
|
address if none is set is "autolaunch:", so if any other address is
|
|
set there will be no autolaunch. You can however include autolaunch in
|
|
an explicit session bus address as a fallback, for example
|
|
DBUS_SESSION_BUS_ADDRESS="something:,autolaunch:" - in that case if
|
|
the first address doesn't work, processes will autolaunch. (The bus
|
|
address variable contains a comma-separated list of addresses to try.)
|
|
|
|
.PP
|
|
The --autolaunch option is considered an internal implementation
|
|
detail of libdbus, and in fact there are plans to change it. There's
|
|
no real reason to use it outside of the libdbus implementation anyhow.
|
|
|
|
.SH OPTIONS
|
|
The following options are supported:
|
|
.TP
|
|
.I "--auto-syntax"
|
|
Choose \-\-csh-syntax or \-\-sh-syntax based on the SHELL environment variable.
|
|
|
|
.I "--binary-syntax"
|
|
Write to stdout a nul-terminated bus address, then the bus PID as a
|
|
binary integer of size sizeof(pid_t), then the bus X window ID as a
|
|
binary integer of size sizeof(long). Integers are in the machine's
|
|
byte order, not network byte order or any other canonical byte order.
|
|
|
|
.TP
|
|
.I "--close-stderr"
|
|
Close the standard error output stream before starting the D-Bus
|
|
daemon. This is useful if you want to capture dbus-launch error
|
|
messages but you don't want dbus-daemon to keep the stream open to
|
|
your application.
|
|
|
|
.TP
|
|
.I "--config-file=FILENAME"
|
|
Pass \-\-config-file=FILENAME to the bus daemon, instead of passing it
|
|
the \-\-session argument. See the man page for dbus-daemon
|
|
|
|
.TP
|
|
.I "--csh-syntax"
|
|
Emit csh compatible code to set up environment variables.
|
|
|
|
.TP
|
|
.I "--exit-with-session"
|
|
If this option is provided, a persistent "babysitter" process will be
|
|
created that watches stdin for HUP and tries to connect to the X
|
|
server. If this process gets a HUP on stdin or loses its X connection,
|
|
it kills the message bus daemon.
|
|
|
|
.TP
|
|
.I "--autolaunch=MACHINEID"
|
|
This option implies that \fIdbus-launch\fP should scan for a
|
|
previously-started session and reuse the values found there. If no
|
|
session is found, it will start a new session. The
|
|
\-\-exit-with-session option is implied if \-\-autolaunch is given.
|
|
This option is for the exclusive use of libdbus, you do not want to
|
|
use it manually. It may change in the future.
|
|
|
|
.TP
|
|
.I "--sh-syntax"
|
|
Emit Bourne-shell compatible code to set up environment variables.
|
|
|
|
.TP
|
|
.I "--version"
|
|
Print the version of dbus-launch
|
|
|
|
.SH AUTHOR
|
|
See http://www.freedesktop.org/software/dbus/doc/AUTHORS
|
|
|
|
.SH BUGS
|
|
Please send bug reports to the D-Bus mailing list or bug tracker,
|
|
see http://www.freedesktop.org/software/dbus/
|