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 '='.</para>
 117
 118                 <para><function>sd_journal_restart_unique()</function>
 119                 resets the data enumeration index to the beginning of
 120                 the list. The next invocation of
 121                 <function>sd_journal_enumerate_unique()</function>
 122                 will return the first field data matching the field
 123                 name again.</para>
 124
 125                 <para>Note that the
 126                 <function>SD_JOURNAL_FOREACH_UNIQUE()</function> macro
 127                 may be used 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
 132                 influenced by matches set with
 133                 <function>sd_journal_add_match()</function> but this
 134                 might change in a later version of this
 135                 software.</para>
 136         </refsect1>
 137
 138         <refsect1>
 139                 <title>Return Value</title>
 140
 141                 <para><function>sd_journal_query_unique()</function>
 142                 returns 0 on success or a negative errno-style error
 143                 code. <function>sd_journal_enumerate_unique()</function>
 144                 returns a positive integer if the next field data has
 145                 been read, 0 when no more fields are known, or a
 146                 negative errno-style error
 147                 code. <function>sd_journal_restart_unique()</function>
 148                 returns nothing.</para>
 149         </refsect1>
 150
 151         <refsect1>
 152                 <title>Notes</title>
 153
 154                 <para>The <function>sd_journal_query_unique()</function>,
 155                 <function>sd_journal_enumerate_unique()</function> and
 156                 <function>sd_journal_restart_unique()</function>
 157                 interfaces are available as shared library, which can
 158                 be compiled and linked to with the
 159                 <literal>libsystemd-journal</literal>
 160                 <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 161                 file.</para>
 162         </refsect1>
 163
 164         <refsect1>
 165                 <title>Examples</title>
 166
 167                 <para>Use the
 168                 <function>SD_JOURNAL_FOREACH_UNIQUE</function> macro
 169                 to iterate through all values a field of the journal
 170                 can take. The following example lists all unit names
 171                 referenced in the journal:</para>
 172
 173                 <programlisting>#include &lt;stdio.h&gt;
 174 #include &lt;string.h&gt;
 175 #include &lt;systemd/sd-journal.h&gt;
 176
 177 int main(int argc, char *argv[]) {
 178         sd_journal *j;
 179         const void *d;
 180         size_t l;
 181         int r;
 182
 183         r = sd_journal_open(&amp;j, SD_JOURNAL_LOCAL_ONLY);
 184         if (r &lt; 0) {
 185                 fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
 186                 return 1;
 187         }
 188         r = sd_journal_query_unique(j, "_SYSTEMD_UNIT");
 189         if (r &lt; 0) {
 190                 fprintf(stderr, "Failed to query journal: %s\n", strerror(-r));
 191                 return 1;
 192         }
 193         SD_JOURNAL_FOREACH_UNIQUE(j, d, l)
 194                 printf("%.*s\n", (int) l, (const char*) d);
 195         sd_journal_close(j);
 196         return 0;
 197 }</programlisting>
 198
 199         </refsect1>
 200
 201         <refsect1>
 202                 <title>See Also</title>
 203
 204                 <para>
 205                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 206                         <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 207                         <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 208                         <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 209                         <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 210                         <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 211                 </para>
 212         </refsect1>
 213
 214 </refentry>