man/sd_journal_query_unique.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   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-or-later -->
   5
   6 <refentry id="sd_journal_query_unique" xmlns:xi="http://www.w3.org/2001/XInclude">
   7
   8   <refentryinfo>
   9     <title>sd_journal_query_unique</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>sd_journal_query_unique</refentrytitle>
  15     <manvolnum>3</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>sd_journal_query_unique</refname>
  20     <refname>sd_journal_enumerate_unique</refname>
  21     <refname>sd_journal_enumerate_available_unique</refname>
  22     <refname>sd_journal_restart_unique</refname>
  23     <refname>SD_JOURNAL_FOREACH_UNIQUE</refname>
  24     <refpurpose>Read unique data fields from the journal</refpurpose>
  25   </refnamediv>
  26
  27   <refsynopsisdiv>
  28     <funcsynopsis>
  29       <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>
  30
  31       <funcprototype>
  32         <funcdef>int <function>sd_journal_query_unique</function></funcdef>
  33         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  34         <paramdef>const char *<parameter>field</parameter></paramdef>
  35       </funcprototype>
  36
  37       <funcprototype>
  38         <funcdef>int <function>sd_journal_enumerate_available_unique</function></funcdef>
  39         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  40         <paramdef>const void **<parameter>data</parameter></paramdef>
  41         <paramdef>size_t *<parameter>length</parameter></paramdef>
  42       </funcprototype>
  43
  44       <funcprototype>
  45         <funcdef>int <function>sd_journal_enumerate_unique</function></funcdef>
  46         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  47         <paramdef>const void **<parameter>data</parameter></paramdef>
  48         <paramdef>size_t *<parameter>length</parameter></paramdef>
  49       </funcprototype>
  50
  51       <funcprototype>
  52         <funcdef>void <function>sd_journal_restart_unique</function></funcdef>
  53         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  54       </funcprototype>
  55
  56       <funcprototype>
  57         <funcdef><function>SD_JOURNAL_FOREACH_UNIQUE</function></funcdef>
  58         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  59         <paramdef>const void *<parameter>data</parameter></paramdef>
  60         <paramdef>size_t <parameter>length</parameter></paramdef>
  61       </funcprototype>
  62
  63     </funcsynopsis>
  64   </refsynopsisdiv>
  65
  66   <refsect1>
  67     <title>Description</title>
  68
  69     <para><function>sd_journal_query_unique()</function> queries the journal for all unique values the
  70     specified field can take. It takes two arguments: the journal to query and the field name to look
  71     for. Well-known field names are listed on
  72     <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
  73     but any field can be specified. Field names must be specified without a trailing
  74     <literal>=</literal>. After this function has been executed successfully the field values may be queried
  75     using <function>sd_journal_enumerate_unique()</function> and
  76     <function>sd_journal_enumerate_available_unique()</function>. Invoking one of those calls will change the
  77     field name being queried and reset the enumeration index to the first field value that matches.</para>
  78
  79     <para><function>sd_journal_enumerate_unique()</function> may be used to iterate through all data fields
  80     which match the previously selected field name as set with
  81     <function>sd_journal_query_unique()</function>. On each invocation the next field data matching the field
  82     name is returned. The order of the returned data fields is not defined. It takes three arguments: the
  83     journal object, plus a pair of pointers to pointer/size variables where the data object and its size
  84     shall be stored. The returned data is in a read-only memory map and is only valid until the next
  85     invocation of <function>sd_journal_enumerate_unique()</function>. Note that the data returned will be
  86     prefixed with the field name and <literal>=</literal>. Note that this call is subject to the data field
  87     size threshold as controlled by <function>sd_journal_set_data_threshold()</function> and only the initial
  88     part of the field up to the threshold is returned. An error is returned for fields which cannot be
  89     retrieved. See the error list below for details.</para>
  90
  91     <para><function>sd_journal_enumerate_available_unique()</function> is similar to
  92     <function>sd_journal_enumerate_unique()</function>, but silently skips any fields which may be valid, but
  93     are too large or not supported by current implementation.</para>
  94
  95     <para><function>sd_journal_restart_unique()</function> resets the
  96     data enumeration index to the beginning of the list. The next
  97     invocation of <function>sd_journal_enumerate_unique()</function>
  98     will return the first field data matching the field name
  99     again.</para>
 100
 101     <para>Note that the <function>SD_JOURNAL_FOREACH_UNIQUE()</function> macro may be used as a handy wrapper
 102     around <function>sd_journal_restart_unique()</function> and
 103     <function>sd_journal_enumerate_available_unique()</function>.</para>
 104
 105     <para>Note that these functions currently are not influenced by
 106     matches set with <function>sd_journal_add_match()</function> but
 107     this might change in a later version of this software.</para>
 108
 109     <para>To enumerate all field names currently in use (and thus all suitable field parameters for
 110     <function>sd_journal_query_unique()</function>), use the
 111     <citerefentry><refentrytitle>sd_journal_enumerate_fields</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 112     call.</para>
 113   </refsect1>
 114
 115   <refsect1>
 116     <title>Return Value</title>
 117
 118     <para><function>sd_journal_query_unique()</function> returns 0 on success or a negative errno-style error
 119     code. <function>sd_journal_enumerate_unique()</function> and
 120     <function>sd_journal_query_available_unique()</function> return a positive integer if the next field data
 121     has been read, 0 when no more fields remain, or a negative errno-style error code.
 122     <function>sd_journal_restart_unique()</function> doesn't return anything.</para>
 123
 124     <refsect2>
 125       <title>Errors</title>
 126
 127       <para>Returned errors may indicate the following problems:</para>
 128
 129       <variablelist>
 130         <xi:include href="sd_journal_get_data.xml" xpointer="EINVAL"/>
 131         <xi:include href="sd_journal_get_data.xml" xpointer="ECHILD"/>
 132         <xi:include href="sd_journal_get_data.xml" xpointer="EADDRNOTAVAIL"/>
 133         <xi:include href="sd_journal_get_data.xml" xpointer="ENOENT"/>
 134         <xi:include href="sd_journal_get_data.xml" xpointer="ENOBUFS"/>
 135         <xi:include href="sd_journal_get_data.xml" xpointer="E2BIG"/>
 136         <xi:include href="sd_journal_get_data.xml" xpointer="EPROTONOSUPPORT"/>
 137         <xi:include href="sd_journal_get_data.xml" xpointer="EBADMSG"/>
 138         <xi:include href="sd_journal_get_data.xml" xpointer="EIO"/>
 139       </variablelist>
 140     </refsect2>
 141   </refsect1>
 142
 143   <refsect1>
 144     <title>Notes</title>
 145
 146     <xi:include href="threads-aware.xml" xpointer="strict"/>
 147
 148     <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
 149   </refsect1>
 150
 151   <refsect1>
 152     <title>Examples</title>
 153
 154     <para>Use the <function>SD_JOURNAL_FOREACH_UNIQUE()</function> macro to iterate through all values a field
 155     of the journal can take (and which can be accessed on the given architecture and are not compressed with
 156     an unsupported mechanism). The following example lists all unit names referenced in the journal:</para>
 157
 158     <programlisting><xi:include href="journal-iterate-unique.c" parse="text" /></programlisting>
 159   </refsect1>
 160
 161   <refsect1>
 162     <title>History</title>
 163     <para><function>sd_journal_query_unique()</function>,
 164     <function>sd_journal_enumerate_unique()</function>,
 165     <function>sd_journal_restart_unique()</function>, and
 166     <function>SD_JOURNAL_FOREACH_UNIQUE()</function> were added in version 195.</para>
 167     <para><function>sd_journal_enumerate_available_unique()</function> was added in version 246.</para>
 168   </refsect1>
 169
 170   <refsect1>
 171     <title>See Also</title>
 172
 173     <para>
 174       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 175       <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 176       <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 177       <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 178       <citerefentry><refentrytitle>sd_journal_enumerate_fields</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 179       <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 180       <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 181     </para>
 182   </refsect1>
 183
 184 </refentry>