man: add the same command sections to the man page as the --help text shows

[elogind.git] / man / loginctl.xml

diff --git a/man/loginctl.xml b/man/loginctl.xml
index f10ca030c904897fd6410aa6e34f8d51feb29d38..7a6cc156d365faeecccbf1b6d50175a9a0c9f303 100644 (file)
--- a/man/loginctl.xml
+++ b/man/loginctl.xml
@@ -21,7 +21,8 @@
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->
 
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->
 

-<refentry id="loginctl" conditional='HAVE_PAM'>
+<refentry id="loginctl" conditional='ENABLE_LOGIND'
+          xmlns:xi="http://www.w3.org/2001/XInclude">

 
         <refentryinfo>
                 <title>loginctl</title>
 
         <refentryinfo>
                 <title>loginctl</title>


@@ -49,7 +50,10 @@
 
         <refsynopsisdiv>
                 <cmdsynopsis>
 
         <refsynopsisdiv>
                 <cmdsynopsis>

-                        <command>loginctl <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="req">COMMAND</arg> <arg choice="opt" rep="repeat">NAME</arg></command>
+                        <command>loginctl</command>
+                        <arg choice="opt" rep="repeat">OPTIONS</arg>
+                        <arg choice="req">COMMAND</arg>
+                        <arg choice="opt" rep="repeat">NAME</arg>

                 </cmdsynopsis>
         </refsynopsisdiv>
 
                 </cmdsynopsis>
         </refsynopsisdiv>
 


@@ -69,18 +73,21 @@
 
                 <variablelist>
                         <varlistentry>
 
                 <variablelist>
                         <varlistentry>

-                                <term><option>-h</option></term>
-                                <term><option>--help</option></term>
+                                <term><option>--no-legend</option></term>

 
 

-                                <listitem><para>Prints a short help
-                                text and exits.</para></listitem>
+                                <listitem>
+                                        <para>Do not print the legend,
+                                        i.e. the column headers and
+                                        the footer.</para>
+                                </listitem>

                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>

-                                <term><option>--version</option></term>
+                                <term><option>--no-ask-password</option></term>

 
 

-                                <listitem><para>Prints a short version
-                                string and exits.</para></listitem>
+                                <listitem><para>Do not query the user
+                                for authentication for privileged
+                                operations.</para></listitem>

                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>


@@ -88,14 +95,14 @@
                                 <term><option>--property=</option></term>
 
                                 <listitem><para>When showing
                                 <term><option>--property=</option></term>
 
                                 <listitem><para>When showing

-                                session/user properties, limit
+                                session/user/seat properties, limit

                                 display to certain properties as
                                 specified as argument. If not
                                 display to certain properties as
                                 specified as argument. If not

-                                specified all set properties are
+                                specified, all set properties are

                                 shown. The argument should be a
                                 property name, such as
                                 <literal>Sessions</literal>. If
                                 shown. The argument should be a
                                 property name, such as
                                 <literal>Sessions</literal>. If

-                                specified more than once all
+                                specified more than once, all

                                 properties with the specified names
                                 are shown.</para></listitem>
                         </varlistentry>
                                 properties with the specified names
                                 are shown.</para></listitem>
                         </varlistentry>


@@ -105,8 +112,8 @@
                                 <term><option>--all</option></term>
 
                                 <listitem><para>When showing
                                 <term><option>--all</option></term>
 
                                 <listitem><para>When showing

-                                unit/job/manager properties, show all
-                                properties regardless whether they are
+                                session/user/seat properties, show all
+                                properties regardless of whether they are

                                 set or not.</para></listitem>
                         </varlistentry>
 
                                 set or not.</para></listitem>
                         </varlistentry>
 


@@ -114,26 +121,11 @@
                                 <term><option>-l</option></term>
                                 <term><option>--full</option></term>
 
                                 <term><option>-l</option></term>
                                 <term><option>--full</option></term>
 

-                                <listitem><para>Do not ellipsize cgroup
-                                members.</para>
+                                <listitem><para>Do not ellipsize
+                                process tree entries.</para>

                                 </listitem>
                         </varlistentry>
 
                                 </listitem>
                         </varlistentry>
 

-                        <varlistentry>
-                                <term><option>--no-pager</option></term>
-
-                                <listitem><para>Do not pipe output into a
-                                pager.</para></listitem>
-                        </varlistentry>
-
-                        <varlistentry>
-                                <term><option>--no-ask-password</option></term>
-
-                                <listitem><para>Don't query the user
-                                for authentication for privileged
-                                operations.</para></listitem>
-                        </varlistentry>
-

                         <varlistentry>
                                 <term><option>--kill-who=</option></term>
 
                         <varlistentry>
                                 <term><option>--kill-who=</option></term>
 


@@ -158,36 +150,58 @@
                                 which signal to send to selected
                                 processes. Must be one of the well
                                 known signal specifiers, such as
                                 which signal to send to selected
                                 processes. Must be one of the well
                                 known signal specifiers, such as

-                                SIGTERM, SIGINT or SIGSTOP. If omitted,
-                                defaults to
-                                <option>SIGTERM</option>.</para></listitem>
+                                <constant>SIGTERM</constant>,
+                                <constant>SIGINT</constant> or
+                                <constant>SIGSTOP</constant>. If
+                                omitted, defaults to
+                                <constant>SIGTERM</constant>.</para></listitem>

                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>

-                                <term><option>-H</option></term>
-                                <term><option>--host</option></term>
-
-                                <listitem><para>Execute operation
-                                remotely. Specify a hostname, or
-                                username and hostname separated by @,
-                                to connect to. This will use SSH to
-                                talk to the remote login manager
-                                instance.</para></listitem>
+                                <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>
                         </varlistentry>
 
                         <varlistentry>

-                                <term><option>-P</option></term>
-                                <term><option>--privileged</option></term>
+                                <term><option>-o</option></term>
+                                <term><option>--output=</option></term>

 
 

-                                <listitem><para>Acquire privileges via
-                                PolicyKit before executing the
-                                operation.</para></listitem>
-                        </varlistentry>
+                                <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" />
+
+                        <xi:include href="standard-options.xml" xpointer="help" />
+                        <xi:include href="standard-options.xml" xpointer="version" />
+                        <xi:include href="standard-options.xml" xpointer="no-pager" />

                 </variablelist>
                 </variablelist>

+        </refsect1>
+
+        <refsect1>
+                <title>Commands</title>

 
                 <para>The following commands are understood:</para>
 
 
                 <para>The following commands are understood:</para>
 

-                <variablelist>
+                <refsect2><title>Session Commands</title><variablelist>
+

                         <varlistentry>
                                 <term><command>list-sessions</command></term>
 
                         <varlistentry>
                                 <term><command>list-sessions</command></term>
 


@@ -195,31 +209,32 @@
                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>

-                                <term><command>session-status [ID...]</command></term>
+                                <term><command>session-status</command> <replaceable>ID</replaceable>...</term>

 
                                 <listitem><para>Show terse runtime
                                 status information about one or more
 
                                 <listitem><para>Show terse runtime
                                 status information about one or more

-                                sessions. This function is intended to
-                                generate human-readable output. If you
-                                are looking for computer-parsable
-                                output, use
-                                <command>show-session</command>
+                                sessions, followed by the most recent
+                                log data from the journal. This
+                                function is intended to generate
+                                human-readable output. If you are
+                                looking for computer-parsable output,
+                                use <command>show-session</command>

                                 instead.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
                                 instead.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>

-                                <term><command>show-session [ID...]</command></term>
+                                <term><command>show-session</command> <optional><replaceable>ID</replaceable>...</optional></term>

 
                                 <listitem><para>Show properties of one
                                 or more sessions or the manager
 
                                 <listitem><para>Show properties of one
                                 or more sessions or the manager

-                                itself. If no argument is specified
+                                itself. If no argument is specified,

                                 properties of the manager will be
                                 properties of the manager will be

-                                shown. If a session ID is specified
-                                properties of the session is shown. By
+                                shown. If a session ID is specified,
+                                properties of the session are shown. By

                                 default, empty properties are
                                 suppressed. Use <option>--all</option>
                                 to show those too. To select specific
                                 default, empty properties are
                                 suppressed. Use <option>--all</option>
                                 to show those too. To select specific

-                                properties to show use
+                                properties to show, use

                                 <option>--property=</option>. This
                                 command is intended to be used
                                 whenever computer-parsable output is
                                 <option>--property=</option>. This
                                 command is intended to be used
                                 whenever computer-parsable output is


@@ -231,7 +246,7 @@
                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>

-                                <term><command>activate [ID...]</command></term>
+                                <term><command>activate</command> <replaceable>ID</replaceable>...</term>

 
                                 <listitem><para>Activate one or more
                                 sessions. This brings one or more
 
                                 <listitem><para>Activate one or more
                                 sessions. This brings one or more


@@ -242,12 +257,13 @@
                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>

-                                <term><command>lock-session [ID...]</command></term>
-                                <term><command>unlock-session [ID...]</command></term>
+                                <term><command>lock-session</command> <replaceable>ID</replaceable>...</term>
+                                <term><command>unlock-session</command> <replaceable>ID</replaceable>...</term>

 
                                 <listitem><para>Activates/deactivates
                                 the screen lock on one or more
 
                                 <listitem><para>Activates/deactivates
                                 the screen lock on one or more

-                                sessions, if the session supports it.</para></listitem>
+                                sessions, if the session supports it.
+                                </para></listitem>

                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>


@@ -256,22 +272,22 @@
 
                                 <listitem><para>Activates/deactivates
                                 the screen lock on all current
 
                                 <listitem><para>Activates/deactivates
                                 the screen lock on all current

-                                sessions supporting
-                                it.</para></listitem>
+                                sessions supporting it.
+                                </para></listitem>

                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>

-                                <term><command>terminate-session [ID...]</command></term>
+                                <term><command>terminate-session</command> <replaceable>ID</replaceable>...</term>

 
 

-                                <listitem><para>Terminates a
-                                session. This kills all processes of
-                                the session and deallocates all
-                                resources attached to the
-                                session.</para></listitem>
+                                <listitem><para>Terminates a session.
+                                This kills all processes of the
+                                session and deallocates all resources
+                                attached to the session.
+                                </para></listitem>

                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>

-                                <term><command>kill-session [ID...]</command></term>
+                                <term><command>kill-session</command> <replaceable>ID</replaceable>...</term>

 
                                 <listitem><para>Send a signal to one
                                 or more processes of the session. Use
 
                                 <listitem><para>Send a signal to one
                                 or more processes of the session. Use


@@ -280,7 +296,9 @@
                                 <option>--signal=</option> to select
                                 the signal to send.</para></listitem>
                         </varlistentry>
                                 <option>--signal=</option> to select
                                 the signal to send.</para></listitem>
                         </varlistentry>

+                </variablelist></refsect2>

 
 

+                <refsect2><title>User Commands</title><variablelist>

                         <varlistentry>
                                 <term><command>list-users</command></term>
 
                         <varlistentry>
                                 <term><command>list-users</command></term>
 


@@ -289,22 +307,23 @@
                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>

-                                <term><command>user-status [USER...]</command></term>
+                                <term><command>user-status</command> <replaceable>USER</replaceable>...</term>

 
                                 <listitem><para>Show terse runtime
                                 status information about one or more
 
                                 <listitem><para>Show terse runtime
                                 status information about one or more

-                                logged in users. This function is
-                                intended to generate human-readable
-                                output. If you are looking for
-                                computer-parsable output, use
-                                <command>show-user</command>
-                                instead. Users may be specified by
-                                their usernames or numeric user
-                                IDs.</para></listitem>
+                                logged in users, followed by the most
+                                recent log data from the journal. This
+                                function is intended to generate
+                                human-readable output. If you are
+                                looking for computer-parsable output,
+                                use <command>show-user</command>
+                                instead.  Users may be specified by
+                                their usernames or numeric user IDs.
+                                </para></listitem>

                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>

-                                <term><command>show-user [USER...]</command></term>
+                                <term><command>show-user</command> <optional><replaceable>USER</replaceable>...</optional></term>

 
                                 <listitem><para>Show properties of one
                                 or more users or the manager
 
                                 <listitem><para>Show properties of one
                                 or more users or the manager


@@ -315,7 +334,7 @@
                                 default, empty properties are
                                 suppressed. Use <option>--all</option>
                                 to show those too. To select specific
                                 default, empty properties are
                                 suppressed. Use <option>--all</option>
                                 to show those too. To select specific

-                                properties to show use
+                                properties to show, use

                                 <option>--property=</option>. This
                                 command is intended to be used
                                 whenever computer-parsable output is
                                 <option>--property=</option>. This
                                 command is intended to be used
                                 whenever computer-parsable output is


@@ -327,39 +346,41 @@
                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>

-                                <term><command>enable-linger [USER...]</command></term>
-                                <term><command>disable-linger [USER...]</command></term>
+                                <term><command>enable-linger</command> <replaceable>USER</replaceable>...</term>
+                                <term><command>disable-linger</command> <replaceable>USER</replaceable>...</term>

 
                                 <listitem><para>Enable/disable user
                                 lingering for one or more users. If
                                 enabled for a specific user, a user
 
                                 <listitem><para>Enable/disable user
                                 lingering for one or more users. If
                                 enabled for a specific user, a user

-                                manager is spawned for him/her at
+                                manager is spawned for the user at

                                 boot and kept around after
                                 boot and kept around after

-                                logouts. This allows users who aren't
+                                logouts. This allows users who are not

                                 logged in to run long-running
                                 services.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
                                 logged in to run long-running
                                 services.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>

-                                <term><command>terminate-user [USER...]</command></term>
+                                <term><command>terminate-user</command> <replaceable>USER</replaceable>...</term>

 
                                 <listitem><para>Terminates all
                                 sessions of a user. This kills all
                                 processes of all sessions of the user
                                 and deallocates all runtime resources
 
                                 <listitem><para>Terminates all
                                 sessions of a user. This kills all
                                 processes of all sessions of the user
                                 and deallocates all runtime resources

-                                attached to the
-                                user.</para></listitem>
+                                attached to the user.
+                                </para></listitem>

                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>

-                                <term><command>kill-user [USER...]</command></term>
+                                <term><command>kill-user</command> <replaceable>USER</replaceable>...</term>

 
                                 <listitem><para>Send a signal to all
                                 processes of a user. Use
                                 <option>--signal=</option> to select
                                 the signal to send.</para></listitem>
                         </varlistentry>
 
                                 <listitem><para>Send a signal to all
                                 processes of a user. Use
                                 <option>--signal=</option> to select
                                 the signal to send.</para></listitem>
                         </varlistentry>

+                </variablelist></refsect2>

 
 

+                <refsect2><title>Seat Commands</title><variablelist>

                         <varlistentry>
                                 <term><command>list-seats</command></term>
 
                         <varlistentry>
                                 <term><command>list-seats</command></term>
 


@@ -369,7 +390,7 @@
                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>

-                                <term><command>seat-status [NAME...]</command></term>
+                                <term><command>seat-status</command> <replaceable>NAME</replaceable>...</term>

 
                                 <listitem><para>Show terse runtime
                                 status information about one or more
 
                                 <listitem><para>Show terse runtime
                                 status information about one or more


@@ -382,7 +403,7 @@
                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>

-                                <term><command>show-seat [NAME...]</command></term>
+                                <term><command>show-seat</command> <replaceable>NAME</replaceable>...</term>

 
                                 <listitem><para>Show properties of one
                                 or more seats or the manager
 
                                 <listitem><para>Show properties of one
                                 or more seats or the manager


@@ -405,7 +426,7 @@
                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>

-                                <term><command>attach [NAME] [DEVICE...]</command></term>
+                                <term><command>attach</command> <replaceable>NAME</replaceable> <replaceable>DEVICE</replaceable>...</term>

 
                                 <listitem><para>Persistently attach
                                 one or more devices to a seat. The
 
                                 <listitem><para>Persistently attach
                                 one or more devices to a seat. The


@@ -415,12 +436,14 @@
                                 attach at least one graphics card to a
                                 previously unused seat name. Seat
                                 names may consist only of a-z, A-Z,
                                 attach at least one graphics card to a
                                 previously unused seat name. Seat
                                 names may consist only of a-z, A-Z,

-                                0-9, "-" and "_" and must be prefixed
-                                with "seat". To drop assignment of a
-                                device to a specific seat, just
-                                reassign it to a different seat, or
-                                use
-                                <command>flush-devices</command>.</para></listitem>
+                                0-9, <literal>-</literal> and
+                                <literal>_</literal> and must be
+                                prefixed with <literal>seat</literal>.
+                                To drop assignment of a device to a
+                                specific seat, just reassign it to a
+                                different seat, or use
+                                <command>flush-devices</command>.
+                                </para></listitem>

                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>


@@ -436,40 +459,26 @@
                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>

-                                <term><command>terminate-seat [NAME...]</command></term>
+                                <term><command>terminate-seat</command> <replaceable>NAME</replaceable>...</term>

 
                                 <listitem><para>Terminates all
                                 sessions on a seat. This kills all
 
                                 <listitem><para>Terminates all
                                 sessions on a seat. This kills all

-                                processes of all sessions on a seat and
-                                deallocates all runtime resources
+                                processes of all sessions on the seat
+                                and deallocates all runtime resources

                                 attached to them.</para></listitem>
                         </varlistentry>
                                 attached to them.</para></listitem>
                         </varlistentry>

-                </variablelist>
+                </variablelist></refsect2>

 
         </refsect1>
 
         <refsect1>
                 <title>Exit status</title>
 
 
         </refsect1>
 
         <refsect1>
                 <title>Exit status</title>
 

-                <para>On success 0 is returned, a non-zero failure
+                <para>On success, 0 is returned, a non-zero failure

                 code otherwise.</para>
         </refsect1>
 
                 code otherwise.</para>
         </refsect1>
 

-        <refsect1>
-                <title>Environment</title>
-
-                <variablelist class='environment-variables'>
-                        <varlistentry>
-                                <term><varname>$SYSTEMD_PAGER</varname></term>
-                                <listitem><para>Pager to use when
-                                <option>--no-pager</option> is not given;
-                                overrides <varname>$PAGER</varname>.  Setting
-                                this to an empty string or the value
-                                <literal>cat</literal> is equivalent to passing
-                                <option>--no-pager</option>.</para></listitem>
-                        </varlistentry>
-                </variablelist>
-        </refsect1>
+        <xi:include href="less-variables.xml" />

 
         <refsect1>
                 <title>See Also</title>
 
         <refsect1>
                 <title>See Also</title>