<para><command>loginctl</command> may be used to introspect and
control the state of the
- <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>
login manager.</para>
</refsect1>
<constant>SIGTERM</constant>.</para></listitem>
</varlistentry>
- <varlistentry>
- <term><option>-n</option></term>
- <term><option>--lines=</option></term>
-
- <listitem><para>When used with <command>user-status</command>
- and <command>session-status</command>, controls the number of
- journal lines to show, counting from the most recent ones.
- Takes a positive integer argument. Defaults to 10.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>-o</option></term>
- <term><option>--output=</option></term>
-
- <listitem><para>When used with <command>user-status</command>
- and <command>session-status</command>, controls the formatting
- of the journal entries that are shown. For the available
- choices, see
- <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
- Defaults to <literal>short</literal>.</para></listitem>
- </varlistentry>
-
<xi:include href="user-system-options.xml" xpointer="host" />
<xi:include href="user-system-options.xml" xpointer="machine" />
<term><command>session-status</command> <optional><replaceable>ID</replaceable>...</optional></term>
<listitem><para>Show terse runtime status information about
- one or more sessions, followed by the most recent log data
- from the journal. Takes one or more session identifiers as
+ one or more sessions. Takes one or more session identifiers as
parameters. If no session identifiers are passed the status of
the caller's session is shown. This function is intended to
generate human-readable output. If you are looking for
<term><command>user-status</command> <optional><replaceable>USER</replaceable>...</optional></term>
<listitem><para>Show terse runtime status information about
- one or more logged in users, followed by the most recent log
- data from the journal. Takes one or more user names or numeric
+ one or more logged in users. Takes one or more user names or numeric
user IDs as parameters. If no parameters are passed the status
of the caller's user is shown. This function is intended to
generate human-readable output. If you are looking for
</varlistentry>
</variablelist></refsect2>
+ <refsect2><title>System Commands</title><variablelist>
+ </variablelist></refsect2>
+ <varlistentry>
+ <term><command>poweroff</command></term>
+
+ <listitem>
+ <para>Print a wall message to all users, shut down and
+ power-off the system.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><command>reboot <optional><replaceable>arg</replaceable></optional></command></term>
+
+ <listitem>
+ <para>Print a wall message to all users, shut down and
+ reboot the system.</para>
+
+ <para>If the optional argument
+ <replaceable>arg</replaceable> is given, it will be passed
+ as the optional argument to the
+ <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+ system call. The value is architecture and firmware
+ specific. As an example, <literal>recovery</literal> might
+ be used to trigger system recovery, and
+ <literal>fota</literal> might be used to trigger a
+ <quote>firmware over the air</quote> update.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><command>suspend</command></term>
+
+ <listitem>
+ <para>Suspend the system.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><command>hibernate</command></term>
+
+ <listitem>
+ <para>Hibernate the system.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><command>hybrid-sleep</command></term>
+
+ <listitem>
+ <para>Hibernate and suspend the system.</para>
+ </listitem>
+ </varlistentry>
</refsect1>
-
<refsect1>
<title>Exit status</title>
<refsect1>
<title>See Also</title>
<para>
- <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
</para>
<title>Description</title>
<para>These files configure various parameters of the elogind
- login manager,
- <citerefentry><refentrytitle>logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
- </para>
+ login manager.</para>
</refsect1>
<xi:include href="standard-conf.xml" xpointer="main-conf" />
<refsect1>
<title>Options</title>
- <para>All options are configured in the
- <literal>[Login]</literal> section:</para>
-
- <variablelist>
-
- <varlistentry>
- <term><varname>KillUserProcesses=</varname></term>
-
- <listitem><para>Takes a boolean argument. Configures whether
- the processes of a user should be killed when the user
- completely logs out (i.e. after the user's last session
- ended). Defaults to <literal>no</literal>.</para>
-
- <para>Note that setting <varname>KillUserProcesses=1</varname>
- will break tools like
- <citerefentry project='die-net'><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>KillOnlyUsers=</varname></term>
- <term><varname>KillExcludeUsers=</varname></term>
-
- <listitem><para>These settings take space-separated lists of
- usernames that influence the effect of
- <varname>KillUserProcesses=</varname>. If not empty, only
- processes of users listed in <varname>KillOnlyUsers=</varname>
- will be killed when they log out entirely. Processes of users
- listed in <varname>KillExcludeUsers=</varname> are excluded
- from being killed. <varname>KillExcludeUsers=</varname>
- defaults to <literal>root</literal> and takes precedence over
- <varname>KillOnlyUsers=</varname>, which defaults to the empty
- list.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>IdleAction=</varname></term>
-
- <listitem><para>Configures the action to take when the system
- is idle. Takes one of
- <literal>ignore</literal>,
- <literal>poweroff</literal>,
- <literal>reboot</literal>,
- <literal>halt</literal>,
- <literal>kexec</literal>,
- <literal>suspend</literal>,
- <literal>hibernate</literal>,
- <literal>hybrid-sleep</literal>, and
- <literal>lock</literal>.
- Defaults to <literal>ignore</literal>.</para>
-
- <para>Note that this requires that user sessions correctly
- report the idle status to the system. The system will execute
- the action after all sessions report that they are idle, no
- idle inhibitor lock is active, and subsequently, the time
- configured with <varname>IdleActionSec=</varname> (see below)
- has expired.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>IdleActionSec=</varname></term>
-
- <listitem><para>Configures the delay after which the action
- configured in <varname>IdleAction=</varname> (see above) is
- taken after the system is idle.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>InhibitDelayMaxSec=</varname></term>
-
- <listitem><para>Specifies the maximum time a system shutdown
- or sleep request is delayed due to an inhibitor lock of type
- <literal>delay</literal> being active before the inhibitor is
- ignored and the operation executes anyway. Defaults to
- 5.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>HandlePowerKey=</varname></term>
- <term><varname>HandleSuspendKey=</varname></term>
- <term><varname>HandleHibernateKey=</varname></term>
- <term><varname>HandleLidSwitch=</varname></term>
- <term><varname>HandleLidSwitchDocked=</varname></term>
-
- <listitem><para>Controls whether logind shall handle the
- system power and sleep keys and the lid switch to trigger
- actions such as system power-off or suspend. Can be one of
- <literal>ignore</literal>,
- <literal>poweroff</literal>,
- <literal>reboot</literal>,
- <literal>halt</literal>,
- <literal>kexec</literal>,
- <literal>suspend</literal>,
- <literal>hibernate</literal>,
- <literal>hybrid-sleep</literal>, and
- <literal>lock</literal>.
- If <literal>ignore</literal>, logind will never handle these
- keys. If <literal>lock</literal>, all running sessions will be
- screen-locked; otherwise, the specified action will be taken
- in the respective event. Only input devices with the
- <literal>power-switch</literal> udev tag will be watched for
- key/lid switch events. <varname>HandlePowerKey=</varname>
- defaults to <literal>poweroff</literal>.
- <varname>HandleSuspendKey=</varname> and
- <varname>HandleLidSwitch=</varname> default to
- <literal>suspend</literal>.
- <varname>HandleLidSwitchDocked=</varname> defaults to
- <literal>ignore</literal>.
- <varname>HandleHibernateKey=</varname> defaults to
- <literal>hibernate</literal>. If the system is inserted in a
- docking station, or if more than one display is connected, the
- action specified by <varname>HandleLidSwitchDocked=</varname>
- occurs; otherwise the <varname>HandleLidSwitch=</varname>
- action occurs.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>PowerKeyIgnoreInhibited=</varname></term>
- <term><varname>SuspendKeyIgnoreInhibited=</varname></term>
- <term><varname>HibernateKeyIgnoreInhibited=</varname></term>
- <term><varname>LidSwitchIgnoreInhibited=</varname></term>
-
- <listitem><para>Controls whether actions triggered by the
- power and sleep keys and the lid switch are subject to
- inhibitor locks. These settings take boolean arguments. If
- <literal>no</literal>, the inhibitor locks taken by
- applications in order to block the requested operation are
- respected. If <literal>yes</literal>, the requested operation
- is executed in any case.
- <varname>PowerKeyIgnoreInhibited=</varname>,
- <varname>SuspendKeyIgnoreInhibited=</varname> and
- <varname>HibernateKeyIgnoreInhibited=</varname> default to
- <literal>no</literal>.
- <varname>LidSwitchIgnoreInhibited=</varname> defaults to
- <literal>yes</literal>. This means that the lid switch does
- not respect suspend blockers by default, but the power and
- sleep keys do. </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>HoldoffTimeoutSec=</varname></term>
-
- <listitem><para>Specifies the timeout after system startup or
- system resume in which elogind will hold off on reacting to
- LID events. This is required for the system to properly
- detect any hotplugged devices so elogind can ignore LID events
- if external monitors, or docks, are connected. If set to 0,
- elogind will always react immediately, possibly before the
- kernel fully probed all hotplugged devices. This is safe, as
- long as you do not care for elogind to account for devices
- that have been plugged or unplugged while the system was off.
- Defaults to 30s.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>RuntimeDirectorySize=</varname></term>
-
- <listitem><para>Sets the size limit on the
- <varname>$XDG_RUNTIME_DIR</varname> runtime directory for each
- user who logs in. Takes a size in bytes, optionally suffixed
- with the usual K, G, M, and T suffixes, to the base 1024
- (IEC). Alternatively, a numerical percentage suffixed by
- <literal>%</literal> may be specified, which sets the size
- limit relative to the amount of physical RAM. Defaults to 10%.
- Note that this size is a safety limit only. As each runtime
- directory is a tmpfs file system, it will only consume as much
- memory as is needed. </para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>RemoveIPC=</varname></term>
-
- <listitem><para>Controls whether System V and POSIX IPC objects belonging to the user shall be removed when the
- user fully logs out. Takes a boolean argument. If enabled, the user may not consume IPC resources after the
- last of the user's sessions terminated. This covers System V semaphores, shared memory and message queues, as
- well as POSIX shared memory and message queues. Note that IPC objects of the root user and other system users
- are excluded from the effect of this setting. Defaults to <literal>yes</literal>.</para></listitem>
- </varlistentry>
-
- </variablelist>
+ <para>All login options are configured in the
+ <literal>[Login]</literal> section, system sleep options are
+ configured in the <literal>[Sleep]</literal> section.</para>
+
+ <refsect2><title>[Login] section:</title>
+ <variablelist>
+
+ <varlistentry>
+ <term><varname>KillUserProcesses=</varname></term>
+
+ <listitem><para>Takes a boolean argument. Configures whether
+ the processes of a user should be killed when the user
+ completely logs out (i.e. after the user's last session
+ ended). Defaults to <literal>no</literal>.</para>
+
+ <para>Note that setting <varname>KillUserProcesses=1</varname>
+ will break tools like
+ <citerefentry project='die-net'><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>KillOnlyUsers=</varname></term>
+ <term><varname>KillExcludeUsers=</varname></term>
+
+ <listitem><para>These settings take space-separated lists of
+ usernames that influence the effect of
+ <varname>KillUserProcesses=</varname>. If not empty, only
+ processes of users listed in <varname>KillOnlyUsers=</varname>
+ will be killed when they log out entirely. Processes of users
+ listed in <varname>KillExcludeUsers=</varname> are excluded
+ from being killed. <varname>KillExcludeUsers=</varname>
+ defaults to <literal>root</literal> and takes precedence over
+ <varname>KillOnlyUsers=</varname>, which defaults to the empty
+ list.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>IdleAction=</varname></term>
+
+ <listitem><para>Configures the action to take when the system
+ is idle. Takes one of
+ <literal>ignore</literal>,
+ <literal>poweroff</literal>,
+ <literal>reboot</literal>,
+ <literal>halt</literal>,
+ <literal>kexec</literal>,
+ <literal>suspend</literal>,
+ <literal>hibernate</literal>,
+ <literal>hybrid-sleep</literal>, and
+ <literal>lock</literal>.
+ Defaults to <literal>ignore</literal>.</para>
+
+ <para>Note that this requires that user sessions correctly
+ report the idle status to the system. The system will execute
+ the action after all sessions report that they are idle, no
+ idle inhibitor lock is active, and subsequently, the time
+ configured with <varname>IdleActionSec=</varname> (see below)
+ has expired.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>IdleActionSec=</varname></term>
+
+ <listitem><para>Configures the delay after which the action
+ configured in <varname>IdleAction=</varname> (see above) is
+ taken after the system is idle.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>InhibitDelayMaxSec=</varname></term>
+
+ <listitem><para>Specifies the maximum time a system shutdown
+ or sleep request is delayed due to an inhibitor lock of type
+ <literal>delay</literal> being active before the inhibitor is
+ ignored and the operation executes anyway. Defaults to
+ 5.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>HandlePowerKey=</varname></term>
+ <term><varname>HandleSuspendKey=</varname></term>
+ <term><varname>HandleHibernateKey=</varname></term>
+ <term><varname>HandleLidSwitch=</varname></term>
+ <term><varname>HandleLidSwitchDocked=</varname></term>
+
+ <listitem><para>Controls whether logind shall handle the
+ system power and sleep keys and the lid switch to trigger
+ actions such as system power-off or suspend. Can be one of
+ <literal>ignore</literal>,
+ <literal>poweroff</literal>,
+ <literal>reboot</literal>,
+ <literal>halt</literal>,
+ <literal>kexec</literal>,
+ <literal>suspend</literal>,
+ <literal>hibernate</literal>,
+ <literal>hybrid-sleep</literal>, and
+ <literal>lock</literal>.
+ If <literal>ignore</literal>, logind will never handle these
+ keys. If <literal>lock</literal>, all running sessions will be
+ screen-locked; otherwise, the specified action will be taken
+ in the respective event. Only input devices with the
+ <literal>power-switch</literal> udev tag will be watched for
+ key/lid switch events. <varname>HandlePowerKey=</varname>
+ defaults to <literal>poweroff</literal>.
+ <varname>HandleSuspendKey=</varname> and
+ <varname>HandleLidSwitch=</varname> default to
+ <literal>suspend</literal>.
+ <varname>HandleLidSwitchDocked=</varname> defaults to
+ <literal>ignore</literal>.
+ <varname>HandleHibernateKey=</varname> defaults to
+ <literal>hibernate</literal>. If the system is inserted in a
+ docking station, or if more than one display is connected, the
+ action specified by <varname>HandleLidSwitchDocked=</varname>
+ occurs; otherwise the <varname>HandleLidSwitch=</varname>
+ action occurs.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>PowerKeyIgnoreInhibited=</varname></term>
+ <term><varname>SuspendKeyIgnoreInhibited=</varname></term>
+ <term><varname>HibernateKeyIgnoreInhibited=</varname></term>
+ <term><varname>LidSwitchIgnoreInhibited=</varname></term>
+
+ <listitem><para>Controls whether actions triggered by the
+ power and sleep keys and the lid switch are subject to
+ inhibitor locks. These settings take boolean arguments. If
+ <literal>no</literal>, the inhibitor locks taken by
+ applications in order to block the requested operation are
+ respected. If <literal>yes</literal>, the requested operation
+ is executed in any case.
+ <varname>PowerKeyIgnoreInhibited=</varname>,
+ <varname>SuspendKeyIgnoreInhibited=</varname> and
+ <varname>HibernateKeyIgnoreInhibited=</varname> default to
+ <literal>no</literal>.
+ <varname>LidSwitchIgnoreInhibited=</varname> defaults to
+ <literal>yes</literal>. This means that the lid switch does
+ not respect suspend blockers by default, but the power and
+ sleep keys do. </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>HoldoffTimeoutSec=</varname></term>
+
+ <listitem><para>Specifies the timeout after system startup or
+ system resume in which elogind will hold off on reacting to
+ LID events. This is required for the system to properly
+ detect any hotplugged devices so elogind can ignore LID events
+ if external monitors, or docks, are connected. If set to 0,
+ elogind will always react immediately, possibly before the
+ kernel fully probed all hotplugged devices. This is safe, as
+ long as you do not care for elogind to account for devices
+ that have been plugged or unplugged while the system was off.
+ Defaults to 30s.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>RuntimeDirectorySize=</varname></term>
+
+ <listitem><para>Sets the size limit on the
+ <varname>$XDG_RUNTIME_DIR</varname> runtime directory for each
+ user who logs in. Takes a size in bytes, optionally suffixed
+ with the usual K, G, M, and T suffixes, to the base 1024
+ (IEC). Alternatively, a numerical percentage suffixed by
+ <literal>%</literal> may be specified, which sets the size
+ limit relative to the amount of physical RAM. Defaults to 10%.
+ Note that this size is a safety limit only. As each runtime
+ directory is a tmpfs file system, it will only consume as much
+ memory as is needed. </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>RemoveIPC=</varname></term>
+
+ <listitem><para>Controls whether System V and POSIX IPC objects belonging to the user shall be removed when the
+ user fully logs out. Takes a boolean argument. If enabled, the user may not consume IPC resources after the
+ last of the user's sessions terminated. This covers System V semaphores, shared memory and message queues, as
+ well as POSIX shared memory and message queues. Note that IPC objects of the root user and other system users
+ are excluded from the effect of this setting. Defaults to <literal>yes</literal>.</para></listitem>
+ </varlistentry>
+
+ </variablelist>
+ </refsect2>
+
+ <refsect2><title>[Sleep] section:</title>
+
+ <para><command>elogind</command> supports three general
+ power-saving modes:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>suspend</term>
+
+ <listitem><para>a low-power state
+ where execution of the OS is paused,
+ and complete power loss might result
+ in lost data, and which is fast to
+ enter and exit. This corresponds to
+ suspend, standby, or freeze states as
+ understood by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>hibernate</term>
+
+ <listitem><para>a low-power state
+ where execution of the OS is paused,
+ and complete power loss does not
+ result in lost data, and which might
+ be slow to enter and exit. This
+ corresponds to the hibernation as
+ understood by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>hybrid-sleep</term>
+
+ <listitem><para>a low-power state
+ where execution of the OS is paused,
+ which might be slow to enter, and on
+ complete power loss does not result in
+ lost data but might be slower to exit
+ in that case. This mode is called
+ suspend-to-both by the kernel.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>SuspendMode=</varname></term>
+ <term><varname>HibernateMode=</varname></term>
+ <term><varname>HybridSleepMode=</varname></term>
+
+ <listitem><para>The string to be written to
+ <filename>/sys/power/disk</filename> by elogind.
+ More than one value can be specified by separating
+ multiple values with whitespace. They will be tried
+ in turn, until one is written without error. If
+ neither succeeds, the operation will be aborted.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>SuspendState=</varname></term>
+ <term><varname>HibernateState=</varname></term>
+ <term><varname>HybridSleepState=</varname></term>
+
+ <listitem><para>The string to be written to
+ <filename>/sys/power/state</filename> by elogind.
+ More than one value can be specified by separating
+ multiple values with whitespace. They will be tried
+ in turn, until one is written without error. If
+ neither succeeds, the operation will be aborted.
+ </para></listitem>
+ </varlistentry>
+
+ </variablelist>
+ </refsect2>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
- <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>elogind-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
</para>
</refsect1>
+++ /dev/null
-<?xml version='1.0'?> <!--*-nxml-*-->
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
-
-<!--
- This file is part of elogind.
-
- Copyright 2016 Lennart Poettering
-
- elogind is free software; you can redistribute it and/or modify it
- under the terms of the GNU Lesser General Public License as published by
- the Free Software Foundation; either version 2.1 of the License, or
- (at your option) any later version.
-
- elogind is distributed in the hope that it will be useful, but
- WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- Lesser General Public License for more details.
-
- You should have received a copy of the GNU Lesser General Public License
- along with elogind; If not, see <http://www.gnu.org/licenses/>.
--->
-
-<refentry id="sd_journal_enumerate_fields">
-
- <refentryinfo>
- <title>sd_journal_enumerate_fields</title>
- <productname>elogind</productname>
-
- <authorgroup>
- <author>
- <contrib>Developer</contrib>
- <firstname>Lennart</firstname>
- <surname>Poettering</surname>
- <email>lennart@poettering.net</email>
- </author>
- </authorgroup>
- </refentryinfo>
-
- <refmeta>
- <refentrytitle>sd_journal_enumerate_fields</refentrytitle>
- <manvolnum>3</manvolnum>
- </refmeta>
-
- <refnamediv>
- <refname>sd_journal_enumerate_fields</refname>
- <refname>sd_journal_restart_fields</refname>
- <refname>SD_JOURNAL_FOREACH_FIELD</refname>
- <refpurpose>Read used field names from the journal</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <funcsynopsis>
- <funcsynopsisinfo>#include <elogind/sd-journal.h></funcsynopsisinfo>
-
- <funcprototype>
- <funcdef>int <function>sd_journal_enumerate_fields</function></funcdef>
- <paramdef>sd_journal *<parameter>j</parameter></paramdef>
- <paramdef>const char **<parameter>field</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef>void <function>sd_journal_restart_fields</function></funcdef>
- <paramdef>sd_journal *<parameter>j</parameter></paramdef>
- </funcprototype>
-
- <funcprototype>
- <funcdef><function>SD_JOURNAL_FOREACH_FIELD</function></funcdef>
- <paramdef>sd_journal *<parameter>j</parameter></paramdef>
- <paramdef>const char *<parameter>field</parameter></paramdef>
- </funcprototype>
-
- </funcsynopsis>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Description</title>
-
- <para><function>sd_journal_enumerate_fields()</function> may be used to iterate through all field names used in the
- opened journal files. On each invocation the next field name is returned. The order of the returned field names is
- not defined. It takes two arguments: the journal context object, plus a pointer to a constant string pointer where
- the field name is stored in. The returned data is in a read-only memory map and is only valid until the next
- invocation of <function>sd_journal_enumerate_fields()</function>. Note that this call is subject to the data field
- size threshold as controlled by <function>sd_journal_set_data_threshold()</function>.</para>
-
- <para><function>sd_journal_restart_fields()</function> resets the field name enumeration index to the beginning of
- the list. The next invocation of <function>sd_journal_enumerate_fields()</function> will return the first field
- name again.</para>
-
- <para>The <function>SD_JOURNAL_FOREACH_FIELD()</function> macro may be used as a handy wrapper around
- <function>sd_journal_restart_fields()</function> and <function>sd_journal_enumerate_fields()</function>.</para>
-
- <para>These functions currently are not influenced by matches set with <function>sd_journal_add_match()</function>
- but this might change in a later version of this software.</para>
-
- <para>To retrieve the possible values a specific field can take use
- <citerefentry><refentrytitle>sd_journal_query_unique</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
- </refsect1>
-
- <refsect1>
- <title>Return Value</title>
-
- <para><function>sd_journal_enumerate_fields()</function> returns a
- positive integer if the next field name has been read, 0 when no
- more field names are known, or a negative errno-style error code.
- <function>sd_journal_restart_fields()</function> returns
- nothing.</para>
- </refsect1>
-
- <refsect1>
- <title>Notes</title>
-
- <para>The <function>sd_journal_enumerate_fields()</function> and <function>sd_journal_restart_fields()</function>
- interfaces are available as a shared library, which can be compiled and linked to with the
- <constant>libelogind</constant> <citerefentry
- project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para>
- </refsect1>
-
- <refsect1>
- <title>Examples</title>
-
- <para>Use the <function>SD_JOURNAL_FOREACH_FIELD</function> macro to iterate through all field names in use in the
- current journal.</para>
-
- <programlisting>#include <stdio.h>
-#include <string.h>
-#include <elogind/sd-journal.h>
-
-int main(int argc, char *argv[]) {
- sd_journal *j;
- const char *field;
- int r;
-
- r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY);
- if (r < 0) {
- fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
- return 1;
- }
- SD_JOURNAL_FOREACH_FIELD(j, field)
- printf("%s\n", field);
- sd_journal_close(j);
- return 0;
-}</programlisting>
-
- </refsect1>
-
- <refsect1>
- <title>See Also</title>
-
- <para>
- <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>elogind.journal-fields</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>sd-journal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>sd_journal_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>sd_journal_query_unique</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>sd_journal_get_data</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>sd_journal_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>
- </para>
- </refsect1>
-
-</refentry>
~ianmdlvl / elogind.git / commitdiff