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