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 b9db4759837f93d9d82f25a8cb926352f2eafcb1..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,7 +95,7 @@
                                 <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
                                 specified, all set properties are
                                 display to certain properties as
                                 specified as argument. If not
                                 specified, all set properties are


@@ -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>Do not 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>
 


@@ -166,30 +158,50 @@
                         </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 <literal>@</literal>,
-                                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>
 


@@ -197,27 +209,28 @@
                         </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
                                 itself. If no argument is specified,
                                 properties of the manager will be
                                 shown. If a session ID is specified,
 
                                 <listitem><para>Show properties of one
                                 or more sessions or the manager
                                 itself. If no argument is specified,
                                 properties of the manager will be
                                 shown. If a session ID is specified,

-                                properties of the session is shown. By
+                                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


@@ -233,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


@@ -244,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>


@@ -258,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


@@ -282,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>
 


@@ -291,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


@@ -329,13 +346,13 @@
                         </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
                                 logouts. This allows users who are not
                                 logged in to run long-running
                                 boot and kept around after
                                 logouts. This allows users who are not
                                 logged in to run long-running


@@ -343,25 +360,27 @@
                         </varlistentry>
 
                         <varlistentry>
                         </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>
 


@@ -371,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


@@ -384,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


@@ -407,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


@@ -440,15 +459,15 @@
                         </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>
 


@@ -459,21 +478,7 @@
                 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>