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     <refpurpose>Retrieve 128-bit IDs</refpurpose>
  49   </refnamediv>
  50
  51   <refsynopsisdiv>
  52     <funcsynopsis>
  53       <funcsynopsisinfo>#include &lt;elogind/sd-id128.h&gt;</funcsynopsisinfo>
  54
  55       <funcprototype>
  56         <funcdef>int <function>sd_id128_get_machine</function></funcdef>
  57         <paramdef>sd_id128_t *<parameter>ret</parameter></paramdef>
  58       </funcprototype>
  59
  60       <funcprototype>
  61         <funcdef>int <function>sd_id128_get_boot</function></funcdef>
  62         <paramdef>sd_id128_t *<parameter>ret</parameter></paramdef>
  63       </funcprototype>
  64
  65     </funcsynopsis>
  66   </refsynopsisdiv>
  67
  68   <refsect1>
  69     <title>Description</title>
  70
  71     <para><function>sd_id128_get_machine()</function> returns the
  72     machine ID of the executing host. This reads and parses the
  73     <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  74     file. This function caches the machine ID internally to make
  75     retrieving the machine ID a cheap operation.</para>
  76
  77     <para><function>sd_id128_get_boot()</function> returns the boot ID
  78     of the executing kernel. This reads and parses the
  79     <filename>/proc/sys/kernel/random/boot_id</filename> file exposed
  80     by the kernel. It is randomly generated early at boot and is
  81     unique for every running kernel instance. See
  82     <citerefentry project='man-pages'><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry>
  83     for more information. This function also internally caches the
  84     returned ID to make this call a cheap operation.</para>
  85
  86     <para>Note that <function>sd_id128_get_boot()</function> always
  87     returns a UUID v4 compatible ID.
  88     <function>sd_id128_get_machine()</function> will also return a
  89     UUID v4-compatible ID on new installations but might not on older.
  90     It is possible to convert the machine ID into a UUID v4-compatible
  91     one. For more information, see
  92     <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
  93
  94     <para>For more information about the <literal>sd_id128_t</literal>
  95     type see
  96     <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
  97   </refsect1>
  98
  99   <refsect1>
 100     <title>Return Value</title>
 101
 102     <para>The two calls return 0 on success (in which case
 103     <parameter>ret</parameter> is filled in), or a negative
 104     errno-style error code.</para>
 105   </refsect1>
 106
 107   <refsect1>
 108     <title>Notes</title>
 109
 110     <para>The <function>sd_id128_get_machine()</function> and
 111     <function>sd_id128_get_boot()</function> interfaces are available
 112     as a shared library, which can be compiled and linked to with the
 113     <literal>libelogind</literal> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 114     file.</para>
 115   </refsect1>
 116
 117   <refsect1>
 118     <title>See Also</title>
 119
 120     <para>
 121       <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 122       <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 123       <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 124       <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry>,
 125       <citerefentry><refentrytitle>sd_id128_randomize</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 126     </para>
 127   </refsect1>
 128
 129 </refentry>