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