1 <html><head><meta http-equiv=
"Content-Type" content=
"text/html; charset=UTF-8"><title>sd_journal_query_unique
</title><meta name=
"generator" content=
"DocBook XSL Stylesheets V1.78.1"></head><body bgcolor=
"white" text=
"black" link=
"#0000FF" vlink=
"#840084" alink=
"#0000FF"><style>
11 background-color: #c60f0f;
15 h1:hover
> a.headerlink, h2:hover
> a.headerlink, h3:hover
> a.headerlink, dt:hover
> a.headerlink {
18 </style><a href=
"index.html">Index
</a>·
19 <a href=
"systemd.directives.html">Directives
</a>·
20 <a href=
"../python-systemd/index.html">Python
</a>·
21 <a href=
"../libudev/index.html">libudev
</a>·
22 <a href=
"../libudev/index.html">gudev
</a><span style=
"float:right">systemd
208</span><hr><div class=
"refentry"><a name=
"sd_journal_query_unique"></a><div class=
"titlepage"></div><div class=
"refnamediv"><h2>Name
</h2><p>sd_journal_query_unique, sd_journal_enumerate_unique, sd_journal_restart_unique, SD_JOURNAL_FOREACH_UNIQUE — Read unique data fields from the journal
</p></div><div class=
"refsynopsisdiv"><h2>Synopsis
</h2><div class=
"funcsynopsis"><pre class=
"funcsynopsisinfo">#include
<systemd/sd-journal.h
></pre><table border=
"0" class=
"funcprototype-table" summary=
"Function synopsis" style=
"cellspacing: 0; cellpadding: 0;"><tr><td><code class=
"funcdef">int
<b class=
"fsfunc">sd_journal_query_unique
</b>(
</code></td><td>sd_journal*
<var class=
"pdparam">j
</var>,
</td></tr><tr><td> </td><td>const char*
<var class=
"pdparam">field
</var><code>)
</code>;
</td></tr></table><div class=
"funcprototype-spacer"> </div><table border=
"0" class=
"funcprototype-table" summary=
"Function synopsis" style=
"cellspacing: 0; cellpadding: 0;"><tr><td><code class=
"funcdef">int
<b class=
"fsfunc">sd_journal_enumerate_unique
</b>(
</code></td><td>sd_journal*
<var class=
"pdparam">j
</var>,
</td></tr><tr><td> </td><td>const void**
<var class=
"pdparam">data
</var>,
</td></tr><tr><td> </td><td>size_t*
<var class=
"pdparam">length
</var><code>)
</code>;
</td></tr></table><div class=
"funcprototype-spacer"> </div><table border=
"0" class=
"funcprototype-table" summary=
"Function synopsis" style=
"cellspacing: 0; cellpadding: 0;"><tr><td><code class=
"funcdef">void
<b class=
"fsfunc">sd_journal_restart_unique
</b>(
</code></td><td>sd_journal*
<var class=
"pdparam">j
</var><code>)
</code>;
</td></tr></table><div class=
"funcprototype-spacer"> </div><table border=
"0" class=
"funcprototype-table" summary=
"Function synopsis" style=
"cellspacing: 0; cellpadding: 0;"><tr><td><code class=
"funcdef"><b class=
"fsfunc">SD_JOURNAL_FOREACH_UNIQUE
</b>(
</code></td><td>sd_journal*
<var class=
"pdparam">j
</var>,
</td></tr><tr><td> </td><td>const void*
<var class=
"pdparam">data
</var>,
</td></tr><tr><td> </td><td>size_t
<var class=
"pdparam">length
</var><code>)
</code>;
</td></tr></table><div class=
"funcprototype-spacer"> </div></div></div><div class=
"refsect1"><a name=
"idm274683751280"></a><h2 id=
"Description">Description
<a class=
"headerlink" title=
"Permalink to this headline" href=
"#Description">¶
</a></h2><p><code class=
"function">sd_journal_query_unique()
</code>
23 queries the journal for all unique values the
24 specified field can take. It takes two arguments: the
25 journal to query and the field name to look
26 for. Well-known field names are listed on
27 <a href=
"systemd.journal-fields.html"><span class=
"citerefentry"><span class=
"refentrytitle">systemd.journal-fields
</span>(
7)
</span></a>. Field
28 names must be specified without a trailing '='. After
29 this function has been executed successfully the field
30 values may be queried using
31 <code class=
"function">sd_journal_enumerate_unique()
</code>. Invoking
32 this call a second time will change the field name
33 being queried and reset the enumeration index to the
34 first field value that matches.
</p><p><code class=
"function">sd_journal_enumerate_unique()
</code>
35 may be used to iterate through all data fields which
36 match the previously selected field name as set with
37 <code class=
"function">sd_journal_query_unique()
</code>. On
38 each invocation the next field data matching the field
39 name is returned. The order of the returned data
40 fields is not defined. It takes three arguments: the
41 journal context object, plus a pair of pointers to
42 pointer/size variables where the data object and its
43 size shall be stored in. The returned data is in a
44 read-only memory map and is only valid until the next
46 <code class=
"function">sd_journal_enumerate_unique()
</code>. Note
47 that the data returned will be prefixed with the field
48 name and '='. Note that this call is subject to the
49 data field size threshold as controlled by
50 <code class=
"function">sd_journal_set_data_threshold()
</code>.
</p><p><code class=
"function">sd_journal_restart_unique()
</code>
51 resets the data enumeration index to the beginning of
52 the list. The next invocation of
53 <code class=
"function">sd_journal_enumerate_unique()
</code>
54 will return the first field data matching the field
55 name again.
</p><p>Note that the
56 <code class=
"function">SD_JOURNAL_FOREACH_UNIQUE()
</code> macro
57 may be used as a handy wrapper around
58 <code class=
"function">sd_journal_restart_unique()
</code> and
59 <code class=
"function">sd_journal_enumerate_unique()
</code>.
</p><p>Note that these functions currently are not
60 influenced by matches set with
61 <code class=
"function">sd_journal_add_match()
</code> but this
62 might change in a later version of this
63 software.
</p></div><div class=
"refsect1"><a name=
"idm274683737440"></a><h2 id=
"Return Value">Return Value
<a class=
"headerlink" title=
"Permalink to this headline" href=
"#Return%20Value">¶
</a></h2><p><code class=
"function">sd_journal_query_unique()
</code>
64 returns
0 on success or a negative errno-style error
65 code.
<code class=
"function">sd_journal_enumerate_unique()
</code>
66 returns a positive integer if the next field data has
67 been read,
0 when no more fields are known, or a
68 negative errno-style error
69 code.
<code class=
"function">sd_journal_restart_unique()
</code>
70 returns nothing.
</p></div><div class=
"refsect1"><a name=
"idm274683726464"></a><h2 id=
"Notes">Notes
<a class=
"headerlink" title=
"Permalink to this headline" href=
"#Notes">¶
</a></h2><p>The
<code class=
"function">sd_journal_query_unique()
</code>,
71 <code class=
"function">sd_journal_enumerate_unique()
</code> and
72 <code class=
"function">sd_journal_restart_unique()
</code>
73 interfaces are available as shared library, which can
74 be compiled and linked to with the
75 <code class=
"constant">libsystemd-journal
</code> <a href=
"pkg-config.html"><span class=
"citerefentry"><span class=
"refentrytitle">pkg-config
</span>(
1)
</span></a>
76 file.
</p></div><div class=
"refsect1"><a name=
"idm274683721584"></a><h2 id=
"Examples">Examples
<a class=
"headerlink" title=
"Permalink to this headline" href=
"#Examples">¶
</a></h2><p>Use the
77 <code class=
"function">SD_JOURNAL_FOREACH_UNIQUE
</code> macro
78 to iterate through all values a field of the journal
79 can take. The following example lists all unit names
80 referenced in the journal:
</p><pre class=
"programlisting">#include
<stdio.h
>
81 #include
<string.h
>
82 #include
<systemd/sd-journal.h
>
84 int main(int argc, char *argv[]) {
90 r = sd_journal_open(
&j, SD_JOURNAL_LOCAL_ONLY);
92 fprintf(stderr,
"Failed to open journal: %s\n", strerror(-r));
95 r = sd_journal_query_unique(j,
"_SYSTEMD_UNIT");
97 fprintf(stderr,
"Failed to query journal: %s\n", strerror(-r));
100 SD_JOURNAL_FOREACH_UNIQUE(j, d, l)
101 printf(
"%.*s\n", (int) l, (const char*) d);
104 }
</pre></div><div class=
"refsect1"><a name=
"idm274683716976"></a><h2 id=
"See Also">See Also
<a class=
"headerlink" title=
"Permalink to this headline" href=
"#See%20Also">¶
</a></h2><p>
105 <a href=
"systemd.html"><span class=
"citerefentry"><span class=
"refentrytitle">systemd
</span>(
1)
</span></a>,
106 <a href=
"systemd.journal-fields.html"><span class=
"citerefentry"><span class=
"refentrytitle">systemd.journal-fields
</span>(
7)
</span></a>,
107 <a href=
"sd-journal.html"><span class=
"citerefentry"><span class=
"refentrytitle">sd-journal
</span>(
3)
</span></a>,
108 <a href=
"sd_journal_open.html"><span class=
"citerefentry"><span class=
"refentrytitle">sd_journal_open
</span>(
3)
</span></a>,
109 <a href=
"sd_journal_get_data.html"><span class=
"citerefentry"><span class=
"refentrytitle">sd_journal_get_data
</span>(
3)
</span></a>,
110 <a href=
"sd_journal_add_match.html"><span class=
"citerefentry"><span class=
"refentrytitle">sd_journal_add_match
</span>(
3)
</span></a>
111 </p></div></div></body></html>