1<?xml version='1.0'?> <!--*-nxml-*--> 2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> 4<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> 5 6<refentry id="sd_journal_query_unique" xmlns:xi="http://www.w3.org/2001/XInclude"> 7 8 <refentryinfo> 9 <title>sd_journal_query_unique</title> 10 <productname>systemd</productname> 11 </refentryinfo> 12 13 <refmeta> 14 <refentrytitle>sd_journal_query_unique</refentrytitle> 15 <manvolnum>3</manvolnum> 16 </refmeta> 17 18 <refnamediv> 19 <refname>sd_journal_query_unique</refname> 20 <refname>sd_journal_enumerate_unique</refname> 21 <refname>sd_journal_enumerate_available_unique</refname> 22 <refname>sd_journal_restart_unique</refname> 23 <refname>SD_JOURNAL_FOREACH_UNIQUE</refname> 24 <refpurpose>Read unique data fields from the journal</refpurpose> 25 </refnamediv> 26 27 <refsynopsisdiv> 28 <funcsynopsis> 29 <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo> 30 31 <funcprototype> 32 <funcdef>int <function>sd_journal_query_unique</function></funcdef> 33 <paramdef>sd_journal *<parameter>j</parameter></paramdef> 34 <paramdef>const char *<parameter>field</parameter></paramdef> 35 </funcprototype> 36 37 <funcprototype> 38 <funcdef>int <function>sd_journal_enumerate_available_unique</function></funcdef> 39 <paramdef>sd_journal *<parameter>j</parameter></paramdef> 40 <paramdef>const void **<parameter>data</parameter></paramdef> 41 <paramdef>size_t *<parameter>length</parameter></paramdef> 42 </funcprototype> 43 44 <funcprototype> 45 <funcdef>int <function>sd_journal_enumerate_unique</function></funcdef> 46 <paramdef>sd_journal *<parameter>j</parameter></paramdef> 47 <paramdef>const void **<parameter>data</parameter></paramdef> 48 <paramdef>size_t *<parameter>length</parameter></paramdef> 49 </funcprototype> 50 51 <funcprototype> 52 <funcdef>void <function>sd_journal_restart_unique</function></funcdef> 53 <paramdef>sd_journal *<parameter>j</parameter></paramdef> 54 </funcprototype> 55 56 <funcprototype> 57 <funcdef><function>SD_JOURNAL_FOREACH_UNIQUE</function></funcdef> 58 <paramdef>sd_journal *<parameter>j</parameter></paramdef> 59 <paramdef>const void *<parameter>data</parameter></paramdef> 60 <paramdef>size_t <parameter>length</parameter></paramdef> 61 </funcprototype> 62 63 </funcsynopsis> 64 </refsynopsisdiv> 65 66 <refsect1> 67 <title>Description</title> 68 69 <para><function>sd_journal_query_unique()</function> queries the journal for all unique values the 70 specified field can take. It takes two arguments: the journal to query and the field name to look 71 for. Well-known field names are listed on 72 <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>, 73 but any field can be specified. Field names must be specified without a trailing 74 <literal>=</literal>. After this function has been executed successfully the field values may be queried 75 using <function>sd_journal_enumerate_unique()</function> and 76 <function>sd_journal_enumerate_available_unique()</function>. Invoking one of those calls will change the 77 field name being queried and reset the enumeration index to the first field value that matches.</para> 78 79 <para><function>sd_journal_enumerate_unique()</function> may be used to iterate through all data fields 80 which match the previously selected field name as set with 81 <function>sd_journal_query_unique()</function>. On each invocation the next field data matching the field 82 name is returned. The order of the returned data fields is not defined. It takes three arguments: the 83 journal object, plus a pair of pointers to pointer/size variables where the data object and its size 84 shall be stored. The returned data is in a read-only memory map and is only valid until the next 85 invocation of <function>sd_journal_enumerate_unique()</function>. Note that the data returned will be 86 prefixed with the field name and <literal>=</literal>. Note that this call is subject to the data field 87 size threshold as controlled by <function>sd_journal_set_data_threshold()</function> and only the initial 88 part of the field up to the threshold is returned. An error is returned for fields which cannot be 89 retrieved. See the error list below for details.</para> 90 91 <para><function>sd_journal_enumerate_available_unique()</function> is similar to 92 <function>sd_journal_enumerate_unique()</function>, but silently skips any fields which may be valid, but 93 are too large or not supported by current implementation.</para> 94 95 <para><function>sd_journal_restart_unique()</function> resets the 96 data enumeration index to the beginning of the list. The next 97 invocation of <function>sd_journal_enumerate_unique()</function> 98 will return the first field data matching the field name 99 again.</para> 100 101 <para>Note that the <function>SD_JOURNAL_FOREACH_UNIQUE()</function> macro may be used as a handy wrapper 102 around <function>sd_journal_restart_unique()</function> and 103 <function>sd_journal_enumerate_available_unique()</function>.</para> 104 105 <para>Note that these functions currently are not influenced by 106 matches set with <function>sd_journal_add_match()</function> but 107 this might change in a later version of this software.</para> 108 109 <para>To enumerate all field names currently in use (and thus all suitable field parameters for 110 <function>sd_journal_query_unique()</function>), use the 111 <citerefentry><refentrytitle>sd_journal_enumerate_fields</refentrytitle><manvolnum>3</manvolnum></citerefentry> 112 call.</para> 113 </refsect1> 114 115 <refsect1> 116 <title>Return Value</title> 117 118 <para><function>sd_journal_query_unique()</function> returns 0 on success or a negative errno-style error 119 code. <function>sd_journal_enumerate_unique()</function> and 120 <function>sd_journal_query_available_unique()</function> return a positive integer if the next field data 121 has been read, 0 when no more fields remain, or a negative errno-style error code. 122 <function>sd_journal_restart_unique()</function> doesn't return anything.</para> 123 124 <refsect2> 125 <title>Errors</title> 126 127 <para>Returned errors may indicate the following problems:</para> 128 129 <variablelist> 130 <xi:include href="sd_journal_get_data.xml" xpointer="EINVAL"/> 131 <xi:include href="sd_journal_get_data.xml" xpointer="ECHILD"/> 132 <xi:include href="sd_journal_get_data.xml" xpointer="EADDRNOTAVAIL"/> 133 <xi:include href="sd_journal_get_data.xml" xpointer="ENOENT"/> 134 <xi:include href="sd_journal_get_data.xml" xpointer="ENOBUFS"/> 135 <xi:include href="sd_journal_get_data.xml" xpointer="E2BIG"/> 136 <xi:include href="sd_journal_get_data.xml" xpointer="EPROTONOSUPPORT"/> 137 <xi:include href="sd_journal_get_data.xml" xpointer="EBADMSG"/> 138 <xi:include href="sd_journal_get_data.xml" xpointer="EIO"/> 139 </variablelist> 140 </refsect2> 141 </refsect1> 142 143 <refsect1> 144 <title>Notes</title> 145 146 <xi:include href="threads-aware.xml" xpointer="strict"/> 147 148 <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> 149 </refsect1> 150 151 <refsect1> 152 <title>Examples</title> 153 154 <para>Use the <function>SD_JOURNAL_FOREACH_UNIQUE()</function> macro to iterate through all values a field 155 of the journal can take (and which can be accessed on the given architecture and are not compressed with 156 an unsupported mechanism). The following example lists all unit names referenced in the journal:</para> 157 158 <programlisting><xi:include href="journal-iterate-unique.c" parse="text" /></programlisting> 159 </refsect1> 160 161 <refsect1> 162 <title>See Also</title> 163 164 <para> 165 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 166 <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>, 167 <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 168 <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 169 <citerefentry><refentrytitle>sd_journal_enumerate_fields</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 170 <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 171 <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry> 172 </para> 173 </refsect1> 174 175</refentry> 176