Fork of Original Code Base: anongit.freedesktop.org/systemd

This is the initial fork of the code base from freedsktop.org.
The code is provided here as a reference of the initial starting
point and for possible future checkouts after a large portion
of this code is removed.

Merge git://anongit.freedesktop.org/systemd/systemd

1 files changed, 350 insertions, 0 deletions

diff --git a/man/os-release.xml b/man/os-release.xml
new file mode 100644
index 0000000000..98320efe31
--- /dev/null
+++ b/man/os-release.xml
@@ -0,0 +1,350 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+  This file is part of systemd.
+
+  Copyright 2010 Lennart Poettering
+
+  systemd is free software; you can redistribute it and/or modify it
+  under the terms of the GNU Lesser General Public License as published by
+  the Free Software Foundation; either version 2.1 of the License, or
+  (at your option) any later version.
+
+  systemd is distributed in the hope that it will be useful, but
+  WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+  Lesser General Public License for more details.
+
+  You should have received a copy of the GNU Lesser General Public License
+  along with systemd; If not, see <http://www.gnu.org/licenses/>.
+-->
+
+<refentry id="os-release">
+        <refentryinfo>
+                <title>os-release</title>
+                <productname>systemd</productname>
+
+                <authorgroup>
+                        <author>
+                                <contrib>Developer</contrib>
+                                <firstname>Lennart</firstname>
+                                <surname>Poettering</surname>
+                                <email>lennart@poettering.net</email>
+                        </author>
+                </authorgroup>
+        </refentryinfo>
+
+        <refmeta>
+                <refentrytitle>os-release</refentrytitle>
+                <manvolnum>5</manvolnum>
+        </refmeta>
+
+        <refnamediv>
+                <refname>os-release</refname>
+                <refpurpose>Operating system identification</refpurpose>
+        </refnamediv>
+
+        <refsynopsisdiv>
+                <para><filename>/etc/os-release</filename></para>
+        </refsynopsisdiv>
+
+        <refsect1>
+                <title>Description</title>
+
+                <para>The <filename>/etc/os-release</filename> file
+                contains operating system identification data.</para>
+
+                <para>The basic file format of
+                <filename>os-release</filename> is a newline-separated
+                list of environment-like shell-compatible variable
+                assignments. It is possible to source the
+                configuration from shell scripts, however, beyond mere
+                variable assignments no shell features are supported
+                (this means variable expansion is explicitly not
+                supported), allowing applications to read the file
+                without implementing a shell compatible execution
+                engine. Variable assignment values should be enclosed
+                in double or single quotes if they include spaces,
+                semicolons or other special characters outside of A-Z,
+                a-z, 0-9. All strings should be in UTF-8 format, and
+                non-printable characters should not be used. If double
+                or single quotes or backslashes are to be used within
+                variable assignments they should be escaped with
+                backslashes, following shell style. It is not
+                supported to concatenate multiple individually quoted
+                strings. Lines beginning with "#" shall be ignored as
+                comments.</para>
+
+                <para><filename>/etc/os-release</filename> contains
+                data that is defined by the operating system vendor
+                and should not be changed by the administrator.</para>
+
+                <para>As this file only encodes names and identifiers
+                it should not be localized.</para>
+
+                <para>The file <filename>/etc/os-release</filename> might
+                be a symlink to another file, but it is important that
+                the file is available from earliest boot on, and hence
+                must be located on the root file system.</para>
+
+                <para>For a longer rationale for
+                <filename>/etc/os-release</filename> please refer to
+                the <ulink
+                url="http://0pointer.de/blog/projects/os-release">Announcement of <filename>/etc/os-release</filename></ulink>.</para>
+        </refsect1>
+
+        <refsect1>
+                <title>Options</title>
+
+                <para>The following OS identifications parameters may be set using
+                <filename>/etc/os-release</filename>:</para>
+
+                <variablelist>
+
+                        <varlistentry>
+                                <term><varname>NAME=</varname></term>
+
+                                <listitem><para>A string identifying
+                                the operating system, without a
+                                version component, and suitable for
+                                presentation to the user. If not set
+                                defaults to
+                                <literal>NAME=Linux</literal>. Example:
+                                <literal>NAME=Fedora</literal> or
+                                <literal>NAME="Debian
+                                GNU/Linux"</literal>.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>VERSION=</varname></term>
+
+                                <listitem><para>A string identifying
+                                the operating system version,
+                                excluding any OS name information,
+                                possibly including a release code
+                                name, and suitable for presentation to
+                                the user. This field is
+                                optional. Example:
+                                <literal>VERSION=17</literal> or
+                                <literal>VERSION="17 (Beefy
+                                Miracle)"</literal>.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>ID=</varname></term>
+
+                                <listitem><para>A lower-case string
+                                (no spaces or other characters outside
+                                of 0-9, a-z, ".", "_" and "-")
+                                identifying the operating system,
+                                excluding any version information and
+                                suitable for processing by scripts or
+                                usage in generated file names. If not
+                                set defaults to
+                                <literal>ID=linux</literal>. Example:
+                                <literal>ID=fedora</literal> or
+                                <literal>ID=debian</literal>.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>ID_LIKE=</varname></term>
+
+                                <listitem><para>A space-separated list
+                                of operating system identifiers in the
+                                same syntax as the
+                                <varname>ID=</varname> setting. Should
+                                list identifiers of operating systems
+                                that are closely related to the local
+                                operating system in regards to
+                                packaging and programming interfaces,
+                                for example listing one or more
+                                OS identifiers the local
+                                OS is a derivative from. An
+                                OS should generally only list other OS
+                                identifiers it itself is a derivative
+                                from, and not any OSes that
+                                are derived from it, but symmetric
+                                relationships are possible. Build
+                                scripts and similar should check this
+                                variable if they need to identify the
+                                local operating system and the value
+                                of <varname>ID=</varname> is not
+                                recognized. Operating systems should
+                                be listed in order of how closely the
+                                local operating system relates to the
+                                listed ones, starting with the
+                                closest. This field is
+                                optional. Example: for an operating
+                                system with
+                                <literal>ID=centos</literal> an
+                                assignment of <literal>ID_LIKE="rhel
+                                fedora"</literal> would be
+                                appropriate. For an operating system
+                                with <literal>ID=ubuntu</literal> an
+                                assignment of
+                                <literal>ID_LIKE=debian</literal> is
+                                appropriate.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>VERSION_ID=</varname></term>
+
+                                <listitem><para>A lower-case string
+                                (mostly numeric, no spaces or other
+                                characters outside of 0-9, a-z, ".",
+                                "_" and "-") identifying the operating
+                                system version, excluding any OS name
+                                information or release code name, and
+                                suitable for processing by scripts or
+                                usage in generated file names. This
+                                field is optional. Example:
+                                <literal>VERSION_ID=17</literal> or
+                                <literal>VERSION_ID=11.04</literal>.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>PRETTY_NAME=</varname></term>
+
+                                <listitem><para>A pretty operating
+                                system name in a format suitable for
+                                presentation to the user. May or may
+                                not contain a release code name or OS
+                                version of some kind, as suitable. If
+                                not set defaults to
+                                <literal>PRETTY_NAME="Linux"</literal>. Example:
+                                <literal>PRETTY_NAME="Fedora 17 (Beefy
+                                Miracle)"</literal>.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>ANSI_COLOR=</varname></term>
+
+                                <listitem><para>A suggested
+                                presentation color when showing the
+                                OS name on the console. This
+                                should be specified as string suitable
+                                for inclusion in the ESC [ m
+                                ANSI/ECMA-48 escape code for setting
+                                graphical rendition. This field is
+                                optional. Example:
+                                <literal>ANSI_COLOR="0;31"</literal>
+                                for red, or
+                                <literal>ANSI_COLOR="1;34"</literal>
+                                for light blue.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>CPE_NAME=</varname></term>
+
+                                <listitem><para>A CPE name for the
+                                operating system, following the <ulink
+                                url="http://cpe.mitre.org/specification/">Common
+                                Platform Enumeration
+                                Specification</ulink> as proposed by
+                                the MITRE Corporation. This field
+                                is optional. Example:
+                                <literal>CPE_NAME="cpe:/o:fedoraproject:fedora:17"</literal>
+                                </para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>HOME_URL=</varname></term>
+                                <term><varname>SUPPORT_URL=</varname></term>
+                                <term><varname>BUG_REPORT_URL=</varname></term>
+
+                                <listitem><para>Links to resources on
+                                the Internet related the operating
+                                system. <varname>HOME_URL=</varname>
+                                should refer to the homepage of the
+                                operating system, or alternatively
+                                some homepage of the specific version
+                                of the operating
+                                system. <varname>SUPPORT_URL=</varname>
+                                should refer to the main support page
+                                for the operating system, if there is
+                                any. This is primarily intended for
+                                operating systems which vendors
+                                provide support
+                                for. <varname>BUG_REPORT_URL=</varname>
+                                should refer to the main bug reporting
+                                page for the operating system, if
+                                there is any. This is primarily
+                                intended for operating systems that
+                                rely on community QA. These settings
+                                are optional, and providing only some
+                                of these settings is common. These
+                                URLs are intended to be exposed in
+                                "About this system" UIs behind links
+                                with captions such as "About this
+                                Operating System", "Obtain Support",
+                                and "Report a Bug". The values should
+                                be in <ulink
+                                url="https://tools.ietf.org/html/rfc3986">RFC3986
+                                format</ulink>, and should be
+                                <literal>http:</literal> or
+                                <literal>https:</literal> URLs, and
+                                possibly <literal>mailto:</literal> or
+                                <literal>tel:</literal>. Only one URL
+                                shall be listed in each setting. If
+                                multiple resources need to be
+                                referenced it is recommended to
+                                provide an online landing page linking
+                                all available resources. Examples:
+                                <literal>HOME_URL="https://fedoraproject.org/"</literal>
+                                and
+                                <literal>BUG_REPORT_URL="https://bugzilla.redhat.com/"</literal></para></listitem>
+                        </varlistentry>
+
+
+                </variablelist>
+
+                <para>If you are reading this file from C code or a
+                shell script to determine the OS or a specific version
+                of it, use the ID and VERSION_ID fields, possibly with
+                ID_LIKE as fallback for ID. When looking for an OS
+                identification string for presentation to the user use
+                the PRETTY_NAME field.</para>
+
+                <para>Note that operating system vendors may choose
+                not to provide version information, for example to
+                accommodate for rolling releases. In this case VERSION
+                and VERSION_ID may be unset. Applications should not
+                rely on these fields to be set.</para>
+
+                <para>Operating system vendors may extend the file
+                format and introduce new fields. It is highly
+                recommended to prefix new fields with an OS specific
+                name in order to avoid name clashes. Applications
+                reading this file must ignore unknown fields. Example:
+                <literal>DEBIAN_BTS="debbugs://bugs.debian.org/"</literal></para>
+        </refsect1>
+
+        <refsect1>
+                <title>Example</title>
+
+                <programlisting>NAME=Fedora
+VERSION="17 (Beefy Miracle)"
+ID=fedora
+VERSION_ID=17
+PRETTY_NAME="Fedora 17 (Beefy Miracle)"
+ANSI_COLOR="0;34"
+CPE_NAME="cpe:/o:fedoraproject:fedora:17"
+HOME_URL="https://fedoraproject.org/"
+BUG_REPORT_URL="https://bugzilla.redhat.com/"</programlisting>
+        </refsect1>
+
+        <refsect1>
+                  <title>See Also</title>
+                  <para>
+                          <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+                          <citerefentry><refentrytitle>lsb_release</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+                          <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+                          <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+                          <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                  </para>
+        </refsect1>
+
+</refentry>