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