diff options
Diffstat (limited to 'doc/dbus-launch.1')
| -rw-r--r-- | doc/dbus-launch.1 | 183 |
1 files changed, 0 insertions, 183 deletions
diff --git a/doc/dbus-launch.1 b/doc/dbus-launch.1 deleted file mode 100644 index a7687cad..00000000 --- a/doc/dbus-launch.1 +++ /dev/null @@ -1,183 +0,0 @@ -.\" -.\" 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 explicitly 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/ |