man/sd_hwdb_new.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
   5
   6 <refentry id="sd_hwdb_new" xmlns:xi="http://www.w3.org/2001/XInclude">
   7   <refentryinfo>
   8     <title>sd_hwdb_new</title>
   9     <productname>systemd</productname>
  10   </refentryinfo>
  11
  12   <refmeta>
  13     <refentrytitle>sd_hwdb_new</refentrytitle>
  14     <manvolnum>3</manvolnum>
  15   </refmeta>
  16
  17   <refnamediv>
  18     <refname>sd_hwdb_new</refname>
  19     <refname>sd_hwdb_ref</refname>
  20     <refname>sd_hwdb_unref</refname>
  21
  22     <refpurpose>Create a new hwdb object and create or destroy references to it</refpurpose>
  23   </refnamediv>
  24
  25   <refsynopsisdiv>
  26     <funcsynopsis>
  27       <funcsynopsisinfo>#include &lt;systemd/sd-hwdb.h&gt;</funcsynopsisinfo>
  28
  29       <funcprototype>
  30         <funcdef>int <function>sd_hwdb_new</function></funcdef>
  31         <paramdef>sd_hwdb **<parameter>hwdb</parameter></paramdef>
  32       </funcprototype>
  33
  34       <funcprototype>
  35         <funcdef>sd_hwdb* <function>sd_hwdb_ref</function></funcdef>
  36         <paramdef>sd_hwdb *<parameter>hwdb</parameter></paramdef>
  37       </funcprototype>
  38
  39       <funcprototype>
  40         <funcdef>sd_hwdb* <function>sd_hwdb_unref</function></funcdef>
  41         <paramdef>sd_hwdb *<parameter>hwdb</parameter></paramdef>
  42       </funcprototype>
  43     </funcsynopsis>
  44   </refsynopsisdiv>
  45
  46   <refsect1>
  47     <title>Description</title>
  48
  49     <para><function>sd_hwdb_new()</function> creates a new hwdb object to access the binary hwdb
  50     database. Upon initialization, the file containing the binary representation of the hardware database is
  51     located and opened. The new object is returned in <parameter>hwdb</parameter>.</para>
  52
  53     <para>The <parameter>hwdb</parameter> object is reference counted. <function>sd_hwdb_ref()</function> and
  54     <function>sd_hwdb_unref()</function> may be used to get a new reference or destroy an existing reference
  55     to an object. The caller must dispose of the reference acquired with <function>sd_hwdb_new()</function>
  56     by calling <function>sd_hwdb_unref()</function> when done with the object.</para>
  57
  58     <para>Use
  59     <citerefentry><refentrytitle>sd_hwdb_seek</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  60     <citerefentry><refentrytitle>sd_hwdb_get</refentrytitle><manvolnum>3</manvolnum></citerefentry>, and
  61     <citerefentry><refentrytitle>sd_hwdb_enumerate</refentrytitle><manvolnum>3</manvolnum></citerefentry> to
  62     access entries.</para>
  63   </refsect1>
  64
  65   <refsect1>
  66     <title>Return Value</title>
  67
  68     <para>On success, <function>sd_hwdb_new()</function> returns a non-negative integer. On
  69     failure, it returns a negative errno-style error code.</para>
  70
  71     <para><function>sd_hwdb_ref()</function> always returns the argument.
  72     </para>
  73
  74     <para><function>sd_hwdb_unref()</function> always returns <constant>NULL</constant>.
  75     </para>
  76
  77     <refsect2>
  78       <title>Errors</title>
  79
  80       <para>Returned errors may indicate the following problems:</para>
  81
  82       <variablelist>
  83         <varlistentry>
  84           <term><constant>-ENOENT</constant></term>
  85
  86           <listitem><para>The binary hardware database file could not be located. See
  87           <citerefentry><refentrytitle>systemd-hwdb</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  88           for more information.</para>
  89           </listitem>
  90         </varlistentry>
  91
  92         <varlistentry>
  93           <term><constant>-EINVAL</constant></term>
  94
  95           <listitem><para>The located binary hardware database file is in an incompatible format.
  96           </para></listitem>
  97         </varlistentry>
  98
  99         <varlistentry>
 100           <term><constant>-ENOMEM</constant></term>
 101
 102           <listitem><para>Memory allocation failed.</para></listitem>
 103         </varlistentry>
 104       </variablelist>
 105     </refsect2>
 106   </refsect1>
 107
 108   <xi:include href="libsystemd-pkgconfig.xml" />
 109
 110   <refsect1>
 111     <title>See Also</title>
 112
 113     <para>
 114       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 115       <citerefentry><refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 116       <citerefentry><refentrytitle>sd-hwdb</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 117       <citerefentry><refentrytitle>systemd-hwdb</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 118     </para>
 119   </refsect1>
 120
 121 </refentry>