man/sd_journal_query_unique.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   SPDX-License-Identifier: LGPL-2.1+
   7 -->
   8
   9 <refentry id="sd_journal_query_unique" xmlns:xi="http://www.w3.org/2001/XInclude">
  10
  11   <refentryinfo>
  12     <title>sd_journal_query_unique</title>
  13     <productname>systemd</productname>
  14
  15     <authorgroup>
  16       <author>
  17         <contrib>Developer</contrib>
  18         <firstname>Lennart</firstname>
  19         <surname>Poettering</surname>
  20         <email>lennart@poettering.net</email>
  21       </author>
  22     </authorgroup>
  23   </refentryinfo>
  24
  25   <refmeta>
  26     <refentrytitle>sd_journal_query_unique</refentrytitle>
  27     <manvolnum>3</manvolnum>
  28   </refmeta>
  29
  30   <refnamediv>
  31     <refname>sd_journal_query_unique</refname>
  32     <refname>sd_journal_enumerate_unique</refname>
  33     <refname>sd_journal_restart_unique</refname>
  34     <refname>SD_JOURNAL_FOREACH_UNIQUE</refname>
  35     <refpurpose>Read unique data fields from the journal</refpurpose>
  36   </refnamediv>
  37
  38   <refsynopsisdiv>
  39     <funcsynopsis>
  40       <funcsynopsisinfo>#include &lt;systemd/sd-journal.h&gt;</funcsynopsisinfo>
  41
  42       <funcprototype>
  43         <funcdef>int <function>sd_journal_query_unique</function></funcdef>
  44         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  45         <paramdef>const char *<parameter>field</parameter></paramdef>
  46       </funcprototype>
  47
  48       <funcprototype>
  49         <funcdef>int <function>sd_journal_enumerate_unique</function></funcdef>
  50         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  51         <paramdef>const void **<parameter>data</parameter></paramdef>
  52         <paramdef>size_t *<parameter>length</parameter></paramdef>
  53       </funcprototype>
  54
  55       <funcprototype>
  56         <funcdef>void <function>sd_journal_restart_unique</function></funcdef>
  57         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  58       </funcprototype>
  59
  60       <funcprototype>
  61         <funcdef><function>SD_JOURNAL_FOREACH_UNIQUE</function></funcdef>
  62         <paramdef>sd_journal *<parameter>j</parameter></paramdef>
  63         <paramdef>const void *<parameter>data</parameter></paramdef>
  64         <paramdef>size_t <parameter>length</parameter></paramdef>
  65       </funcprototype>
  66
  67     </funcsynopsis>
  68   </refsynopsisdiv>
  69
  70   <refsect1>
  71     <title>Description</title>
  72
  73     <para><function>sd_journal_query_unique()</function> queries the
  74     journal for all unique values the specified field can take. It
  75     takes two arguments: the journal to query and the field name to
  76     look for. Well-known field names are listed on
  77     <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
  78     Field names must be specified without a trailing '='. After this
  79     function has been executed successfully the field values may be
  80     queried using <function>sd_journal_enumerate_unique()</function>.
  81     Invoking this call a second time will change the field name being
  82     queried and reset the enumeration index to the first field value
  83     that matches.</para>
  84
  85     <para><function>sd_journal_enumerate_unique()</function> may be
  86     used to iterate through all data fields which match the previously
  87     selected field name as set with
  88     <function>sd_journal_query_unique()</function>. On each invocation
  89     the next field data matching the field name is returned. The order
  90     of the returned data fields is not defined. It takes three
  91     arguments: the journal context object, plus a pair of pointers to
  92     pointer/size variables where the data object and its size shall be
  93     stored in. The returned data is in a read-only memory map and is
  94     only valid until the next invocation of
  95     <function>sd_journal_enumerate_unique()</function>. Note that the
  96     data returned will be prefixed with the field name and '='. Note
  97     that this call is subject to the data field size threshold as
  98     controlled by
  99     <function>sd_journal_set_data_threshold()</function>.</para>
 100
 101     <para><function>sd_journal_restart_unique()</function> resets the
 102     data enumeration index to the beginning of the list. The next
 103     invocation of <function>sd_journal_enumerate_unique()</function>
 104     will return the first field data matching the field name
 105     again.</para>
 106
 107     <para>Note that the
 108     <function>SD_JOURNAL_FOREACH_UNIQUE()</function> macro may be used
 109     as a handy wrapper around
 110     <function>sd_journal_restart_unique()</function> and
 111     <function>sd_journal_enumerate_unique()</function>.</para>
 112
 113     <para>Note that these functions currently are not influenced by
 114     matches set with <function>sd_journal_add_match()</function> but
 115     this might change in a later version of this software.</para>
 116
 117     <para>To enumerate all field names currently in use (and thus all suitable field parameters for
 118     <function>sd_journal_query_unique()</function>), use the
 119     <citerefentry><refentrytitle>sd_journal_enumerate_fields</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 120     call.</para>
 121   </refsect1>
 122
 123   <refsect1>
 124     <title>Return Value</title>
 125
 126     <para><function>sd_journal_query_unique()</function> returns 0 on
 127     success or a negative errno-style error code.
 128     <function>sd_journal_enumerate_unique()</function> returns a
 129     positive integer if the next field data has been read, 0 when no
 130     more fields are known, or a negative errno-style error code.
 131     <function>sd_journal_restart_unique()</function> returns
 132     nothing.</para>
 133   </refsect1>
 134
 135   <refsect1>
 136     <title>Notes</title>
 137
 138     <para>All functions listed here are thread-agnostic and only a single thread may operate
 139     on a given <structname>sd_journal</structname> object.</para>
 140
 141     <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
 142   </refsect1>
 143
 144   <refsect1>
 145     <title>Examples</title>
 146
 147     <para>Use the <function>SD_JOURNAL_FOREACH_UNIQUE</function> macro
 148     to iterate through all values a field of the journal can take. The
 149     following example lists all unit names referenced in the
 150     journal:</para>
 151
 152     <programlisting>#include &lt;stdio.h&gt;
 153 #include &lt;string.h&gt;
 154 #include &lt;systemd/sd-journal.h&gt;
 155
 156 int main(int argc, char *argv[]) {
 157         sd_journal *j;
 158         const void *d;
 159         size_t l;
 160         int r;
 161
 162         r = sd_journal_open(&amp;j, SD_JOURNAL_LOCAL_ONLY);
 163         if (r &lt; 0) {
 164                 fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
 165                 return 1;
 166         }
 167         r = sd_journal_query_unique(j, "_SYSTEMD_UNIT");
 168         if (r &lt; 0) {
 169                 fprintf(stderr, "Failed to query journal: %s\n", strerror(-r));
 170                 return 1;
 171         }
 172         SD_JOURNAL_FOREACH_UNIQUE(j, d, l)
 173                 printf("%.*s\n", (int) l, (const char*) d);
 174         sd_journal_close(j);
 175         return 0;
 176 }</programlisting>
 177
 178   </refsect1>
 179
 180   <refsect1>
 181     <title>See Also</title>
 182
 183     <para>
 184       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 185       <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 186       <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 187       <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 188       <citerefentry><refentrytitle>sd_journal_enumerate_fields</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 189       <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 190       <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 191     </para>
 192   </refsect1>
 193
 194 </refentry>