blob: f9ef29139a0cf198a186f75e9505ab668b279ff2 [file] [log] [blame]
<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl"
href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
]>
<refentry id="xdg-settings">
<refentryinfo>
<title>xdg-settings Manual</title>
<copyright>
<year>2009-2011</year>
</copyright>
<author>
<firstname>Mike</firstname>
<surname>Mammarella</surname>
</author>
<address><email>mdm@google.com</email></address>
<!--<releaseinfo>xdg-utils 1.0</releaseinfo>-->
</refentryinfo>
<refmeta>
<refentrytitle>xdg-settings</refentrytitle>
<manvolnum>1</manvolnum>
</refmeta>
<refnamediv>
<refname>xdg-settings</refname>
<refpurpose>get various settings from the desktop environment</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>xdg-settings</command>
<group choice="req">
<arg choice="plain"><option><replaceable>get</replaceable></option></arg>
<arg choice="plain"><option><replaceable>check</replaceable></option></arg>
<arg choice="plain"><option><replaceable>set</replaceable></option></arg>
</group>
<group choice="req">
<option>property</option>
</group>
<group choice="opt">
<option>subproperty</option>
</group>
<group choice="opt">
<option>value</option>
</group>
</cmdsynopsis>
<cmdsynopsis>
<command>xdg-settings</command>
<group choice="req">
<arg choice="plain"><option>--help</option></arg>
<arg choice="plain"><option>--list</option></arg>
<arg choice="plain"><option>--manual</option></arg>
<arg choice="plain"><option>--version</option></arg>
</group>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1 id="description">
<title>Description</title>
<para>
xdg-settings gets various settings from the desktop environment.
For instance, desktop environments often provide proxy configuration
and default web browser settings. Using xdg-settings these parameters
can be extracted for use by applications that do not use the desktop
environment's libraries (which would use the settings natively).
</para>
<para>
xdg-settings is for use inside a desktop session only.
It is not recommended to use xdg-settings as root.
</para>
</refsect1>
<refsect1 id="options">
<title>Options</title>
<variablelist>
<varlistentry>
<term><option>--help</option></term>
<listitem>
<simpara>
Show command synopsis.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--list</option></term>
<listitem>
<simpara>
List all properties xdg-settings knows about.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--manual</option></term>
<listitem>
<simpara>
Show this manualpage.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--version</option></term>
<listitem>
<simpara>
Show the xdg-utils version information.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="properties">
<title>Properties</title>
<para>
When using xdg-settings to get, check or set a destkop setting, properties
and possibly sub-properties are used to specify the setting to be changed.
</para>
<para>
Some properties (such as default-web-browser) fully describe the setting
to be changed. Other properties (such as default-url-scheme-handler) require
more information (in this case the actual scheme to set the default handler
for) which must be provided in a sub-property.
</para>
</refsect1>
<refsect1 id="exitcodes">
<title>Exit Codes</title>
<para>
An exit code of 0 indicates success while a non-zero exit code
indicates failure. The following failure codes can be returned:
</para>
<variablelist>
<varlistentry>
<term><option>1</option></term>
<listitem>
<simpara>
Error in command line syntax.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><option>2</option></term>
<listitem>
<simpara>
One of the files passed on the command line did not exist.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><option>3</option></term>
<listitem>
<simpara>
A required tool could not be found.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term><option>4</option></term>
<listitem>
<simpara>
The action failed.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="examples">
<title>Examples</title>
<para>
Get the desktop file name of the current default web browser
<programlisting>
xdg-settings get default-web-browser
</programlisting>
</para>
<para>
Check whether the default web browser is firefox.desktop, which can be
false even if "get default-web-browser" says that is the current value
(if only some of the underlying settings actually reflect that value)
<programlisting>
xdg-settings check default-web-browser firefox.desktop
</programlisting>
</para>
<para>
Set the default web browser to google-chrome.desktop
<programlisting>
xdg-settings set default-web-browser google-chrome.desktop
</programlisting>
</para>
<para>
Set the default mailto URL scheme handler to be evolution.desktop
<programlisting>
xdg-settings set default-url-scheme-handler mailto evolution.desktop
</programlisting>
</para>
</refsect1>
</refentry>