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