sd_journal_query_unique.xml revision 494a66821815e8109afa136bd42818b85da38c09
8a77240a809197c92c0736c431b4b88947a7bac1Christian Maeder<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
8a77240a809197c92c0736c431b4b88947a7bac1Christian Maeder "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder This file is part of systemd.
98890889ffb2e8f6f722b00e265a211f13b5a861Corneliu-Claudiu Prodescu Copyright 2012 Lennart Poettering
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski systemd is free software; you can redistribute it and/or modify it
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski under the terms of the GNU Lesser General Public License as published by
f3a94a197960e548ecd6520bb768cb0d547457bbChristian Maeder the Free Software Foundation; either version 2.1 of the License, or
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder (at your option) any later version.
adea2e45fa61f1097aadc490a0aeaf4831b729ccChristian Maeder systemd is distributed in the hope that it will be useful, but
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski WITHOUT ANY WARRANTY; without even the implied warranty of
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder Lesser General Public License for more details.
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder You should have received a copy of the GNU Lesser General Public License
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski along with systemd; If not, see <http://www.gnu.org/licenses/>.
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <refentryinfo>
ad270004874ce1d0697fb30d7309f180553bb315Christian Maeder <authorgroup>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski </authorgroup>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski </refentryinfo>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <refentrytitle>sd_journal_query_unique</refentrytitle>
556f473448dfcceee22afaa89ed7a364489cdbbbChristian Maeder <refname>sd_journal_enumerate_unique</refname>
556f473448dfcceee22afaa89ed7a364489cdbbbChristian Maeder <refname>sd_journal_restart_unique</refname>
556f473448dfcceee22afaa89ed7a364489cdbbbChristian Maeder <refname>SD_JOURNAL_FOREACH_UNIQUE</refname>
556f473448dfcceee22afaa89ed7a364489cdbbbChristian Maeder <refpurpose>Read unique data fields from the journal</refpurpose>
556f473448dfcceee22afaa89ed7a364489cdbbbChristian Maeder </refnamediv>
556f473448dfcceee22afaa89ed7a364489cdbbbChristian Maeder <refsynopsisdiv>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <funcsynopsis>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <funcsynopsisinfo>#include <systemd/sd-journal.h></funcsynopsisinfo>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <funcprototype>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <funcdef>int <function>sd_journal_query_unique</function></funcdef>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <paramdef>sd_journal* <parameter>j</parameter></paramdef>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <paramdef>const char* <parameter>field</parameter></paramdef>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski </funcprototype>
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <funcprototype>
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <funcdef>int <function>sd_journal_enumerate_unique</function></funcdef>
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <paramdef>sd_journal* <parameter>j</parameter></paramdef>
adea2e45fa61f1097aadc490a0aeaf4831b729ccChristian Maeder <paramdef>const void** <parameter>data</parameter></paramdef>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <paramdef>size_t* <parameter>length</parameter></paramdef>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski </funcprototype>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <funcprototype>
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <funcdef>void <function>sd_journal_restart_unique</function></funcdef>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <paramdef>sd_journal* <parameter>j</parameter></paramdef>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski </funcprototype>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <funcprototype>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <funcdef><function>SD_JOURNAL_FOREACH_UNIQUE</function></funcdef>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <paramdef>sd_journal* <parameter>j</parameter></paramdef>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <paramdef>const void* <parameter>data</parameter></paramdef>
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <paramdef>size_t <parameter>length</parameter></paramdef>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski </funcprototype>
556f473448dfcceee22afaa89ed7a364489cdbbbChristian Maeder </funcsynopsis>
adea2e45fa61f1097aadc490a0aeaf4831b729ccChristian Maeder </refsynopsisdiv>
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <para><function>sd_journal_query_unique()</function>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski queries the journal for all unique values the
4ef5e33657aae95850b7e6941f67ac1fb73cd13fChristian Maeder specified field can take. It takes two arguments: the
4ef5e33657aae95850b7e6941f67ac1fb73cd13fChristian Maeder journal to query and the field name to look
4ef5e33657aae95850b7e6941f67ac1fb73cd13fChristian Maeder for. Well-known field names are listed on
e7d2b3903c7b44db432538b0d720c21062c24823Christian Maeder <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>. Field
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski names must be specified without a trailing '='. After
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski this function has been executed successfully the field
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski values may be queried using
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <function>sd_journal_enumerate_unique()</function>. Invoking
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski this call a second time will change the field name
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski being queried and reset the enumeration index to the
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski first field value that matches.</para>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <para><function>sd_journal_enumerate_unique()</function>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski may be used to iterate through all data fields which
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder match the previously selected field name as set with
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <function>sd_journal_query_unique()</function>. On
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski each invocation the next field data matching the field
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski name is returned. The order of the returned data
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski fields is not defined. It takes three arguments: the
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski journal context object, plus a pair of pointers to
a98fd29a06e80e447af26d898044c23497adbc73Mihai Codescu pointer/size variables where the data object and its
a98fd29a06e80e447af26d898044c23497adbc73Mihai Codescu size shall be stored in. The returned data is in a
a98fd29a06e80e447af26d898044c23497adbc73Mihai Codescu read-only memory map and is only valid until the next
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski invocation of
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <function>sd_journal_enumerate_unique()</function>. Note
e7d2b3903c7b44db432538b0d720c21062c24823Christian Maeder that the data returned will be prefixed with the field
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder name and '='. Note that this call is subject to the
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski data field size threshold as controlled by
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <function>sd_journal_set_data_threshold()</function>.</para>
556f473448dfcceee22afaa89ed7a364489cdbbbChristian Maeder <para><function>sd_journal_restart_unique()</function>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski resets the data enumeration index to the beginning of
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski the list. The next invocation of
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <function>sd_journal_enumerate_unique()</function>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski will return the first field data matching the field
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder name again.</para>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <para>Note that the
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <function>SD_JOURNAL_FOREACH_UNIQUE()</function> macro
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski may be used as a handy wrapper around
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <function>sd_journal_restart_unique()</function> and
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <function>sd_journal_enumerate_unique()</function>.</para>
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski <para>Note that these functions currently are not
df11e5eab86d8247f58e301d8f0a2c6ecf4c9541Till Mossakowski influenced by matches set with
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <function>sd_journal_add_match()</function> but this
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder might change in a later version of this
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder software.</para>
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <para><function>sd_journal_query_unique()</function>
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder returns 0 on success or a negative errno-style error
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder code. <function>sd_journal_enumerate_unique()</function>
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder returns a positive integer if the next field data has
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder been read, 0 when no more fields are known, or a
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder negative errno-style error
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder code. <function>sd_journal_restart_unique()</function>
556f473448dfcceee22afaa89ed7a364489cdbbbChristian Maeder returns nothing.</para>
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <para>The <function>sd_journal_query_unique()</function>,
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <function>sd_journal_enumerate_unique()</function> and
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <function>sd_journal_restart_unique()</function>
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder interfaces are available as a shared library, which can
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder be compiled and linked to with the
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <constant>libsystemd-journal</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
556f473448dfcceee22afaa89ed7a364489cdbbbChristian Maeder <para>Use the
556f473448dfcceee22afaa89ed7a364489cdbbbChristian Maeder <function>SD_JOURNAL_FOREACH_UNIQUE</function> macro
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder to iterate through all values a field of the journal
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder can take. The following example lists all unit names
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder referenced in the journal:</para>
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder#include <string.h>
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maederint main(int argc, char *argv[]) {
556f473448dfcceee22afaa89ed7a364489cdbbbChristian Maeder sd_journal *j;
4d7d53fec6b551333c79da6ae3b8ca2af0a741abChristian Maeder const void *d;
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY);
d3c9318c22fcf44d9135a3b2c64f880b9a785babChristian Maeder if (r < 0) {
d3c9318c22fcf44d9135a3b2c64f880b9a785babChristian Maeder fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder r = sd_journal_query_unique(j, "_SYSTEMD_UNIT");
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder if (r < 0) {
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder fprintf(stderr, "Failed to query journal: %s\n", strerror(-r));
cd6e5706893519bfcf24539afa252fcbed5097ddKlaus Luettich SD_JOURNAL_FOREACH_UNIQUE(j, d, l)
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder printf("%.*s\n", (int) l, (const char*) d);
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder sd_journal_close(j);
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder}</programlisting>
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <citerefentry><refentrytitle>systemd.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
09b431a868c79a92ae7c9bd141565f43f9034144Christian Maeder <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>