man/sd_id128_get_machine.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   This file is part of elogind.
   7
   8   Copyright 2012 Lennart Poettering
   9
  10   elogind is free software; you can redistribute it and/or modify it
  11   under the terms of the GNU Lesser General Public License as published by
  12   the Free Software Foundation; either version 2.1 of the License, or
  13   (at your option) any later version.
  14
  15   elogind is distributed in the hope that it will be useful, but
  16   WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18   Lesser General Public License for more details.
  19
  20   You should have received a copy of the GNU Lesser General Public License
  21   along with elogind; If not, see <http://www.gnu.org/licenses/>.
  22 -->
  23
  24 <refentry id="sd_id128_get_machine">
  25
  26   <refentryinfo>
  27     <title>sd_id128_get_machine</title>
  28     <productname>elogind</productname>
  29
  30     <authorgroup>
  31       <author>
  32         <contrib>Developer</contrib>
  33         <firstname>Lennart</firstname>
  34         <surname>Poettering</surname>
  35         <email>lennart@poettering.net</email>
  36       </author>
  37     </authorgroup>
  38   </refentryinfo>
  39
  40   <refmeta>
  41     <refentrytitle>sd_id128_get_machine</refentrytitle>
  42     <manvolnum>3</manvolnum>
  43   </refmeta>
  44
  45   <refnamediv>
  46     <refname>sd_id128_get_machine</refname>
  47     <refname>sd_id128_get_boot</refname>
  48     <refname>sd_id128_get_invocation</refname>
  49     <refpurpose>Retrieve 128-bit IDs</refpurpose>
  50   </refnamediv>
  51
  52   <refsynopsisdiv>
  53     <funcsynopsis>
  54       <funcsynopsisinfo>#include &lt;elogind/sd-id128.h&gt;</funcsynopsisinfo>
  55
  56       <funcprototype>
  57         <funcdef>int <function>sd_id128_get_machine</function></funcdef>
  58         <paramdef>sd_id128_t *<parameter>ret</parameter></paramdef>
  59       </funcprototype>
  60
  61       <funcprototype>
  62         <funcdef>int <function>sd_id128_get_boot</function></funcdef>
  63         <paramdef>sd_id128_t *<parameter>ret</parameter></paramdef>
  64       </funcprototype>
  65
  66       <funcprototype>
  67         <funcdef>int <function>sd_id128_get_invocation</function></funcdef>
  68         <paramdef>sd_id128_t *<parameter>ret</parameter></paramdef>
  69       </funcprototype>
  70
  71     </funcsynopsis>
  72   </refsynopsisdiv>
  73
  74   <refsect1>
  75     <title>Description</title>
  76
  77     <para><function>sd_id128_get_machine()</function> returns the
  78     machine ID of the executing host. This reads and parses the
  79     <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  80     file. This function caches the machine ID internally to make
  81     retrieving the machine ID a cheap operation.</para>
  82
  83     <para><function>sd_id128_get_boot()</function> returns the boot ID
  84     of the executing kernel. This reads and parses the
  85     <filename>/proc/sys/kernel/random/boot_id</filename> file exposed
  86     by the kernel. It is randomly generated early at boot and is
  87     unique for every running kernel instance. See
  88     <citerefentry project='man-pages'><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry>
  89     for more information. This function also internally caches the
  90     returned ID to make this call a cheap operation.</para>
  91
  92     <para><function>sd_id128_get_invocation()</function> returns the invocation ID of the currently executed
  93     service. In its current implementation, this reads and parses the <varname>$INVOCATION_ID</varname> environment
  94     variable that the service manager sets when activating a service, see
  95     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details. The
  96     ID is cached internally. In future a different mechanism to determine the invocation ID may be added.</para>
  97
  98     <para>Note that <function>sd_id128_get_boot()</function> and <function>sd_id128_get_invocation()</function> always
  99     return UUID v4 compatible IDs.  <function>sd_id128_get_machine()</function> will also return a UUID v4-compatible
 100     ID on new installations but might not on older.  It is possible to convert the machine ID into a UUID v4-compatible
 101     one. For more information, see
 102     <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 103
 104     <para>For more information about the <literal>sd_id128_t</literal>
 105     type see
 106     <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 107   </refsect1>
 108
 109   <refsect1>
 110     <title>Return Value</title>
 111
 112     <para>The two calls return 0 on success (in which case
 113     <parameter>ret</parameter> is filled in), or a negative
 114     errno-style error code.</para>
 115   </refsect1>
 116
 117   <refsect1>
 118     <title>Notes</title>
 119
 120     <para>The <function>sd_id128_get_machine()</function>, <function>sd_id128_get_boot()</function> and
 121     <function>sd_id128_get_invocation()</function> interfaces are available as a shared library, which can be compiled
 122     and linked to with the <literal>libsystemd</literal> <citerefentry
 123     project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para>
 124   </refsect1>
 125
 126   <refsect1>
 127     <title>See Also</title>
 128
 129     <para>
 130       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 131       <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 132       <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 133       <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 134       <citerefentry><refentrytitle>sd_id128_randomize</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 135       <citerefentry project='man-pages'><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry>
 136     </para>
 137   </refsect1>
 138
 139 </refentry>