diff options
| author | Mark Hindley <mark@hindley.org.uk> | 2018-10-29 15:58:23 +0000 |
|---|---|---|
| committer | Mark Hindley <mark@hindley.org.uk> | 2018-10-30 16:35:33 +0000 |
| commit | a40b5201585a0fa96d1bcdfc4584b5d1ff7e2583 (patch) | |
| tree | 605dc2f4ccaf782d2e928d72bbdeb6330abf521d /man | |
| parent | 48ae8adcd5d880d056a6ec6f68a31d38db24e55d (diff) | |
| parent | 1f0d51f2fc42fcaa55d7fcd536dc722d69344454 (diff) | |
Merge remote-tracking branch 'origin/upstream/latest' into merge_v239
Diffstat (limited to 'man')
87 files changed, 4496 insertions, 2410 deletions
diff --git a/man/.gitignore b/man/.gitignore deleted file mode 100644 index 4b5f0a489..000000000 --- a/man/.gitignore +++ /dev/null @@ -1,5 +0,0 @@ -/elogind.directives.xml -/elogind.index.xml -/*.[13578] -/*.html -/custom-entities.ent diff --git a/man/Makefile b/man/Makefile deleted file mode 120000 index bd1047548..000000000 --- a/man/Makefile +++ /dev/null @@ -1 +0,0 @@ -../src/Makefile
\ No newline at end of file diff --git a/man/custom-entities.ent.in b/man/custom-entities.ent.in new file mode 100644 index 000000000..9c70fecb2 --- /dev/null +++ b/man/custom-entities.ent.in @@ -0,0 +1,12 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!-- 0 /// elogind does not has any of these but KILL_USER_PROCESSES. +# <!ENTITY MOUNT_PATH @MOUNT_PATH@> +# <!ENTITY UMOUNT_PATH @UMOUNT_PATH@> +# <!ENTITY systemgeneratordir @SYSTEM_GENERATOR_PATH@> +# <!ENTITY usergeneratordir @USER_GENERATOR_PATH@> +# <!ENTITY systemenvgeneratordir @SYSTEM_ENV_GENERATOR_PATH@> +# <!ENTITY userenvgeneratordir @USER_ENV_GENERATOR_PATH@> +# <!ENTITY CERTIFICATE_ROOT @CERTIFICATE_ROOT@> +# <!ENTITY MEMORY_ACCOUNTING_DEFAULT @MEMORY_ACCOUNTING_DEFAULT_YES_NO@> +// 0 --> +<!ENTITY KILL_USER_PROCESSES @KILL_USER_PROCESSES_YES_NO@> diff --git a/man/custom-html.xsl b/man/custom-html.xsl index f1271dcb1..ca0326cfa 100644 --- a/man/custom-html.xsl +++ b/man/custom-html.xsl @@ -1,22 +1,8 @@ <?xml version='1.0'?> <!--*-nxml-*--> <!-- - This file is part of elogind. + SPDX-License-Identifier: LGPL-2.1+ - Copyright 2011 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/>. --> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> @@ -71,6 +57,18 @@ </a> </xsl:template> +<xsl:template match="citerefentry[@project='wireguard']"> + <a> + <xsl:attribute name="href"> + <xsl:text>https://git.zx2c4.com/WireGuard/about/src/tools/</xsl:text> + <xsl:value-of select="refentrytitle"/> + <xsl:text>.</xsl:text> + <xsl:value-of select="manvolnum"/> + </xsl:attribute> + <xsl:call-template name="inline.charseq"/> + </a> +</xsl:template> + <xsl:template match="citerefentry[@project='mankier']"> <a> <xsl:attribute name="href"> diff --git a/man/custom-man.xsl b/man/custom-man.xsl index 853e214d1..5cd94834a 100644 --- a/man/custom-man.xsl +++ b/man/custom-man.xsl @@ -1,22 +1,7 @@ <?xml version='1.0'?> <!--*-nxml-*--> <!-- - This file is part of elogind. - - Copyright 2013 Zbigniew Jędrzejewski-Szmek - - 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" diff --git a/man/elogind-inhibit.xml b/man/elogind-inhibit.xml new file mode 100644 index 000000000..d095e1b05 --- /dev/null +++ b/man/elogind-inhibit.xml @@ -0,0 +1,157 @@ +<?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"> + +<!-- + SPDX-License-Identifier: LGPL-2.1+ +--> + +<refentry id="elogind-inhibit" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>elogind-inhibit</title> + <productname>elogind</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>elogind-inhibit</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>elogind-inhibit</refname> + <refpurpose>Execute a program with an inhibition lock taken</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>elogind-inhibit <arg choice="opt" rep="repeat">OPTIONS</arg> <arg>COMMAND</arg> <arg choice="opt" rep="repeat">ARGUMENTS</arg></command> + </cmdsynopsis> + <cmdsynopsis> + <command>elogind-inhibit <arg choice="opt" rep="repeat">OPTIONS</arg> --list</command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>elogind-inhibit</command> may be used to execute a + program with a shutdown, sleep, or idle inhibitor lock taken. The + lock will be acquired before the specified command line is + executed and released afterwards.</para> + + <para>Inhibitor locks may be used to block or delay system sleep + and shutdown requests from the user, as well as automatic idle + handling of the OS. This is useful to avoid system suspends while + an optical disc is being recorded, or similar operations that + should not be interrupted.</para> + + <para>For more information see the <ulink + url="https://www.freedesktop.org/wiki/Software/systemd/inhibit">Inhibitor + Lock Developer Documentation</ulink>.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <varlistentry> + <term><option>--what=</option></term> + + <listitem><para>Takes a colon-separated list of one or more + operations to inhibit: + <literal>shutdown</literal>, + <literal>sleep</literal>, + <literal>idle</literal>, + <literal>handle-power-key</literal>, + <literal>handle-suspend-key</literal>, + <literal>handle-hibernate-key</literal>, + <literal>handle-lid-switch</literal>, + for inhibiting reboot/power-off/halt/kexec, + suspending/hibernating, the automatic idle detection, or the + low-level handling of the power/sleep key and the lid switch, + respectively. If omitted, defaults to + <literal>idle:sleep:shutdown</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--who=</option></term> + + <listitem><para>Takes a short, human-readable descriptive + string for the program taking the lock. If not passed, + defaults to the command line string.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--why=</option></term> + + <listitem><para>Takes a short, human-readable descriptive + string for the reason for taking the lock. Defaults to + "Unknown reason".</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--mode=</option></term> + + <listitem><para>Takes either <literal>block</literal> or + <literal>delay</literal> and describes how the lock is + applied. If <literal>block</literal> is used (the default), + the lock prohibits any of the requested operations without + time limit, and only privileged users may override it. If + <literal>delay</literal> is used, the lock can only delay the + requested operations for a limited time. If the time elapses, + the lock is ignored and the operation executed. The time limit + may be specified in + <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + Note that <literal>delay</literal> is only available for + <literal>sleep</literal> and + <literal>shutdown</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--list</option></term> + + <listitem><para>Lists all active inhibition locks instead of + acquiring one.</para></listitem> + </varlistentry> + + <xi:include href="standard-options.xml" xpointer="no-pager" /> + <xi:include href="standard-options.xml" xpointer="no-legend" /> + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + </variablelist> + + </refsect1> + + <refsect1> + <title>Exit status</title> + + <para>Returns the exit status of the executed program.</para> + </refsect1> + + <refsect1> + <title>Example</title> + + <programlisting># elogind-inhibit wodim foobar.iso</programlisting> + + <para>This burns the ISO image + <filename>foobar.iso</filename> on a CD using + <citerefentry project='man-pages'><refentrytitle>wodim</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + and inhibits system sleeping, shutdown and idle while + doing so.</para> + </refsect1> + + <xi:include href="less-variables.xml" /> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/elogind.syntax.xml b/man/elogind.syntax.xml new file mode 100644 index 000000000..9b39b45c9 --- /dev/null +++ b/man/elogind.syntax.xml @@ -0,0 +1,98 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ +<!ENTITY % entities SYSTEM "custom-entities.ent" > +%entities; +]> + +<!-- SPDX-License-Identifier: LGPL-2.1+ --> + +<refentry id="elogind.syntax"> + + <refentryinfo> + <title>elogind.syntax</title> + <productname>elogind</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>elogind.syntax</refentrytitle> + <manvolnum>7</manvolnum> + </refmeta> + + <refnamediv> + <refname>elogind.syntax</refname> + <refpurpose>General syntax of elogind configuration files</refpurpose> + </refnamediv> + + <refsect1> + <title>Introduction</title> + + <para>This page describes the basic principles of configuration files used by + <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry> + and related programs for: + <itemizedlist> + <listitem><para>elogind unit files, see + <citerefentry><refentrytitle>elogind.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry></para></listitem> + + <listitem><para>daemon config files, see + <citerefentry><refentrytitle>elogind-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind-user.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journal-remote.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journal-upload.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind-sleep.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>timesyncd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para></listitem> + </itemizedlist> + </para> + + <para>The syntax is inspired by + <ulink url="http://standards.freedesktop.org/desktop-entry-spec/latest/">XDG Desktop Entry Specification</ulink> + <filename>.desktop</filename> files, which are in turn inspired by Microsoft Windows + <filename>.ini</filename> files. + </para> + + <para>Each file is a plain text file divided into sections, with configuration entries in the + style <replaceable>key</replaceable>=<replaceable>value</replaceable>. + Empty lines and lines starting with <literal>#</literal> or <literal>;</literal> are + ignored, which may be used for commenting.</para> + + <para>Lines ending in a backslash are concatenated with the following line while reading and the + backslash is replaced by a space character. This may be used to wrap long lines. The limit on + line length is very large (currently 1 MB), but it is recommended to avoid such long lines and + use multiple directives, variable substitution, or other mechanism as appropriate for the given + file type.</para> + + <example><programlisting>[Section A] +KeyOne=value 1 +KeyTwo=value 2 + +# a comment + +[Section B] +Setting="something" "some thing" "…" +KeyTwo=value 2 \ + value 2 continued +</programlisting></example> + + <para>Various settings are allowed to be specified more than once, in which case the + interpretation depends on the setting. Often, multiple settings form a list, and setting to an + empty value "resets", which means that previous assignments are ignored. When this is allowed, + it is mentioned in the description of the setting. Note that using multiple assignments to the + same value makes the file incompatible with parsers for the XDG <filename>.desktop</filename> + file format.</para> + </refsect1> + +</refentry> diff --git a/man/elogind.xml b/man/elogind.xml index 19dbd477e..e84bfd226 100644 --- a/man/elogind.xml +++ b/man/elogind.xml @@ -3,22 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2010 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> <refentry id="elogind" @@ -27,34 +12,75 @@ <refentryinfo> <title>elogind</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>elogind</refentrytitle> + <!-- 0 /// elogind is in section 8 + <manvolnum>1</manvolnum> + --><!-- else --> <manvolnum>8</manvolnum> + <!-- // 0 --> </refmeta> <refnamediv> + <!-- 0 /// Well, elogind isn't that much... + <refname>systemd</refname> + <refname>init</refname> + <refpurpose>systemd system and service manager</refpurpose> + --><!-- else --> <refname>elogind</refname> <refpurpose>Login manager</refpurpose> + <!-- // 0 --> </refnamediv> <refsynopsisdiv> - <para><filename>/usr/libexec/elogind/elogind</filename></para> + <!-- 0 /// elogind has a different synopsis of course... + <cmdsynopsis> + <command>/usr/lib/systemd/systemd</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + </cmdsynopsis> + <cmdsynopsis> + <command>init</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="req">COMMAND</arg> + </cmdsynopsis> + --><!-- else --> + <cmdsynopsis> + <command>elogind</command> + <arg choice="opt" rep="repeat">OPTIONS</arg> + <arg choice="req">COMMAND</arg> + </cmdsynopsis> + <!-- // 0 --> </refsynopsisdiv> <refsect1> <title>Description</title> + <!-- 0 /// elogind does not need that much explanation. + <para>systemd is a system and service manager for Linux operating + systems. When run as first process on boot (as PID 1), it acts as + init system that brings up and maintains userspace + services.</para> + + <para>For compatibility with SysV, if systemd is called as + <command>init</command> and a PID that is not 1, it will execute + <command>telinit</command> and pass all command line arguments + unmodified. That means <command>init</command> and + <command>telinit</command> are mostly equivalent when invoked from + normal login sessions. See + <citerefentry><refentrytitle>telinit</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for more information.</para> + + <para>When run as a system instance, systemd interprets the + configuration file <filename>system.conf</filename> and the files + in <filename>system.conf.d</filename> directories; when run as a + user instance, systemd interprets the configuration file + <filename>user.conf</filename> and the files in + <filename>user.conf.d</filename> directories. See + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more information.</para> + --><!-- else --> <para><command>elogind</command> is a system service that manages user logins. It is responsible for:</para> @@ -101,14 +127,1208 @@ <para>For more information on the inhibition logic see the <ulink url="http://www.freedesktop.org/wiki/Software/systemd/inhibit">Inhibitor Lock Developer Documentation</ulink>.</para> + <!-- // 0 --> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options are understood:</para> + + <variablelist> + <!-- 0 /// This list is much shorter with elogind of course. + <varlistentry> + <term><option>--test</option></term> + + <listitem><para>Determine startup sequence, dump it and exit. + This is an option useful for debugging only.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--dump-configuration-items</option></term> + + <listitem><para>Dump understood unit configuration items. This + outputs a terse but complete list of configuration items + understood in unit definition files.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--dump-bus-properties</option></term> + + <listitem><para>Dump exposed bus properties. This outputs + a terse but complete list of properties exposed to dbus. + </para></listitem> + </varlistentry> + <varlistentry> + <term><option>--unit=</option></term> + + <listitem><para>Set default unit to activate on startup. If + not specified, defaults to + <filename>default.target</filename>.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--system</option></term> + <term><option>--user</option></term> + + <listitem><para>For <option>--system</option>, tell systemd to + run a system instance, even if the process ID is not 1, i.e. + systemd is not run as init process. <option>--user</option> + does the opposite, running a user instance even if the process + ID is 1. Normally, it should not be necessary to pass these + options, as systemd automatically detects the mode it is + started in. These options are hence of little use except for + debugging. Note that it is not supported booting and + maintaining a full system with systemd running in + <option>--system</option> mode, but PID not 1. In practice, + passing <option>--system</option> explicitly is only useful in + conjunction with <option>--test</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--dump-core</option></term> + + <listitem><para>Enable core dumping on crash. This switch has + no effect when running as user instance. This setting may also + be enabled during boot on the kernel command line via the + <varname>systemd.dump_core=</varname> option, see + below.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--crash-vt=</option><replaceable>VT</replaceable></term> + + <listitem><para>Switch to a specific virtual console (VT) on + crash. Takes a positive integer in the range 1–63, or a + boolean argument. If an integer is passed, selects which VT to + switch to. If <constant>yes</constant>, the VT kernel messages + are written to is selected. If <constant>no</constant>, no VT + switch is attempted. This switch has no effect when running as + user instance. This setting may also be enabled during boot, + on the kernel command line via the + <varname>systemd.crash_vt=</varname> option, see + // 0 --> + <!-- FIXME: there is no crash_vt command line option? --> + <!-- 0 /// elogind check_tree.pl can not mangle closed comments. + below.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--crash-shell</option></term> + + <listitem><para>Run a shell on crash. This switch has no + effect when running as user instance. This setting may also be + enabled during boot, on the kernel command line via the + <varname>systemd.crash_shell=</varname> option, see + below.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--crash-reboot</option></term> + + <listitem><para>Automatically reboot the system on crash. This + switch has no effect when running as user instance. This + setting may also be enabled during boot, on the kernel command + line via the <varname>systemd.crash_reboot=</varname> option, + see below.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--confirm-spawn</option></term> + + <listitem><para>Ask for confirmation when spawning processes. + This switch has no effect when run as user + instance.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--show-status=</option></term> + + <listitem><para>Takes a boolean argument or the special value <constant>auto</constant>. If on, terse unit + status information is shown on the console during boot-up and shutdown. If off, no such status information is + shown. If set to <constant>auto</constant> behavior is similar to off, except that it is automatically switched + to on, as soon as the first unit failure or significant boot delay is encountered. This switch has no effect + when invoked as user instance. If specified, overrides both the kernel command line setting + <varname>systemd.show_status=</varname> (see below) and the configuration file option + <option>ShowStatus=</option>, see + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--log-target=</option></term> + + <listitem><para>Set log target. Argument must be one of + <option>console</option>, + <option>journal</option>, + <option>kmsg</option>, + <option>journal-or-kmsg</option>, + <option>null</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--log-level=</option></term> + + <listitem><para>Set log level. As + argument this accepts a numerical log + level or the well-known <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> + symbolic names (lowercase): + <option>emerg</option>, + <option>alert</option>, + <option>crit</option>, + <option>err</option>, + <option>warning</option>, + <option>notice</option>, + <option>info</option>, + <option>debug</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--log-color=</option></term> + + <listitem><para>Highlight important log messages. Argument is + a boolean value. If the argument is omitted, it defaults to + <option>true</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--log-location=</option></term> + + <listitem><para>Include code location in log messages. This is + mostly relevant for debugging purposes. Argument is a boolean + value. If the argument is omitted it defaults to + <option>true</option>.</para></listitem> + </varlistentry> + <varlistentry> + <term><option>--default-standard-output=</option></term> + <term><option>--default-standard-error=</option></term> + + <listitem><para>Sets the default output or error output for + all services and sockets, respectively. That is, controls the + default for <option>StandardOutput=</option> and + <option>StandardError=</option> (see + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details). Takes one of + <option>inherit</option>, + <option>null</option>, + <option>tty</option>, + <option>journal</option>, + <option>journal+console</option>, + <option>syslog</option>, + <option>syslog+console</option>, + <option>kmsg</option>, + <option>kmsg+console</option>. If the + argument is omitted + <option>--default-standard-output=</option> defaults to + <option>journal</option> and + <option>--default-standard-error=</option> to + <option>inherit</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--machine-id=</option></term> + + <listitem><para>Override the machine-id set on the hard drive, + useful for network booting or for containers. May not be set + to all zeros.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>--service-watchdogs=</option></term> + + <listitem><para>Globally enable/disable all service watchdog timeouts and emergency + actions. This setting may also be specified during boot, on the kernel + command line via the <varname>systemd.service_watchdogs=</varname> + option, see below. Defaults to enabled.</para></listitem> + </varlistentry> + + <xi:include href="standard-options.xml" xpointer="help" /> + <xi:include href="standard-options.xml" xpointer="version" /> + else --> + <varlistentry> + <term><option>-D</option></term> + <term><option>--daemon</option></term> + + <listitem><para>Daemonize elogind by double-forking + into background.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>-h</option></term> + <term><option>--help</option></term> + + <listitem><para>Show the helpt text and exit.</para></listitem> + </varlistentry> + <!-- // 0 --> + </variablelist> + </refsect1> + + <!-- 0 /// The whole concpets section is unneeded in elogind + <refsect1> + <title>Concepts</title> + + <para>systemd provides a dependency system between various + entities called "units" of 11 different types. Units encapsulate + various objects that are relevant for system boot-up and + maintenance. The majority of units are configured in unit + configuration files, whose syntax and basic set of options is + described in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + however some are created automatically from other configuration, + dynamically from system state or programmatically at runtime. + Units may be "active" (meaning started, bound, plugged in, …, + depending on the unit type, see below), or "inactive" (meaning + stopped, unbound, unplugged, …), as well as in the process of + being activated or deactivated, i.e. between the two states (these + states are called "activating", "deactivating"). A special + "failed" state is available as well, which is very similar to + "inactive" and is entered when the service failed in some way + (process returned error code on exit, or crashed, an operation + timed out, or after too many restarts). If this state is entered, + the cause will be logged, for later reference. Note that the + various unit types may have a number of additional substates, + which are mapped to the five generalized unit states described + here.</para> + + <para>The following unit types are available:</para> + + <orderedlist> + <listitem><para>Service units, which start and control daemons + and the processes they consist of. For details, see + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Socket units, which encapsulate local IPC or + network sockets in the system, useful for socket-based + activation. For details about socket units, see + <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + for details on socket-based activation and other forms of + activation, see + <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Target units are useful to group units, or + provide well-known synchronization points during boot-up, see + <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Device units expose kernel devices in systemd + and may be used to implement device-based activation. For + details, see + <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Mount units control mount points in the file + system, for details see + <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Automount units provide automount capabilities, + for on-demand mounting of file systems as well as parallelized + boot-up. See + <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Timer units are useful for triggering activation + of other units based on timers. You may find details in + <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Swap units are very similar to mount units and + encapsulate memory swap partitions or files of the operating + system. They are described in + <citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Path units may be used to activate other + services when file system objects change or are modified. See + <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Slice units may be used to group units which + manage system processes (such as service and scope units) in a + hierarchical tree for resource management purposes. See + <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + <listitem><para>Scope units are similar to service units, but + manage foreign processes instead of starting them as well. See + <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> + + </orderedlist> + + <para>Units are named as their configuration files. Some units + have special semantics. A detailed list is available in + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + + <para>systemd knows various kinds of dependencies, including + positive and negative requirement dependencies (i.e. + <varname>Requires=</varname> and <varname>Conflicts=</varname>) as + well as ordering dependencies (<varname>After=</varname> and + <varname>Before=</varname>). NB: ordering and requirement + dependencies are orthogonal. If only a requirement dependency + exists between two units (e.g. <filename>foo.service</filename> + requires <filename>bar.service</filename>), but no ordering + dependency (e.g. <filename>foo.service</filename> after + <filename>bar.service</filename>) and both are requested to start, + they will be started in parallel. It is a common pattern that both + requirement and ordering dependencies are placed between two + units. Also note that the majority of dependencies are implicitly + created and maintained by systemd. In most cases, it should be + unnecessary to declare additional dependencies manually, however + it is possible to do this.</para> + + <para>Application programs and units (via dependencies) may + request state changes of units. In systemd, these requests are + encapsulated as 'jobs' and maintained in a job queue. Jobs may + succeed or can fail, their execution is ordered based on the + ordering dependencies of the units they have been scheduled + for.</para> + + <para>On boot systemd activates the target unit + <filename>default.target</filename> whose job is to activate + on-boot services and other on-boot units by pulling them in via + dependencies. Usually, the unit name is just an alias (symlink) for + either <filename>graphical.target</filename> (for fully-featured + boots into the UI) or <filename>multi-user.target</filename> (for + limited console-only boots for use in embedded or server + environments, or similar; a subset of graphical.target). However, + it is at the discretion of the administrator to configure it as an + alias to any other target unit. See + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details about these target units.</para> + + <para>Processes systemd spawns are placed in individual Linux + control groups named after the unit which they belong to in the + private systemd hierarchy. (see <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v1/cgroups.txt">cgroups.txt</ulink> + for more information about control groups, or short "cgroups"). + systemd uses this to effectively keep track of processes. Control + group information is maintained in the kernel, and is accessible + via the file system hierarchy (beneath + <filename>/sys/fs/cgroup/systemd/</filename>), or in tools such as + <citerefentry project='man-pages'><refentrytitle>systemd-cgls</refentrytitle><manvolnum>1</manvolnum></citerefentry> + or + <citerefentry project='man-pages'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry> + (<command>ps xawf -eo pid,user,cgroup,args</command> is + particularly useful to list all processes and the systemd units + they belong to.).</para> + + <para>systemd is compatible with the SysV init system to a large + degree: SysV init scripts are supported and simply read as an + alternative (though limited) configuration file format. The SysV + <filename>/dev/initctl</filename> interface is provided, and + compatibility implementations of the various SysV client tools are + available. In addition to that, various established Unix + functionality such as <filename>/etc/fstab</filename> or the + <filename>utmp</filename> database are supported.</para> + + <para>systemd has a minimal transaction system: if a unit is + requested to start up or shut down it will add it and all its + dependencies to a temporary transaction. Then, it will verify if + the transaction is consistent (i.e. whether the ordering of all + units is cycle-free). If it is not, systemd will try to fix it up, + and removes non-essential jobs from the transaction that might + remove the loop. Also, systemd tries to suppress non-essential + jobs in the transaction that would stop a running service. Finally + it is checked whether the jobs of the transaction contradict jobs + that have already been queued, and optionally the transaction is + aborted then. If all worked out and the transaction is consistent + and minimized in its impact it is merged with all already + outstanding jobs and added to the run queue. Effectively this + means that before executing a requested operation, systemd will + verify that it makes sense, fixing it if possible, and only + failing if it really cannot work.</para> + + <para>systemd contains native implementations of various tasks + that need to be executed as part of the boot process. For example, + it sets the hostname or configures the loopback network device. It + also sets up and mounts various API file systems, such as + <filename>/sys</filename> or <filename>/proc</filename>.</para> + + <para>For more information about the concepts and + ideas behind systemd, please refer to the + <ulink url="http://0pointer.de/blog/projects/systemd.html">Original Design Document</ulink>.</para> + + <para>Note that some but not all interfaces provided + by systemd are covered by the + <ulink url="https://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise">Interface + Stability Promise</ulink>.</para> + + <para>Units may be generated dynamically at boot and system + manager reload time, for example based on other configuration + files or parameters passed on the kernel command line. For details, see + <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + + <para>Systems which invoke systemd in a container or initrd + environment should implement the + <ulink url="https://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container Interface</ulink> or + <ulink url="https://www.freedesktop.org/wiki/Software/systemd/InitrdInterface">initrd Interface</ulink> + specifications, respectively.</para> + </refsect1> + // 0 --> + + <!-- 0 /// The whole directories section is unneeded in elogind + <refsect1> + <title>Directories</title> + + <variablelist> + <varlistentry> + <term>System unit directories</term> + + <listitem><para>The systemd system manager reads unit + configuration from various directories. Packages that want to + install unit files shall place them in the directory returned + by <command>pkg-config systemd + --variable=systemdsystemunitdir</command>. Other directories + checked are <filename>/usr/local/lib/systemd/system</filename> + and <filename>/usr/lib/systemd/system</filename>. User + configuration always takes precedence. <command>pkg-config + systemd --variable=systemdsystemconfdir</command> returns the + path of the system configuration directory. Packages should + alter the content of these directories only with the + <command>enable</command> and <command>disable</command> + commands of the + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + tool. Full list of directories is provided in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> + </variablelist> + + <variablelist> + <varlistentry> + <term>User unit directories</term> + + <listitem><para>Similar rules apply for the user unit + directories. However, here the + <ulink url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG + Base Directory specification</ulink> is followed to find + units. Applications should place their unit files in the + directory returned by <command>pkg-config systemd + --variable=systemduserunitdir</command>. Global configuration + is done in the directory reported by <command>pkg-config + systemd --variable=systemduserconfdir</command>. The + <command>enable</command> and <command>disable</command> + commands of the + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + tool can handle both global (i.e. for all users) and private + (for one user) enabling/disabling of units. Full list of + directories is provided in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> + </variablelist> + + <variablelist> + <varlistentry> + <term>SysV init scripts directory</term> + + <listitem><para>The location of the SysV init script directory + varies between distributions. If systemd cannot find a native + unit file for a requested service, it will look for a SysV + init script of the same name (with the + <filename>.service</filename> suffix + removed).</para></listitem> + </varlistentry> + </variablelist> + + <variablelist> + <varlistentry> + <term>SysV runlevel link farm directory</term> + + <listitem><para>The location of the SysV runlevel link farm + directory varies between distributions. systemd will take the + link farm into account when figuring out whether a service + shall be enabled. Note that a service unit with a native unit + configuration file cannot be started by activating it in the + SysV runlevel link farm.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + // 0 --> + + <!-- 0 /// The whole Signals section is unneeded in elogind + <refsect1> + <title>Signals</title> + + <variablelist> + <varlistentry> + <term><constant>SIGTERM</constant></term> + + <listitem><para>Upon receiving this signal the systemd system + manager serializes its state, reexecutes itself and + deserializes the saved state again. This is mostly equivalent + to <command>systemctl daemon-reexec</command>.</para> + + <para>systemd user managers will start the + <filename>exit.target</filename> unit when this signal is + received. This is mostly equivalent to <command>systemctl + --user start exit.target + --job-mode=replace-irreversible</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGINT</constant></term> + + <listitem><para>Upon receiving this signal the systemd system + manager will start the + <filename>ctrl-alt-del.target</filename> unit. This is mostly + equivalent to <command>systemctl start ctrl-alt-del.target + --job-mode=replace-irreversible</command>. If this signal is + received more than 7 times per 2s, an immediate reboot is + triggered. Note that pressing Ctrl-Alt-Del on the console + will trigger this signal. Hence, if a reboot is hanging, + pressing Ctrl-Alt-Del more than 7 times in 2s is a relatively + safe way to trigger an immediate reboot.</para> + + <para>systemd user managers treat this signal the same way as + <constant>SIGTERM</constant>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGWINCH</constant></term> + + <listitem><para>When this signal is received the systemd + system manager will start the + <filename>kbrequest.target</filename> unit. This is mostly + equivalent to <command>systemctl start + kbrequest.target</command>.</para> + + <para>This signal is ignored by systemd user + managers.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGPWR</constant></term> + + <listitem><para>When this signal is received the systemd + manager will start the <filename>sigpwr.target</filename> + unit. This is mostly equivalent to <command>systemctl start + sigpwr.target</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGUSR1</constant></term> + + <listitem><para>When this signal is received the systemd + manager will try to reconnect to the D-Bus + bus.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGUSR2</constant></term> + + <listitem><para>When this signal is received the systemd + manager will log its complete state in human-readable form. + The data logged is the same as printed by + <command>systemd-analyze dump</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGHUP</constant></term> + + <listitem><para>Reloads the complete daemon configuration. + This is mostly equivalent to <command>systemctl + daemon-reload</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+0</constant></term> + + <listitem><para>Enters default mode, starts the + <filename>default.target</filename> unit. This is mostly + equivalent to <command>systemctl isolate + default.target</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+1</constant></term> + + <listitem><para>Enters rescue mode, starts the + <filename>rescue.target</filename> unit. This is mostly + equivalent to <command>systemctl isolate + rescue.target</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+2</constant></term> + + <listitem><para>Enters emergency mode, starts the + <filename>emergency.service</filename> unit. This is mostly + equivalent to <command>systemctl isolate + emergency.service</command>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+3</constant></term> + + <listitem><para>Halts the machine, starts the + <filename>halt.target</filename> unit. This is mostly + equivalent to <command>systemctl start halt.target + --job-mode=replace-irreversible</command>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+4</constant></term> + + <listitem><para>Powers off the machine, starts the + <filename>poweroff.target</filename> unit. This is mostly + equivalent to <command>systemctl start poweroff.target + --job-mode=replace-irreversible</command>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+5</constant></term> + + <listitem><para>Reboots the machine, starts the + <filename>reboot.target</filename> unit. This is mostly + equivalent to <command>systemctl start reboot.target + --job-mode=replace-irreversible</command>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+6</constant></term> + + <listitem><para>Reboots the machine via kexec, starts the + <filename>kexec.target</filename> unit. This is mostly + equivalent to <command>systemctl start kexec.target + --job-mode=replace-irreversible</command>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+13</constant></term> + + <listitem><para>Immediately halts the machine.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+14</constant></term> + + <listitem><para>Immediately powers off the machine.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+15</constant></term> + + <listitem><para>Immediately reboots the machine.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+16</constant></term> + + <listitem><para>Immediately reboots the machine with kexec.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+20</constant></term> + + <listitem><para>Enables display of status messages on the + console, as controlled via + <varname>systemd.show_status=1</varname> on the kernel command + line.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+21</constant></term> + + <listitem><para>Disables display of + status messages on the console, as + controlled via + <varname>systemd.show_status=0</varname> + on the kernel command + line.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+22</constant></term> + + <listitem><para>Sets the service manager's log level to <literal>debug</literal>, in a fashion equivalent to + <varname>systemd.log_level=debug</varname> on the kernel command line.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+23</constant></term> + + <listitem><para>Restores the log level to its configured value. The configured value is derived from – in order + of priority – the value specified with <varname>systemd.log-level=</varname> on the kernel command line, or the + value specified with <option>LogLevel=</option> in the configuration file, or the built-in default of + <literal>info</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+24</constant></term> + + <listitem><para>Immediately exits the manager (only available + for --user instances).</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+26</constant></term> + + <listitem><para>Restores the log target to its configured value. The configured value is derived from – in + order of priority – the value specified with <varname>systemd.log-target=</varname> on the kernel command line, + or the value specified with <option>LogTarget=</option> in the configuration file, or the built-in + default.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>SIGRTMIN+27</constant></term> + <term><constant>SIGRTMIN+28</constant></term> + + <listitem><para>Sets the log target to <literal>console</literal> on <constant>SIGRTMIN+27</constant> (or + <literal>kmsg</literal> on <constant>SIGRTMIN+28</constant>), in a fashion equivalent to + <varname>systemd.log_target=console</varname> (or <varname>systemd.log_target=kmsg</varname> on + <constant>SIGRTMIN+28</constant>) on the kernel command line.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + // 0 --> + + <!-- 0 /// The whole environment section is unneeded in elogind + <refsect1> + <title>Environment</title> + + <variablelist class='environment-variables'> + <varlistentry> + <term><varname>$SYSTEMD_LOG_LEVEL</varname></term> + <listitem><para>systemd reads the log level from this + environment variable. This can be overridden with + <option>--log-level=</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$SYSTEMD_LOG_TARGET</varname></term> + <listitem><para>systemd reads the log target from this + environment variable. This can be overridden with + <option>--log-target=</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$SYSTEMD_LOG_COLOR</varname></term> + <listitem><para>Controls whether systemd highlights important + log messages. This can be overridden with + <option>--log-color=</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$SYSTEMD_LOG_LOCATION</varname></term> + <listitem><para>Controls whether systemd prints the code + location along with log messages. This can be overridden with + <option>--log-location=</option>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$XDG_CONFIG_HOME</varname></term> + <term><varname>$XDG_CONFIG_DIRS</varname></term> + <term><varname>$XDG_DATA_HOME</varname></term> + <term><varname>$XDG_DATA_DIRS</varname></term> + + <listitem><para>The systemd user manager uses these variables + in accordance to the <ulink + url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG + Base Directory specification</ulink> to find its + configuration.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$SYSTEMD_UNIT_PATH</varname></term> + + <listitem><para>Controls where systemd looks for unit + files.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$SYSTEMD_SYSVINIT_PATH</varname></term> + + <listitem><para>Controls where systemd looks for SysV init + scripts.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$SYSTEMD_SYSVRCND_PATH</varname></term> + + <listitem><para>Controls where systemd looks for SysV init + script runlevel link farms.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$SYSTEMD_COLORS</varname></term> + + <listitem><para>The value must be a boolean. Controls whether colorized output should be + generated. This can be specified to override the decision that <command>systemd</command> + makes based on <varname>$TERM</varname> and what the console is connected to.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>$SYSTEMD_URLIFY</varname></term> + + <listitem><para>The value must be a boolean. Controls whether clickable links should be generated in the output + for terminal emulators supporting this. This can be specified to override the decision that + <command>systemd</command> makes based on <varname>$TERM</varname> and other conditions.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>$LISTEN_PID</varname></term> + <term><varname>$LISTEN_FDS</varname></term> + <term><varname>$LISTEN_FDNAMES</varname></term> + + <listitem><para>Set by systemd for supervised processes during + socket-based activation. See + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for more information.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$NOTIFY_SOCKET</varname></term> + + <listitem><para>Set by systemd for supervised processes for + status and start-up completion notification. See + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for more information.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + // 0 --> + + <!-- 0 /// The whole kernel section is unneeded in elogind + <refsect1> + <title>Kernel Command Line</title> + + <para>When run as system instance systemd parses a number of + kernel command line arguments<footnote><para>If run inside a Linux + container these arguments may be passed as command line arguments + to systemd itself, next to any of the command line options listed + in the Options section above. If run outside of Linux containers, + these arguments are parsed from <filename>/proc/cmdline</filename> + instead.</para></footnote>:</para> + + <variablelist class='kernel-commandline-options'> + <varlistentry> + <term><varname>systemd.unit=</varname></term> + <term><varname>rd.systemd.unit=</varname></term> + + <listitem><para>Overrides the unit to activate on boot. + Defaults to <filename>default.target</filename>. This may be + used to temporarily boot into a different boot unit, for + example <filename>rescue.target</filename> or + <filename>emergency.service</filename>. See + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> + for details about these units. The option prefixed with + <literal>rd.</literal> is honored only in the initial RAM disk + (initrd), while the one that is not prefixed only in the main + system.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.dump_core</varname></term> + + <listitem><para>Takes a boolean argument or enables the option if specified + without an argument. If enabled, the systemd manager (PID 1) dumps core when + it crashes. Otherwise, no core dump is created. Defaults to enabled.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.crash_chvt</varname></term> + + <listitem><para>Takes a positive integer, or a boolean argument. Can be also + specified without an argument, with the same effect as a positive boolean. If + a positive integer (in the range 1–63) is specified, the system manager (PID + 1) will activate the specified virtual terminal (VT) when it + crashes. Defaults to disabled, meaning that no such switch is attempted. If + set to enabled, the VT the kernel messages are written to is selected. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.crash_shell</varname></term> + + <listitem><para>Takes a boolean argument or enables the option if specified + without an argument. If enabled, the system manager (PID 1) spawns a shell + when it crashes, after a 10s delay. Otherwise, no shell is spawned. Defaults + to disabled, for security reasons, as the shell is not protected by password + authentication.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.crash_reboot</varname></term> + + <listitem><para>Takes a boolean argument or enables the option if specified + without an argument. If enabled, the system manager (PID 1) will reboot the + machine automatically when it crashes, after a 10s delay. Otherwise, the + system will hang indefinitely. Defaults to disabled, in order to avoid a + reboot loop. If combined with <varname>systemd.crash_shell</varname>, the + system is rebooted after the shell exits.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.confirm_spawn</varname></term> + + <listitem><para>Takes a boolean argument or a path to the virtual console + where the confirmation messages should be emitted. Can be also specified + without an argument, with the same effect as a positive boolean. If enabled, + the system manager (PID 1) asks for confirmation when spawning processes + using <option>/dev/console</option>. If a path or a console name (such as + <literal>ttyS0</literal>) is provided, the virtual console pointed to by this + path or described by the give name will be used instead. Defaults to disabled. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.service_watchdogs=</varname></term> + + <listitem><para>Takes a boolean argument. If disabled, all service runtime + watchdogs (<option>WatchdogSec=</option>) and emergency actions (e.g. + <option>OnFailure=</option> or <option>StartLimitAction=</option>) are + ignored by the system manager (PID 1); see + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + Defaults to enabled, i.e. watchdogs and failure actions are processed + normally. The hardware watchdog is not affected by this + option.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.show_status</varname></term> + + <listitem><para>Takes a boolean argument or the constant + <constant>auto</constant>. Can be also specified without an argument, with + the same effect as a positive boolean. If enabled, the systemd manager (PID + 1) shows terse service status updates on the console during bootup. + <constant>auto</constant> behaves like <option>false</option> until a unit + fails or there is a significant delay in boot. Defaults to enabled, unless + <option>quiet</option> is passed as kernel command line option, in which case + it defaults to <constant>auto</constant>. If specified overrides the system + manager configuration file option <option>ShowStatus=</option>, see + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + However, the process command line option <option>--show-status=</option> + takes precedence over both this kernel command line option and the + configuration file option.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.log_target=</varname></term> + <term><varname>systemd.log_level=</varname></term> + <term><varname>systemd.log_location=</varname></term> + <term><varname>systemd.log_color</varname></term> + + <listitem><para>Controls log output, with the same effect as the + <varname>$SYSTEMD_LOG_TARGET</varname>, + <varname>$SYSTEMD_LOG_LEVEL</varname>, + <varname>$SYSTEMD_LOG_LOCATION</varname>, + <varname>$SYSTEMD_LOG_COLOR</varname> environment variables described above. + <varname>systemd.log_color</varname> can be specified without an argument, + with the same effect as a positive boolean.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.default_standard_output=</varname></term> + <term><varname>systemd.default_standard_error=</varname></term> + <listitem><para>Controls default standard output and error + output for services, with the same effect as the + <option>--default-standard-output=</option> and + <option>--default-standard-error=</option> command line + arguments described above, respectively.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.setenv=</varname></term> + + <listitem><para>Takes a string argument in the form + VARIABLE=VALUE. May be used to set default environment + variables to add to forked child processes. May be used more + than once to set multiple variables.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.machine_id=</varname></term> + + <listitem><para>Takes a 32 character hex value to be + used for setting the machine-id. Intended mostly for + network booting where the same machine-id is desired + for every boot.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.unified_cgroup_hierarchy</varname></term> + + <listitem><para>When specified without an argument or with a true argument, + enables the usage of + <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v2.txt">unified cgroup hierarchy</ulink> + (a.k.a. cgroups-v2). When specified with a false argument, fall back to + hybrid or full legacy cgroup hierarchy.</para> + + <para>If this option is not specified, the default behaviour is determined + during compilation (the <option>--with-default-hierarchy=</option> + option). If the kernel does not support unified cgroup hierarchy, the legacy + hierarchy will be used even if this option is specified.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>systemd.legacy_systemd_cgroup_controller</varname></term> + + <listitem><para>Takes effect if the full unified cgroup hierarchy is not used + (see previous option). When specified without an argument or with a true + argument, disables the use of "hybrid" cgroup hierarchy (i.e. a cgroups-v2 + tree used for systemd, and + <ulink url="https://www.kernel.org/doc/Documentation/cgroup-v1/">legacy + cgroup hierarchy</ulink>, a.k.a. cgroups-v1, for other controllers), and + forces a full "legacy" mode. When specified with a false argument, enables + the use of "hybrid" hierarchy.</para> + + <para>If this option is not specified, the default behaviour is determined + during compilation (the <option>--with-default-hierarchy=</option> + option). If the kernel does not support unified cgroup hierarchy, the legacy + hierarchy will be used even if this option is specified.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>quiet</varname></term> + + <listitem><para>Turn off status output at boot, much like + <varname>systemd.show_status=false</varname> would. Note that + this option is also read by the kernel itself and disables + kernel log output. Passing this option hence turns off the + usual output from both the system manager and the kernel. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>debug</varname></term> + + <listitem><para>Turn on debugging output. This is equivalent + to <varname>systemd.log_level=debug</varname>. Note that this + option is also read by the kernel itself and enables kernel + debug output. Passing this option hence turns on the debug + output from both the system manager and the + kernel.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>emergency</varname></term> + <term><varname>rd.emergency</varname></term> + <term><varname>-b</varname></term> + + <listitem><para>Boot into emergency mode. This is equivalent + to <varname>systemd.unit=emergency.target</varname> or + <varname>rd.systemd.unit=emergency.target</varname>, respectively, and + provided for compatibility reasons and to be easier to type.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>rescue</varname></term> + <term><varname>rd.rescue</varname></term> + <term><varname>single</varname></term> + <term><varname>s</varname></term> + <term><varname>S</varname></term> + <term><varname>1</varname></term> + + <listitem><para>Boot into rescue mode. This is equivalent to + <varname>systemd.unit=rescue.target</varname> or + <varname>rd.systemd.unit=rescue.target</varname>, respectively, and + provided for compatibility reasons and to be easier to type.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>2</varname></term> + <term><varname>3</varname></term> + <term><varname>4</varname></term> + <term><varname>5</varname></term> + + <listitem><para>Boot into the specified legacy SysV runlevel. + These are equivalent to + <varname>systemd.unit=runlevel2.target</varname>, + <varname>systemd.unit=runlevel3.target</varname>, + <varname>systemd.unit=runlevel4.target</varname>, and + <varname>systemd.unit=runlevel5.target</varname>, + respectively, and provided for compatibility reasons and to be + easier to type.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>locale.LANG=</varname></term> + <term><varname>locale.LANGUAGE=</varname></term> + <term><varname>locale.LC_CTYPE=</varname></term> + <term><varname>locale.LC_NUMERIC=</varname></term> + <term><varname>locale.LC_TIME=</varname></term> + <term><varname>locale.LC_COLLATE=</varname></term> + <term><varname>locale.LC_MONETARY=</varname></term> + <term><varname>locale.LC_MESSAGES=</varname></term> + <term><varname>locale.LC_PAPER=</varname></term> + <term><varname>locale.LC_NAME=</varname></term> + <term><varname>locale.LC_ADDRESS=</varname></term> + <term><varname>locale.LC_TELEPHONE=</varname></term> + <term><varname>locale.LC_MEASUREMENT=</varname></term> + <term><varname>locale.LC_IDENTIFICATION=</varname></term> + + <listitem><para>Set the system locale to use. This overrides + the settings in <filename>/etc/locale.conf</filename>. For + more information, see + <citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry project='man-pages'><refentrytitle>locale</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> + </variablelist> + + <para>For other kernel command line parameters understood by + components of the core OS, please refer to + <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> + </refsect1> + // 0 --> + + <!-- 0 /// The whole sockets section is unneeded in elogind + <refsect1> + <title>Sockets and FIFOs</title> + + <variablelist> + <varlistentry> + <term><filename>/run/systemd/notify</filename></term> + + <listitem><para>Daemon status notification socket. This is an + <constant>AF_UNIX</constant> datagram socket and is used to + implement the daemon notification logic as implemented by + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem> + + </varlistentry> + + <varlistentry> + <term><filename>/run/systemd/private</filename></term> + + <listitem><para>Used internally as communication channel + between + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + and the systemd process. This is an + <constant>AF_UNIX</constant> stream socket. This interface is + private to systemd and should not be used in external + projects.</para></listitem> + </varlistentry> + + <varlistentry> + <term><filename>/dev/initctl</filename></term> + + <listitem><para>Limited compatibility support for the SysV + client interface, as implemented by the + <filename>systemd-initctl.service</filename> unit. This is a + named pipe in the file system. This interface is obsolete and + should not be used in new applications.</para></listitem> + </varlistentry> + </variablelist> </refsect1> + // 0 --> <refsect1> <title>See Also</title> <para> + <!-- 0 /// elogind does not have that much to see also... + The <ulink url="https://www.freedesktop.org/wiki/Software/systemd/">systemd Homepage</ulink>, + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-notify</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> + else --> + The <ulink url="https://github.com/elogind/elogind/">elogind Homepage</ulink>, <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>pam_elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry> + <!-- // 0 --> </para> </refsect1> diff --git a/man/glib-event-glue.c b/man/glib-event-glue.c index 8f3168d0e..15e2bdb6a 100644 --- a/man/glib-event-glue.c +++ b/man/glib-event-glue.c @@ -1,68 +1,50 @@ -/*** - Copyright 2014 Tom Gundersen - - Permission is hereby granted, free of charge, to any person - obtaining a copy of this software and associated documentation files - (the "Software"), to deal in the Software without restriction, - including without limitation the rights to use, copy, modify, merge, - publish, distribute, sublicense, and/or sell copies of the Software, - and to permit persons to whom the Software is furnished to do so, - subject to the following conditions: - - The above copyright notice and this permission notice shall be - included in all copies or substantial portions of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, - EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF - MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND - NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS - BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN - ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN - CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - SOFTWARE. -***/ +/* SPDX-License-Identifier: MIT */ #include <stdlib.h> +//#include <elogind/sd-event.h> +//#include <glib.h> +#include <glib.h> +#include <systemd/sd-event.h> typedef struct SDEventSource { - GSource source; - GPollFD pollfd; - sd_event *event; + GSource source; + GPollFD pollfd; + sd_event *event; } SDEventSource; static gboolean event_prepare(GSource *source, gint *timeout_) { - return sd_event_prepare(((SDEventSource *)source)->event) > 0; + return sd_event_prepare(((SDEventSource *)source)->event) > 0; } static gboolean event_check(GSource *source) { - return sd_event_wait(((SDEventSource *)source)->event, 0) > 0; + return sd_event_wait(((SDEventSource *)source)->event, 0) > 0; } static gboolean event_dispatch(GSource *source, GSourceFunc callback, gpointer user_data) { - return sd_event_dispatch(((SDEventSource *)source)->event) > 0; + return sd_event_dispatch(((SDEventSource *)source)->event) > 0; } static void event_finalize(GSource *source) { - sd_event_unref(((SDEventSource *)source)->event); + sd_event_unref(((SDEventSource *)source)->event); } static GSourceFuncs event_funcs = { - .prepare = event_prepare, - .check = event_check, - .dispatch = event_dispatch, - .finalize = event_finalize, + .prepare = event_prepare, + .check = event_check, + .dispatch = event_dispatch, + .finalize = event_finalize, }; GSource *g_sd_event_create_source(sd_event *event) { - SDEventSource *source; + SDEventSource *source; - source = (SDEventSource *)g_source_new(&event_funcs, sizeof(SDEventSource)); + source = (SDEventSource *)g_source_new(&event_funcs, sizeof(SDEventSource)); - source->event = sd_event_ref(event); - source->pollfd.fd = sd_event_get_fd(event); - source->pollfd.events = G_IO_IN | G_IO_HUP | G_IO_ERR; + source->event = sd_event_ref(event); + source->pollfd.fd = sd_event_get_fd(event); + source->pollfd.events = G_IO_IN | G_IO_HUP | G_IO_ERR; - g_source_add_poll((GSource *)source, &source->pollfd); + g_source_add_poll((GSource *)source, &source->pollfd); - return (GSource *)source; + return (GSource *)source; } diff --git a/man/less-variables.xml b/man/less-variables.xml index 396481c93..a3faa3899 100644 --- a/man/less-variables.xml +++ b/man/less-variables.xml @@ -2,6 +2,10 @@ <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<!-- + SPDX-License-Identifier: LGPL-2.1+ +--> + <refsect1> <title>Environment</title> diff --git a/man/libelogind-pkgconfig.xml b/man/libelogind-pkgconfig.xml index c940b15b3..5c83e11f8 100644 --- a/man/libelogind-pkgconfig.xml +++ b/man/libelogind-pkgconfig.xml @@ -2,6 +2,10 @@ <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<!-- + SPDX-License-Identifier: LGPL-2.1+ +--> + <refsect1> <title>Notes</title> diff --git a/man/loginctl.xml b/man/loginctl.xml index 39534f115..e96f0e999 100644 --- a/man/loginctl.xml +++ b/man/loginctl.xml @@ -3,39 +3,19 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2010 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> -<refentry id="loginctl" +<!-- 0 /// elogind does not need to activate loginctl in configure +<refentry id="loginctl" conditional='ENABLE_LOGIND' xmlns:xi="http://www.w3.org/2001/XInclude"> +else --> +<refentry id="loginctl" xmlns:xi="http://www.w3.org/2001/XInclude"> +<!-- // 0 --> <refentryinfo> <title>loginctl</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -62,8 +42,14 @@ <para><command>loginctl</command> may be used to introspect and control the state of the + <!-- 0 /// elogind has no services and is in section 8 + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + login manager + <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + --><!-- else --> <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry> login manager</para> + <!-- // 0 --> </refsect1> <refsect1> @@ -95,11 +81,9 @@ <varlistentry> <term><option>--value</option></term> - <listitem> - <para>When printing properties with <command>show</command>, - only print the value, and skip the property name and - <literal>=</literal>.</para> - </listitem> + <listitem><para>When showing session/user/seat properties, + only print the value, and skip the property name and + <literal>=</literal>.</para></listitem> </varlistentry> <varlistentry> @@ -143,6 +127,31 @@ <constant>SIGTERM</constant>.</para></listitem> </varlistentry> + <!-- 0 /// elogind does not support systemd-journal + <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> + // 0 --> + <xi:include href="user-system-options.xml" xpointer="host" /> <xi:include href="user-system-options.xml" xpointer="machine" /> @@ -256,11 +265,10 @@ one or more logged in users, followed by the most recent log data from the journal. 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 - computer-parsable output, use <command>show-user</command> - instead. Users may be specified by their usernames or numeric - user IDs. </para></listitem> + is shown for the user of the session of the caller. This + function is intended to generate human-readable output. If you + are looking for computer-parsable output, use + <command>show-user</command> instead.</para></listitem> </varlistentry> <varlistentry> @@ -278,6 +286,7 @@ formatted human-readable output.</para></listitem> </varlistentry> + <!-- 0 /// elogind does not spawn a user manager. Mask until lingeringin elogind is clarified. <varlistentry> <term><command>enable-linger</command> <optional><replaceable>USER</replaceable>…</optional></term> <term><command>disable-linger</command> <optional><replaceable>USER</replaceable>…</optional></term> @@ -294,6 +303,7 @@ <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. </para></listitem> </varlistentry> + // 0 --> <varlistentry> <term><command>terminate-user</command> <replaceable>USER</replaceable>…</term> @@ -380,61 +390,64 @@ </varlistentry> </variablelist></refsect2> + <!-- 1 /// elogind additionally supports a few systemctl commands. --> <refsect2><title>System Commands</title><variablelist> + <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> </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> + <!-- // 1 --> </refsect1> + <refsect1> <title>Exit status</title> @@ -448,6 +461,7 @@ <example> <title>Querying user status</title> + <!-- 0 /// With elogind no Unit and jurnald output is generated <programlisting>$ loginctl user-status fatima (1005) Since: Sat 2016-04-09 14:23:31 EDT; 54min ago @@ -459,13 +473,22 @@ fatima (1005) ├─session-3.scope … └─session-5.scope - ├─3473 login -- fatima + ├─3473 login -- fatima └─3515 -zsh Apr 09 14:40:30 laptop login[2325]: pam_unix(login:session): session opened for user fatima by LOGIN(uid=0) Apr 09 14:40:30 laptop login[2325]: LOGIN ON tty3 BY fatima </programlisting> + --><!-- else --> + <programlisting>$ loginctl user-status +fatima (1005) + Since: Sat 2016-04-09 14:23:31 EDT; 54min ago + State: active + Sessions: 5 *3 + Unit: user-1005.slice +</programlisting> + <!-- // 0 --> <para>There are two sessions, 3 and 5. Session 3 is a graphical session, marked with a star. The tree of processing including the two corresponding @@ -478,8 +501,13 @@ Apr 09 14:40:30 laptop login[2325]: LOGIN ON tty3 BY fatima <refsect1> <title>See Also</title> <para> - <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <!-- 0 /// elogind is in section 8 + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + --><!-- else --> + <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <!-- // 0 --> <citerefentry><refentrytitle>logind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/logind.conf.xml b/man/logind.conf.xml index 4641bbb83..abc97b356 100644 --- a/man/logind.conf.xml +++ b/man/logind.conf.xml @@ -1,39 +1,26 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ +<!ENTITY % entities SYSTEM "custom-entities.ent" > +%entities; +]> <!-- - This file is part of elogind. - - Copyright 2010 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> +<!-- 0 /// elogind does not have to enable itself in configure +<refentry id="logind.conf" conditional='ENABLE_LOGIND' + xmlns:xi="http://www.w3.org/2001/XInclude"> + <refentryinfo> + <title>logind.conf</title> + <productname>systemd</productname> +--><!-- else --> <refentry id="logind.conf" xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>logind.conf</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> +<!-- // 0 --> </refentryinfo> <refmeta> @@ -43,221 +30,344 @@ <refnamediv> <refname>logind.conf</refname> + <!-- 0 /// not supported by elogind + <refname>logind.conf.d</refname> + // 0 --> <refpurpose>Login manager configuration files</refpurpose> </refnamediv> <refsynopsisdiv> <para><filename>/etc/elogind/logind.conf</filename></para> + <!-- 0 /// not supported by elogind + <para><filename>/etc/systemd/logind.conf.d/*.conf</filename></para> + <para><filename>/run/systemd/logind.conf.d/*.conf</filename></para> + <para><filename>/usr/lib/systemd/logind.conf.d/*.conf</filename></para> + // 0 --> </refsynopsisdiv> <refsect1> <title>Description</title> - <para>These files configure various parameters of the elogind - login manager.</para> + <!-- 0 /// elogind does not need a service file. + <para>These files configure various parameters of the systemd login manager, + <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. See + <citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for a general description of the syntax.</para> + --><!-- else --> + <para>This file configures various parameters of elogind.</para> + <!-- // 0 --> </refsect1> + <!-- 0 /// elogind has only this configuration <xi:include href="standard-conf.xml" xpointer="main-conf" /> + // 0 --> <refsect1> <title>Options</title> + <!-- 0 /// elogind also supports a few system commands + <para>All options are configured in the + <literal>[Login]</literal> section:</para> + --><!-- else --> <para>All login options are configured in the <literal>[Login]</literal> section, system sleep options are configured in the <literal>[Sleep]</literal> section.</para> + <!-- // 0 --> + <!-- 1 /// elogind needs a second level, as we use two sections. --> <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> + <!-- // 1 --> + + <variablelist> + <!-- 0 /// elogind has no support for AutoVT + + <varlistentry> + <term><varname>NAutoVTs=</varname></term> + + <listitem><para>Takes a positive integer. Configures how many + virtual terminals (VTs) to allocate by default that, when + switched to and are previously unused, + <literal>autovt</literal> services are automatically spawned + on. These services are instantiated from the template unit + <filename>autovt@.service</filename> for the respective VT TTY + name, for example, <filename>autovt@tty4.service</filename>. + By default, <filename>autovt@.service</filename> is linked to + <filename>getty@.service</filename>. In other words, login + prompts are started dynamically as the user switches to unused + virtual terminals. Hence, this parameter controls how many + login <literal>gettys</literal> are available on the VTs. If a + VT is already used by some other subsystem (for example, a + graphical login), this kind of activation will not be + attempted. Note that the VT configured in + <varname>ReserveVT=</varname> is always subject to this kind + of activation, even if it is not one of the VTs configured + with the <varname>NAutoVTs=</varname> directive. Defaults to + 6. When set to 0, automatic spawning of + <literal>autovt</literal> services is + disabled.</para></listitem> + </varlistentry> - <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>ReserveVT=</varname></term> + + <listitem><para>Takes a positive integer. Identifies one + virtual terminal that shall unconditionally be reserved for + <filename>autovt@.service</filename> activation (see above). + The VT selected with this option will be marked busy + unconditionally, so that no other subsystem will allocate it. + This functionality is useful to ensure that, regardless of how + many VTs are allocated by other subsystems, one login + <literal>getty</literal> is always available. Defaults to 6 + (in other words, there will always be a + <literal>getty</literal> available on Alt-F6.). When set to 0, + VT reservation is disabled.</para></listitem> + </varlistentry> + // 0 --> + + <varlistentry> + <term><varname>KillUserProcesses=</varname></term> + + <listitem><para>Takes a boolean argument. Configures whether the processes of a + <!-- 0 /// elogind has no scope unit, and goes for cgroups only + user should be killed when the user logs out. If true, the scope unit + corresponding to the session and all processes inside that scope will be + terminated. If false, the scope is "abandoned", see + <citerefentry><refentrytitle>systemd.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + and processes are not killed. Defaults to <literal>&KILL_USER_PROCESSES;</literal>, + --><!-- else --> + user should be killed when the user logs out. If true, the processes + listed in their session cgroup will be terminated. If false, the session cgroup + is ignored + <!-- // 0 --> + but see the options <varname>KillOnlyUsers=</varname> and + <varname>KillExcludeUsers=</varname> below.</para> + + <!-- 0 /// elogind has no user manager unit, and lingering isn't clarified, yet. + <para>In addition to session processes, user process may run under the user + manager unit <filename>user@.service</filename>. Depending on the linger + settings, this may allow users to run processes independent of their login + sessions. See the description of <command>enable-linger</command> in + <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + </para> + // 0 --> + + <para>Note that setting <varname>KillUserProcesses=yes</varname> + will break tools like + <citerefentry project='die-net'><refentrytitle>screen</refentrytitle><manvolnum>1</manvolnum></citerefentry> + and + <citerefentry project='die-net'><refentrytitle>tmux</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <!-- 0 /// elogind does not provide systemd-run or any equivalent, yet. + unless they are moved out of the session scope. See example in + <citerefentry><refentrytitle>systemd-run</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + --><!-- else --> + unless they are moved out of the session scope. + <!-- // 0 --> + </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>KillOnlyUsers=</varname></term> + <term><varname>KillExcludeUsers=</varname></term> + + <listitem><para>These settings take space-separated lists of usernames that override + the <varname>KillUserProcesses=</varname> setting. A user name may be added to + <varname>KillExcludeUsers=</varname> to exclude the processes in the session scopes of + that user from being killed even if <varname>KillUserProcesses=yes</varname> is set. If + <varname>KillExcludeUsers=</varname> is not set, the <literal>root</literal> user is + excluded by default. <varname>KillExcludeUsers=</varname> may be set to an empty value + to override this default. If a user is not excluded, <varname>KillOnlyUsers=</varname> + is checked next. If this setting is specified, only the session scopes of those users + will be killed. Otherwise, users are subject to the + <varname>KillUserProcesses=yes</varname> setting.</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>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>, + <literal>suspend-then-hibernate</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> + <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> + <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> + <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> + <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 how 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> + <varlistentry> + <term><varname>HandlePowerKey=</varname></term> + <term><varname>HandleSuspendKey=</varname></term> + <term><varname>HandleHibernateKey=</varname></term> + <term><varname>HandleLidSwitch=</varname></term> + <term><varname>HandleLidSwitchExternalPower=</varname></term> + <term><varname>HandleLidSwitchDocked=</varname></term> + + <listitem><para>Controls how 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>, + <literal>suspend-then-hibernate</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>HandleLidSwitchExternalPower=</varname> is completely + ignored by default (for backwards compatibility) — an explicit + value must be set before it will be used to determine + behaviour. <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; if the system is on external power the action (if any) + specified by <varname>HandleLidSwitchExternalPower=</varname> + occurs; otherwise the <varname>HandleLidSwitch=</varname> action occurs.</para> <para>A different application may disable logind's handling of system power and sleep keys and the lid switch by taking a low-level inhibitor lock - ("handle-power-key", "handle-suspend-key", "handle-hibernate-key", - "handle-lid-switch"). This is most commonly used by graphical desktop environments + (<literal>handle-power-key</literal>, <literal>handle-suspend-key</literal>, + <literal>handle-hibernate-key</literal>, <literal>handle-lid-switch</literal>). + This is most commonly used by graphical desktop environments to take over suspend and hibernation handling, and to use their own configuration mechanisms. If a low-level inhibitor lock is taken, logind will not take any action when that key or switch is triggered and the <varname>Handle*=</varname> settings are irrelevant.</para></listitem> </varlistentry> - <varlistentry> - <term><varname>PowerKeyIgnoreInhibited=</varname></term> - <term><varname>SuspendKeyIgnoreInhibited=</varname></term> - <term><varname>HibernateKeyIgnoreInhibited=</varname></term> - <term><varname>LidSwitchIgnoreInhibited=</varname></term> + <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 that <command>systemd-logind</command> + <listitem><para>Controls whether actions that <command>elogind</command> takes when the power and sleep keys and the lid switch are triggered are subject to high-level inhibitor locks ("shutdown", "sleep", "idle"). Low level inhibitor - locks ("handle-*-key"), are always honoured, irrespective of this setting.</para> + locks (<literal>handle-power-key</literal>, <literal>handle-suspend-key</literal>, + <literal>handle-hibernate-key</literal>, <literal>handle-lid-switch</literal>), + are always honored, irrespective of this setting.</para> <para>These settings take boolean arguments. If <literal>no</literal>, the inhibitor locks taken by applications are respected. If <literal>yes</literal>, "shutdown", "sleep", and "idle" inhibitor locks are ignored. - <varname>PowerKeyIgnoreInhibited=</varname>, + <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 when <command>systemd-logind</command> is handling events by + This means that when <command>elogind</command> is handling events by itself (no low level inhibitor locks are taken by another application), the lid switch does not respect suspend blockers by default, but the power and sleep keys do.</para></listitem> - </varlistentry> + </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>HoldoffTimeoutSec=</varname></term> + + <listitem><para>Specifies the timeout after system startup or + system resume in which systemd will hold off on reacting to + lid events. This is required for the system to properly + detect any hotplugged devices so systemd can ignore lid events + if external monitors, or docks, are connected. If set to 0, + systemd will always react immediately, possibly before the + kernel fully probed all hotplugged devices. This is safe, as + long as you do not care for systemd 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>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> + <varlistentry> + <term><varname>InhibitorsMax=</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> + <listitem><para>Controls the maximum number of concurrent inhibitors to permit. Defaults to 8192 + (8K).</para></listitem> + </varlistentry> - </variablelist> + <varlistentry> + <term><varname>SessionsMax=</varname></term> + + <listitem><para>Controls the maximum number of concurrent user sessions to manage. Defaults to 8192 + (8K). Depending on how the <filename>pam_systemd.so</filename> module is included in the PAM stack + configuration, further login sessions will either be refused, or permitted but not tracked by + <filename>elogind</filename>.</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> + <!-- 1 /// elogind has an additional section for system commands. --> </refsect2> <refsect2><title>[Sleep] section:</title> - <para><command>elogind</command> supports three general power-saving modes:</para> @@ -331,13 +441,22 @@ </variablelist> </refsect2> + <!-- // 1 --> </refsect1> <refsect1> <title>See Also</title> <para> + <!-- 0 /// elogind is in section 8 + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + --><!-- else --> <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <!-- // 0 --> <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <!-- 0 /// UNNEEDED by elogind + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + // 0 --> </para> </refsect1> diff --git a/man/meson.build b/man/meson.build new file mode 100644 index 000000000..d5895eb2f --- /dev/null +++ b/man/meson.build @@ -0,0 +1,225 @@ +# SPDX-License-Identifier: LGPL-2.1+ + +# This is lame, I know, but meson has no other include mechanism +subdir('rules') + +want_man = get_option('man') +want_html = get_option('html') +xsltproc = find_program('xsltproc', + required : want_man == 'true' or want_html == 'true') +want_man = want_man != 'false' and xsltproc.found() +want_html = want_html != 'false' and xsltproc.found() + +xsltproc_flags = [ + '--nonet', + '--xinclude', + '--maxdepth', '9000', + '--stringparam', 'man.output.quietly', '1', + '--stringparam', 'funcsynopsis.style', 'ansi', + '--stringparam', 'man.authors.section.enabled', '0', + '--stringparam', 'man.copyright.section.enabled', '0', + '--stringparam', 'elogind.version', '@0@'.format(meson.project_version()), + '--path', + '@0@:@1@'.format(meson.current_build_dir(), meson.current_source_dir())] + +custom_man_xsl = files('custom-man.xsl') +custom_html_xsl = files('custom-html.xsl') +xslt_cmd = [xsltproc, '-o', '@OUTPUT0@'] + xsltproc_flags + +custom_entities_ent = configure_file( + input : 'custom-entities.ent.in', + output : 'custom-entities.ent', + configuration : conf) + +man_pages = [] +html_pages = [] +source_xml_files = [] +foreach tuple : xsltproc.found() ? manpages : [] + stem = tuple[0] + section = tuple[1] + aliases = tuple[2] + condition = tuple[3] + + xml = stem + '.xml' + html = stem + '.html' + man = stem + '.' + section + + manaliases = [] + htmlaliases = [] + foreach alias : aliases + manaliases += [alias + '.' + section] + htmlaliases += [alias + '.html'] + endforeach + + mandirn = join_paths(get_option('mandir'), 'man' + section) + + if condition == '' or conf.get(condition) == 1 + p1 = custom_target( + man, + input : xml, + output : [man] + manaliases, + command : xslt_cmd + [custom_man_xsl, '@INPUT@'], +#if 0 /// UNNEEDED by elogind +# depend_files : custom_entities_ent, +#endif // 0 + install : want_man, + install_dir : mandirn) + man_pages += [p1] + + p2 = [] + foreach htmlalias : htmlaliases + link = custom_target( + htmlalias, + input : p2, + output : htmlalias, + command : ['ln', '-fs', html, '@OUTPUT@']) + if want_html +#if 0 /// This must be configurable in elogind +# dst = join_paths(docdir, 'html', htmlalias) +#else + dst = get_option('htmldir') + dst = dst != '' ? dst: join_paths(docdir, 'html', htmlalias) +#endif // 0 + cmd = 'ln -fs @0@ $DESTDIR@1@'.format(html, dst) + meson.add_install_script('sh', '-c', cmd) + p2 += [link] + endif + html_pages += [link] + endforeach + + p3 = custom_target( + html, + input : xml, + output : html, + command : xslt_cmd + [custom_html_xsl, '@INPUT@'], +#if 0 /// UNNEEDED by elogind +# depend_files : custom_entities_ent, +#endif // 0 + depends : p2, + install : want_html, + install_dir : join_paths(docdir, 'html')) + html_pages += [p3] + + source_xml_files += files(tuple[0] + '.xml') + else + message('Skipping @0@.@1@ because @2@ is false'.format(stem, section, condition)) + endif +endforeach + +############################################################ + +have_lxml = run_command(xml_helper_py).returncode() == 0 +if not have_lxml + message('python-lxml not available, not making man page indices') +endif + +elogind_directives_xml = custom_target( + 'elogind.directives.xml', + input : source_xml_files, + output : 'elogind.directives.xml', + command : [make_directive_index_py, '@OUTPUT@'] + source_xml_files) + +nonindex_xml_files = source_xml_files + [elogind_directives_xml] +elogind_index_xml = custom_target( + 'elogind.index.xml', + input : nonindex_xml_files, + output : 'elogind.index.xml', + command : [make_man_index_py, '@OUTPUT@'] + nonindex_xml_files) + +foreach tuple : want_man or want_html ? [['elogind.directives', '7', elogind_directives_xml], + ['elogind.index', '7', elogind_index_xml]] : [] + stem = tuple[0] + section = tuple[1] + xml = tuple[2] + + html = stem + '.html' + man = stem + '.' + section + + mandirn = join_paths(get_option('mandir'), 'man' + section) + + p1 = custom_target( + man, + input : xml, + output : man, + command : xslt_cmd + [custom_man_xsl, '@INPUT@'], + install : want_man and have_lxml, + install_dir : mandirn) + man_pages += [p1] + + p2 = [] + if html == 'elogind.index.html' + htmlalias = 'index.html' + link = custom_target( + htmlalias, + input : p2, + output : htmlalias, + command : ['ln', '-fs', html, '@OUTPUT@']) + if want_html + dst = join_paths(docdir, 'html', htmlalias) + cmd = 'ln -fs @0@ $DESTDIR@1@'.format(html, dst) + meson.add_install_script('sh', '-c', cmd) + p2 += [link] + endif + html_pages += [link] + endif + + p3 = custom_target( + html, + input : xml, + output : html, + command : xslt_cmd + [custom_html_xsl, '@INPUT@'], +#if 0 /// UNNEEDED by elogind +# depend_files : custom_entities_ent, +#endif // 0 + depends : p2, + install : want_html and have_lxml, + install_dir : join_paths(docdir, 'html')) + html_pages += [p3] +endforeach + +# cannot use run_target until https://github.com/mesonbuild/meson/issues/1644 is resolved +man = custom_target( + 'man', + output : 'man', + depends : man_pages, + command : ['echo']) + +html = custom_target( + 'html', + output : 'html', + depends : html_pages, + command : ['echo']) + +#if 0 /// UNNEEDED in elogind +# run_target( +# 'doc-sync', +# depends : man_pages + html_pages, +# command : ['rsync', '-rlv', +# '--delete-excluded', +# '--include=man', +# '--include=*.html', +# '--exclude=*', +# '--omit-dir-times', +# meson.current_build_dir(), +# get_option('www-target')]) +#endif // 0 + +############################################################ + +if git.found() + custom_target( + 'update-man-rules', + output : 'update-man-rules', + # slightly strange syntax because of + # https://github.com/mesonbuild/meson/issues/1643 + # and https://github.com/mesonbuild/meson/issues/1512 + command : ['sh', '-c', + 'cd @0@ && '.format(meson.build_root()) + + 'python3 @0@/tools/make-man-rules.py `git ls-files ":/man/*.xml"` >t && '.format(meson.source_root()) + + 'mv t @0@/rules/meson.build'.format(meson.current_source_dir())], +#if 0 /// UNNEEDED by elogind +# depend_files : custom_entities_ent) +#else + ) +#endif // 0 +endif diff --git a/man/pam_elogind.xml b/man/pam_elogind.xml index c707b0307..51b285d3a 100644 --- a/man/pam_elogind.xml +++ b/man/pam_elogind.xml @@ -3,22 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2010 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> <refentry id="pam_elogind" conditional='HAVE_PAM'> @@ -26,15 +11,6 @@ <refentryinfo> <title>pam_elogind</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -253,8 +229,65 @@ for, if any. (Only applies to seats with a VT available, such as <literal>seat0</literal>)</para></listitem> </varlistentry> + </variablelist> + + <para>If not set, <command>pam_elogind</command> will determine the + values for <varname>$XDG_SEAT</varname> and <varname>$XDG_VTNR</varname> + based on the <varname>$DISPLAY</varname> variable.</para> + </refsect1> + <refsect1> + <title>Session limits</title> + + <para>PAM modules earlier in the stack, that is those that come before <command>pam_elogind.so</command>, + can set session scope limits using the PAM context objects. The data for these objects is provided as NUL-terminated C strings + and maps directly to the respective unit resource control directives. Note that these limits apply to individual sessions of the user, + they do not apply to all user processes as a combined whole. In particular, the per-user <command>user@.service</command> unit instance, + which runs the <command>elogind --user</command> manager process and its children, and is tracked outside of any session, being shared + by all the user's sessions, is not covered by these limits. + </para> + + <para> See + <citerefentry><refentrytitle>elogind.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information about the resources. + Also, see <citerefentry><refentrytitle>pam_set_data</refentrytitle><manvolnum>3</manvolnum></citerefentry> for additional information about how to set + the context objects. + </para> + + <variablelist> + <varlistentry> + <term><varname>elogind.memory_max</varname></term> + + <listitem><para>Sets unit <varname>MemoryMax=</varname>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>elogind.tasks_max</varname></term> + + <listitem><para>Sets unit <varname>TasksMax=</varname>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>elogind.cpu_weight</varname></term> + + <listitem><para>Sets unit <varname>CPUWeight=</varname>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>elogind.io_weight</varname></term> + + <listitem><para>Sets unit <varname>IOWeight=</varname>.</para></listitem> + </varlistentry> </variablelist> + + <para>Example data as can be provided from an another PAM module: + <programlisting> +pam_set_data(handle, "elogind.memory_max", (void *)"200M", cleanup); +pam_set_data(handle, "elogind.tasks_max", (void *)"50", cleanup); +pam_set_data(handle, "elogind.cpu_weight", (void *)"100", cleanup); +pam_set_data(handle, "elogind.io_weight", (void *)"340", cleanup); + </programlisting> + </para> + </refsect1> <refsect1> diff --git a/man/rules/meson.build b/man/rules/meson.build new file mode 100644 index 000000000..74191d00b --- /dev/null +++ b/man/rules/meson.build @@ -0,0 +1,349 @@ +# Do not edit. Generated by make-man-rules.py. +manpages = [ +['elogind-inhibit', '1', [], ''], + ['elogind', '8', [], ''], + ['elogind.syntax', '7', [], ''], + ['loginctl', '1', [], ''], + ['logind.conf', '5', [], ''], + ['pam_elogind', '8', [], 'HAVE_PAM'], + ['sd-bus', '3', [], ''], + ['sd-event', '3', [], ''], + ['sd-login', '3', [], 'HAVE_PAM'], + ['sd_booted', '3', [], ''], + ['sd_bus_add_match', + '3', + ['sd_bus_add_match_async', + 'sd_bus_match_signal', + 'sd_bus_match_signal_async'], + ''], + ['sd_bus_creds_get_pid', + '3', + ['sd_bus_creds_get_audit_login_uid', + 'sd_bus_creds_get_audit_session_id', + 'sd_bus_creds_get_cgroup', + 'sd_bus_creds_get_cmdline', + 'sd_bus_creds_get_comm', + 'sd_bus_creds_get_description', + 'sd_bus_creds_get_egid', + 'sd_bus_creds_get_euid', + 'sd_bus_creds_get_exe', + 'sd_bus_creds_get_fsgid', + 'sd_bus_creds_get_fsuid', + 'sd_bus_creds_get_gid', + 'sd_bus_creds_get_owner_uid', + 'sd_bus_creds_get_ppid', + 'sd_bus_creds_get_selinux_context', + 'sd_bus_creds_get_session', + 'sd_bus_creds_get_sgid', + 'sd_bus_creds_get_slice', + 'sd_bus_creds_get_suid', + 'sd_bus_creds_get_supplementary_gids', + 'sd_bus_creds_get_tid', + 'sd_bus_creds_get_tid_comm', + 'sd_bus_creds_get_tty', + 'sd_bus_creds_get_uid', + 'sd_bus_creds_get_unique_name', + 'sd_bus_creds_get_unit', + 'sd_bus_creds_get_user_slice', + 'sd_bus_creds_get_user_unit', + 'sd_bus_creds_get_well_known_names', + 'sd_bus_creds_has_bounding_cap', + 'sd_bus_creds_has_effective_cap', + 'sd_bus_creds_has_inheritable_cap', + 'sd_bus_creds_has_permitted_cap'], + ''], + ['sd_bus_creds_new_from_pid', + '3', + ['sd_bus_creds_get_augmented_mask', + 'sd_bus_creds_get_mask', + 'sd_bus_creds_ref', + 'sd_bus_creds_unref', + 'sd_bus_creds_unrefp'], + ''], + ['sd_bus_default', + '3', + ['sd_bus_default_system', + 'sd_bus_default_user', + 'sd_bus_open', + 'sd_bus_open_system', + 'sd_bus_open_system_machine', + 'sd_bus_open_system_remote', + 'sd_bus_open_user'], + ''], + ['sd_bus_error', + '3', + ['SD_BUS_ERROR_MAKE_CONST', + 'SD_BUS_ERROR_NULL', + 'sd_bus_error_copy', + 'sd_bus_error_free', + 'sd_bus_error_get_errno', + 'sd_bus_error_has_name', + 'sd_bus_error_is_set', + 'sd_bus_error_set', + 'sd_bus_error_set_const', + 'sd_bus_error_set_errno', + 'sd_bus_error_set_errnof', + 'sd_bus_error_set_errnofv', + 'sd_bus_error_setf'], + ''], + ['sd_bus_error_add_map', + '3', + ['SD_BUS_ERROR_END', 'SD_BUS_ERROR_MAP', 'sd_bus_error_map'], + ''], + ['sd_bus_get_fd', '3', [], ''], + ['sd_bus_is_open', '3', ['sd_bus_is_ready'], ''], + ['sd_bus_message_append', '3', ['sd_bus_message_appendv'], ''], + ['sd_bus_message_append_array', + '3', + ['sd_bus_message_append_array_iovec', + 'sd_bus_message_append_array_memfd', + 'sd_bus_message_append_array_space'], + ''], + ['sd_bus_message_append_basic', '3', [], ''], + ['sd_bus_message_append_string_memfd', + '3', + ['sd_bus_message_append_string_iovec', 'sd_bus_message_append_string_space'], + ''], + ['sd_bus_message_append_strv', '3', [], ''], + ['sd_bus_message_get_cookie', '3', ['sd_bus_message_get_reply_cookie'], ''], + ['sd_bus_message_get_monotonic_usec', + '3', + ['sd_bus_message_get_realtime_usec', 'sd_bus_message_get_seqnum'], + ''], + ['sd_bus_message_read_basic', '3', [], ''], + ['sd_bus_negotiate_fds', + '3', + ['sd_bus_negotiate_creds', 'sd_bus_negotiate_timestamp'], + ''], + ['sd_bus_new', '3', ['sd_bus_ref', 'sd_bus_unref', 'sd_bus_unrefp'], ''], + ['sd_bus_path_encode', + '3', + ['sd_bus_path_decode', 'sd_bus_path_decode_many', 'sd_bus_path_encode_many'], + ''], + ['sd_bus_process', '3', [], ''], + ['sd_bus_request_name', + '3', + ['sd_bus_release_name', + 'sd_bus_release_name_async', + 'sd_bus_request_name_async'], + ''], + ['sd_bus_set_connected_signal', '3', ['sd_bus_get_connected_signal'], ''], + ['sd_bus_set_sender', '3', ['sd_bus_get_sender'], ''], + ['sd_bus_set_watch_bind', '3', ['sd_bus_get_watch_bind'], ''], + ['sd_bus_slot_set_destroy_callback', + '3', + ['sd_bus_destroy_t', + 'sd_bus_slot_get_destroy_callback', + 'sd_bus_track_get_destroy_callback', + 'sd_bus_track_set_destroy_callback'], + ''], + ['sd_bus_slot_set_floating', '3', ['sd_bus_slot_get_floating'], ''], + ['sd_bus_track_add_name', + '3', + ['sd_bus_track_add_sender', + 'sd_bus_track_contains', + 'sd_bus_track_count', + 'sd_bus_track_count_name', + 'sd_bus_track_count_sender', + 'sd_bus_track_first', + 'sd_bus_track_next', + 'sd_bus_track_remove_name', + 'sd_bus_track_remove_sender'], + ''], + ['sd_bus_track_new', + '3', + ['sd_bus_track_get_bus', + 'sd_bus_track_get_recursive', + 'sd_bus_track_get_userdata', + 'sd_bus_track_ref', + 'sd_bus_track_set_recursive', + 'sd_bus_track_set_userdata', + 'sd_bus_track_unref', + 'sd_bus_track_unrefp'], + ''], + ['sd_event_add_child', + '3', + ['sd_event_child_handler_t', 'sd_event_source_get_child_pid'], + ''], + ['sd_event_add_defer', + '3', + ['sd_event_add_exit', 'sd_event_add_post', 'sd_event_handler_t'], + ''], + ['sd_event_add_inotify', + '3', + ['sd_event_inotify_handler_t', 'sd_event_source_get_inotify_mask'], + ''], + ['sd_event_add_io', + '3', + ['sd_event_io_handler_t', + 'sd_event_source', + 'sd_event_source_get_io_events', + 'sd_event_source_get_io_fd', + 'sd_event_source_get_io_fd_own', + 'sd_event_source_get_io_revents', + 'sd_event_source_set_io_events', + 'sd_event_source_set_io_fd', + 'sd_event_source_set_io_fd_own'], + ''], + ['sd_event_add_signal', + '3', + ['sd_event_signal_handler_t', 'sd_event_source_get_signal'], + ''], + ['sd_event_add_time', + '3', + ['sd_event_source_get_time', + 'sd_event_source_get_time_accuracy', + 'sd_event_source_get_time_clock', + 'sd_event_source_set_time', + 'sd_event_source_set_time_accuracy', + 'sd_event_time_handler_t'], + ''], + ['sd_event_exit', '3', ['sd_event_get_exit_code'], ''], + ['sd_event_get_fd', '3', [], ''], + ['sd_event_new', + '3', + ['sd_event', + 'sd_event_default', + 'sd_event_get_tid', + 'sd_event_ref', + 'sd_event_unref', + 'sd_event_unrefp'], + ''], + ['sd_event_now', '3', [], ''], + ['sd_event_run', '3', ['sd_event_loop'], ''], + ['sd_event_set_watchdog', '3', ['sd_event_get_watchdog'], ''], + ['sd_event_source_get_event', '3', [], ''], + ['sd_event_source_get_pending', '3', [], ''], + ['sd_event_source_set_description', + '3', + ['sd_event_source_get_description'], + ''], + ['sd_event_source_set_destroy_callback', + '3', + ['sd_event_destroy_t', 'sd_event_source_get_destroy_callback'], + ''], + ['sd_event_source_set_enabled', + '3', + ['SD_EVENT_OFF', + 'SD_EVENT_ON', + 'SD_EVENT_ONESHOT', + 'sd_event_source_get_enabled'], + ''], + ['sd_event_source_set_prepare', '3', [], ''], + ['sd_event_source_set_priority', + '3', + ['SD_EVENT_PRIORITY_IDLE', + 'SD_EVENT_PRIORITY_IMPORTANT', + 'SD_EVENT_PRIORITY_NORMAL', + 'sd_event_source_get_priority'], + ''], + ['sd_event_source_set_userdata', '3', ['sd_event_source_get_userdata'], ''], + ['sd_event_source_unref', + '3', + ['sd_event_source_ref', 'sd_event_source_unrefp'], + ''], + ['sd_event_wait', + '3', + ['SD_EVENT_ARMED', + 'SD_EVENT_EXITING', + 'SD_EVENT_FINISHED', + 'SD_EVENT_INITIAL', + 'SD_EVENT_PENDING', + 'SD_EVENT_PREPARING', + 'SD_EVENT_RUNNING', + 'sd_event_dispatch', + 'sd_event_get_iteration', + 'sd_event_get_state', + 'sd_event_prepare'], + ''], + ['sd_get_seats', + '3', + ['sd_get_machine_names', 'sd_get_sessions', 'sd_get_uids'], + 'HAVE_PAM'], + ['sd_id128_get_machine', + '3', + ['sd_id128_get_boot', + 'sd_id128_get_invocation', + 'sd_id128_get_machine_app_specific'], + ''], + ['sd_id128_randomize', '3', [], ''], + ['sd_id128_to_string', '3', ['sd_id128_from_string'], ''], + ['sd_is_fifo', + '3', + ['sd_is_mq', + 'sd_is_socket', + 'sd_is_socket_inet', + 'sd_is_socket_sockaddr', + 'sd_is_socket_unix', + 'sd_is_special'], + ''], + ['sd_listen_fds', + '3', + ['SD_LISTEN_FDS_START', 'sd_listen_fds_with_names'], + ''], + ['sd_login_monitor_new', + '3', + ['sd_login_monitor', + 'sd_login_monitor_flush', + 'sd_login_monitor_get_events', + 'sd_login_monitor_get_fd', + 'sd_login_monitor_get_timeout', + 'sd_login_monitor_unref', + 'sd_login_monitor_unrefp'], + 'HAVE_PAM'], + ['sd_machine_get_class', '3', ['sd_machine_get_ifindices'], ''], + ['sd_notify', + '3', + ['sd_notifyf', 'sd_pid_notify', 'sd_pid_notify_with_fds', 'sd_pid_notifyf'], + ''], + ['sd_pid_get_owner_uid', + '3', + ['sd_peer_get_cgroup', + 'sd_peer_get_machine_name', + 'sd_peer_get_owner_uid', + 'sd_peer_get_session', + 'sd_peer_get_slice', + 'sd_peer_get_unit', + 'sd_peer_get_user_slice', + 'sd_peer_get_user_unit', + 'sd_pid_get_cgroup', + 'sd_pid_get_machine_name', + 'sd_pid_get_session', + 'sd_pid_get_slice', + 'sd_pid_get_unit', + 'sd_pid_get_user_slice', + 'sd_pid_get_user_unit'], + 'HAVE_PAM'], + ['sd_seat_get_active', + '3', + ['sd_seat_can_graphical', + 'sd_seat_can_multi_session', + 'sd_seat_can_tty', + 'sd_seat_get_sessions'], + 'HAVE_PAM'], + ['sd_session_is_active', + '3', + ['sd_session_get_class', + 'sd_session_get_desktop', + 'sd_session_get_display', + 'sd_session_get_remote_host', + 'sd_session_get_remote_user', + 'sd_session_get_seat', + 'sd_session_get_service', + 'sd_session_get_state', + 'sd_session_get_tty', + 'sd_session_get_type', + 'sd_session_get_uid', + 'sd_session_get_vt', + 'sd_session_is_remote'], + 'HAVE_PAM'], + ['sd_uid_get_state', + '3', + ['sd_uid_get_display', + 'sd_uid_get_seats', + 'sd_uid_get_sessions', + 'sd_uid_is_on_seat'], + 'HAVE_PAM'], + ['sd_watchdog_enabled', '3', [], ''] +] +# Really, do not edit. diff --git a/man/sd-bus.xml b/man/sd-bus.xml index 0ecabab11..95e0e227b 100644 --- a/man/sd-bus.xml +++ b/man/sd-bus.xml @@ -3,22 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of systemd. - - Copyright 2016 Zbigniew Jędrzejewski-Szmek - - systemd 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. - - systemd 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 systemd; If not, see <http://www.gnu.org/licenses/>. + SPDX-License-Identifier: LGPL-2.1+ --> <refentry id="sd-bus" xmlns:xi="http://www.w3.org/2001/XInclude"> @@ -26,15 +11,6 @@ <refentryinfo> <title>sd-bus</title> <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Documentation</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> </refentryinfo> <refmeta> diff --git a/man/sd-event.xml b/man/sd-event.xml index 4fcd35685..d1fae5f15 100644 --- a/man/sd-event.xml +++ b/man/sd-event.xml @@ -3,22 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2015 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> <refentry id="sd-event" xmlns:xi="http://www.w3.org/2001/XInclude"> @@ -26,15 +11,6 @@ <refentryinfo> <title>sd-event</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -73,6 +49,7 @@ <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>, @@ -156,7 +133,12 @@ <refsect1> <title>See Also</title> <para> + <!-- 0 /// elogind is in section 8 + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + --><!-- else --> <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <!-- // 0 --> <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, diff --git a/man/sd-login.xml b/man/sd-login.xml new file mode 100644 index 000000000..5651e0485 --- /dev/null +++ b/man/sd-login.xml @@ -0,0 +1,251 @@ +<?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"> + +<!-- + SPDX-License-Identifier: LGPL-2.1+ +--> + +<refentry id="sd-login" conditional='HAVE_PAM' + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd-login</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd-login</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd-login</refname> + <refpurpose>APIs for + tracking logins</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo> + </funcsynopsis> + + <cmdsynopsis> + <command>pkg-config --cflags --libs libelogind</command> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>sd-login.h</filename> provides APIs to introspect + and monitor seat, login session and user status information on the + local system. </para> + + <para>Note that these APIs only allow purely passive access and + monitoring of seats, sessions and users. To actively make changes + to the seat configuration, terminate login sessions, or switch + session on a seat you need to utilize the D-Bus API of + systemd-logind, instead.</para> + + <para>These functions synchronously access data in + <filename>/proc</filename>, <filename>/sys/fs/cgroup</filename> + and <filename>/run</filename>. All of these are virtual file + systems, hence the runtime cost of the accesses is relatively + cheap.</para> + + <para>It is possible (and often a very good choice) to mix calls + to the synchronous interface of <filename>sd-login.h</filename> + with the asynchronous D-Bus interface of systemd-logind. However, + if this is done you need to think a bit about possible races since + the stream of events from D-Bus and from + <filename>sd-login.h</filename> interfaces such as the login + monitor are asynchronous and not ordered against each + other.</para> + + <para>If the functions return string arrays, these are generally + <constant>NULL</constant> terminated and need to be freed by the + caller with the libc + <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use, including the strings referenced therein. + Similarly, individual strings returned need to be freed, as + well.</para> + + <para>As a special exception, instead of an empty string array + <constant>NULL</constant> may be returned, which should be treated + equivalent to an empty string array.</para> + + <para>See + <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_uid_get_state</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_seat_get_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_login_monitor_new</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for more information about the functions + implemented.</para> + </refsect1> + + <refsect1> + <title>Definition of Terms</title> + + <variablelist> + <varlistentry> + <term>seat</term> + + <listitem><para>A seat consists of all hardware devices assigned to a specific + workplace. It consists of at least one graphics device, and usually also includes + keyboard, mouse. It can also include video cameras, sound cards and more. Seats + are identified by seat names, which are strings (<= 255 characters), that start + with the four characters <literal>seat</literal> followed by at least one + character from the range [a-zA-Z0-9], <literal>_</literal> and + <literal>-</literal>. They are suitable for use as file names. Seat names may or + may not be stable and may be reused if a seat becomes available again. + </para></listitem> + </varlistentry> + + <varlistentry> + <term>session</term> + + <listitem><para>A session is defined by the time a user is logged in until they + log out. A session is bound to one or no seats (the latter for 'virtual' ssh + logins). Multiple sessions can be attached to the same seat, but only one of them + can be active, the others are in the background. A session is identified by a + short string.</para> + + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + ensures that audit sessions are identical to systemd sessions, and uses the audit + session ID as session ID in systemd (if auditing is enabled). In general the + session identifier is a short string consisting only of [a-zA-Z0-9], + <literal>_</literal> and <literal>-</literal>, suitable for use as a file name. + Session IDs are unique on the local machine and are + never reused as long as the machine is online. A user (the way we know it on UNIX) + corresponds to the person using a computer. A single user can have multiple + sessions open at the same time. A user is identified by a numeric user id (UID) or + a user name (a string). A multi-session system allows multiple user sessions on + the same seat at the same time. A multi-seat system allows multiple independent + seats that can be individually and simultaneously used by different users.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>All hardware devices that are eligible to being assigned to a seat, are assigned + to one. A device can be assigned to only one seat at a time. If a device is not + assigned to any particular other seat it is implicitly assigned to the special default + seat called <literal>seat0</literal>.</para> + + <para>Note that hardware like printers, hard disks or network cards is generally not + assigned to a specific seat. They are available to all seats equally. (Well, with one + exception: USB sticks can be assigned to a seat.)</para> + + <para><literal>seat0</literal> always exists.</para> + </refsect1> + + <refsect1> + <title>udev Rules</title> + + <para>Assignment of hardware devices to seats is managed inside the udev database, via + settings on the devices:</para> + + <variablelist> + <varlistentry> + <term>Tag <literal>seat</literal></term> + + <listitem><para>When set, a device is eligible to be assigned to a seat. This tag + is set for graphics devices, mice, keyboards, video cards, sound cards and + more. Note that some devices like sound cards consist of multiple subdevices + (i.e. a PCM for input and another one for output). This tag will be set only for + the originating device, not for the individual subdevices. A UI for configuring + assignment of devices to seats should enumerate and subscribe to all devices with + this tag set and show them in the UI. Note that USB hubs can be assigned to a seat + as well, in which case all (current and future) devices plugged into it will also + be assigned to the same seat (unless they are explicitly assigned to another + seat). + </para></listitem> + </varlistentry> + + <varlistentry> + <term>Tag <literal>master-of-seat</literal></term> + + <listitem><para>When set, this device is enough for a seat to be considered + existent. This tag is usually set for the framebuffer device of graphics cards. A + seat hence consists of an arbitrary number of devices marked with the + <literal>seat</literal> tag, but (at least) one of these devices needs to be + tagged with <literal>master-of-seat</literal> before the seat is actually + considered to be around.</para></listitem> + </varlistentry> + + <varlistentry> + <term>Property <varname>ID_SEAT</varname></term> + + <listitem><para>This property specifies the name of the seat a specific device is + assigned to. If not set the device is assigned to <literal>seat0</literal>. Also, + to speed up enumeration of hardware belonging to a specific seat, the seat is also + set as tag on the device. I.e. if the property + <varname>ID_SEAT=seat-waldo</varname> is set for a device, the tag + <literal>seat-waldo</literal> will be set as well. Note that if a device is + assigned to <literal>seat0</literal>, it will usually not carry such a tag and you + need to enumerate all devices and check the <varname>ID_SEAT</varname> property + manually. Again, if a device is assigned to seat0 this is visible on the device in + two ways: with a property <varname>ID_SEAT=seat0</varname> and with no property + <varname>ID_SEAT</varname> set for it at all.</para></listitem> + </varlistentry> + + <varlistentry> + <term>Property <varname>ID_AUTOSEAT</varname></term> + + <listitem><para>When set to <literal>1</literal>, this device automatically + generates a new and independent seat, which is named after the path of the + device. This is set for specialized USB hubs like the Plugable devices, which when + plugged in should create a hotplug seat without further configuration.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Property <varname>ID_FOR_SEAT</varname></term> + + <listitem><para>When creating additional (manual) seats starting from a graphics + device this is a good choice to name the seat after. It is created from the path + of the device. This is useful in UIs for configuring seats: as soon as you create + a new seat from a graphics device, read this property and prefix it with + <literal>seat-</literal> and use it as name for the seat.</para></listitem> + </varlistentry> + </variablelist> + + <para>A seat exists only and exclusively because a properly tagged device with the + right <varname>ID_SEAT</varname> property exists. Besides udev rules there is no + persistent data about seats stored on disk.</para> + + <para>Note that + <citerefentry><refentrytitle>systemd-logind</refentrytitle><manvolnum>8</manvolnum></citerefentry> + manages ACLs on a number of device classes, to allow user code to access the device + nodes attached to a seat as long as the user has an active session on it. This is + mostly transparent to applications. As mentioned above, for certain user software it + might be a good idea to watch whether they can access device nodes instead of thinking + about seats.</para> + </refsect1> + + <xi:include href="libelogind-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_uid_get_state</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_seat_get_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_login_monitor_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + + <para> + <ulink url="https://www.freedesktop.org/wiki/Software/systemd/multiseat">Multi-Seat on Linux</ulink> + for an introduction to multi-seat support on Linux and the background for this set of APIs. + </para> + </refsect1> + +</refentry> diff --git a/man/sd_booted.xml b/man/sd_booted.xml index d6e9be16e..1dc519602 100644 --- a/man/sd_booted.xml +++ b/man/sd_booted.xml @@ -3,22 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2017 Sven Eden - - 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> <refentry id="sd_booted" @@ -27,15 +12,6 @@ <refentryinfo> <title>sd_booted</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Sven</firstname> - <surname>Eden</surname> - <email>sven.eden@gmx.de.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> diff --git a/man/sd_bus_add_match.xml b/man/sd_bus_add_match.xml index cac662f8d..db250a0cd 100644 --- a/man/sd_bus_add_match.xml +++ b/man/sd_bus_add_match.xml @@ -3,22 +3,9 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. + SPDX-License-Identifier: LGPL-2.1+ - Copyright 2016 Julian Orth - - 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/>. + Copyright © 2016 Julian Orth --> <refentry id="sd_bus_add_match"> @@ -26,14 +13,6 @@ <refentryinfo> <title>sd_bus_add_match</title> <productname>elogind</productname> - - <authorgroup> - <author> - <firstname>Julian</firstname> - <surname>Orth</surname> - <email>ju.orth@gmail.com</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -43,8 +22,11 @@ <refnamediv> <refname>sd_bus_add_match</refname> + <refname>sd_bus_add_match_async</refname> + <refname>sd_bus_match_signal</refname> + <refname>sd_bus_match_signal_async</refname> - <refpurpose>Add a match rule for message dispatching</refpurpose> + <refpurpose>Add a match rule for incoming message dispatching</refpurpose> </refnamediv> <refsynopsisdiv> @@ -52,6 +34,13 @@ <funcsynopsisinfo>#include <elogind/sd-bus.h></funcsynopsisinfo> <funcprototype> + <funcdef>typedef int (*<function>sd_bus_message_handler_t</function>)</funcdef> + <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> + <paramdef>void *<parameter>userdata</parameter></paramdef> + <paramdef>sd_bus_error *<parameter>ret_error</parameter></paramdef> + </funcprototype> + + <funcprototype> <funcdef>int <function>sd_bus_add_match</function></funcdef> <paramdef>sd_bus *<parameter>bus</parameter></paramdef> <paramdef>sd_bus_slot **<parameter>slot</parameter></paramdef> @@ -61,58 +50,125 @@ </funcprototype> <funcprototype> - <funcdef>typedef int (*<function>sd_bus_message_handler_t</function>)</funcdef> - <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> + <funcdef>int <function>sd_bus_add_match_async</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + <paramdef>sd_bus_slot **<parameter>slot</parameter></paramdef> + <paramdef>const char *<parameter>match</parameter></paramdef> + <paramdef>sd_bus_message_handler_t <parameter>callback</parameter></paramdef> + <paramdef>sd_bus_message_handler_t <parameter>install_callback</parameter></paramdef> <paramdef>void *<parameter>userdata</parameter></paramdef> - <paramdef>sd_bus_error *<parameter>ret_error</parameter></paramdef> </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_match_signal</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + <paramdef>sd_bus_slot **<parameter>slot</parameter></paramdef> + <paramdef>const char *<parameter>sender</parameter></paramdef> + <paramdef>const char *<parameter>path</parameter></paramdef> + <paramdef>const char *<parameter>interface</parameter></paramdef> + <paramdef>const char *<parameter>member</parameter></paramdef> + <paramdef>sd_bus_message_handler_t <parameter>callback</parameter></paramdef> + <paramdef>void *<parameter>userdata</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_match_signal_async</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + <paramdef>sd_bus_slot **<parameter>slot</parameter></paramdef> + <paramdef>const char *<parameter>sender</parameter></paramdef> + <paramdef>const char *<parameter>path</parameter></paramdef> + <paramdef>const char *<parameter>interface</parameter></paramdef> + <paramdef>const char *<parameter>member</parameter></paramdef> + <paramdef>sd_bus_message_handler_t <parameter>callback</parameter></paramdef> + <paramdef>sd_bus_message_handler_t <parameter>install_callback</parameter></paramdef> + <paramdef>void *<parameter>userdata</parameter></paramdef> + </funcprototype> + </funcsynopsis> </refsynopsisdiv> <refsect1> <title>Description</title> - <para> - <function>sd_bus_add_match()</function> adds a match rule used to dispatch - incoming messages. The syntax of the rule passed in - <parameter>match</parameter> is described in the - <ulink url="https://dbus.freedesktop.org/doc/dbus-specification.html">D-Bus Specification</ulink>. + <para><function>sd_bus_add_match()</function> installs a match rule for messages received on the specified bus + connection object <parameter>bus</parameter>. The syntax of the match rule expression passed in + <parameter>match</parameter> is described in the <ulink + url="https://dbus.freedesktop.org/doc/dbus-specification.html">D-Bus Specification</ulink>. The specified handler + function <parameter>callback</parameter> is called for eaching incoming message matching the specified expression, + the <parameter>userdata</parameter> parameter is passed as-is to the callback function. The match is installed + synchronously when connected to a bus broker, i.e. the call sends a control message requested the match to be added + to the broker and waits until the broker confirms the match has been installed successfully.</para> + + <para><function>sd_bus_add_match_async()</function> operates very similar to + <function>sd_bus_match_signal()</function>, however it installs the match asynchronously, in a non-blocking + fashion: a request is sent to the broker, but the call does not wait for a response. The + <parameter>install_callback</parameter> function is called when the response is later received, with the response + message from the broker as parameter. If this function is specified as <constant>NULL</constant> a default + implementation is used that terminates the bus connection should installing the match fail.</para> + + <para><function>sd_bus_match_signal()</function> is very similar to <function>sd_bus_add_match()</function>, but + only matches signals, and instead of a match expression accepts four parameters: <parameter>sender</parameter> (the + service name of the sender), <parameter>path</parameter> (the object path of the emitting object), + <parameter>interface</parameter> (the interface the signal belongs to), <parameter>member</parameter> (the signal + name), from which the match string is internally generated. Optionally, these parameters may be specified as + <constant>NULL</constant> in which case the relevant field of incoming signals is not tested.</para> + + <para><function>sd_bus_match_signal_async()</function> combines the signal matching logic of + <function>sd_bus_match_signal()</function> with the asynchronous behaviour of + <function>sd_bus_add_match_async()</function>.</para> + + <para>On success, and if non-<constant>NULL</constant>, the <parameter>slot</parameter> return parameter will be + set to a slot object that may be used as a reference to the installed match, and may be utilized to remove it again + at a later time with + <citerefentry><refentrytitle>sd_bus_slot_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If specified + as <constant>NULL</constant> the lifetime of the match is bound to the lifetime of the bus object itself, and the + match is generally not removed independently. See + <citerefentry><refentrytitle>sd_bus_slot_set_floating</refentrytitle><manvolnum>3</manvolnum></citerefentry> for + details.</para> + + <para>The message <parameter>m</parameter> passed to the callback is only borrowed, that is, the callback should + not call <citerefentry><refentrytitle>sd_bus_message_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> + on it. If the callback wants to hold on to the message beyond the lifetime of the callback, it needs to call + <citerefentry><refentrytitle>sd_bus_message_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry> to create a + new reference.</para> + + <para>If an error occurs during the callback invocation, the callback should return a negative error number + (optionally, a more precise error may be returned in <parameter>ret_error</parameter>, as well). If it wants other + callbacks that match the same rule to be called, it should return 0. Otherwise it should return a positive integer. </para> - <para> - The message <parameter>m</parameter> passed to the callback is only - borrowed, that is, the callback should not call - <citerefentry><refentrytitle>sd_bus_message_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> - on it. If the callback wants to hold on to the message beyond the lifetime - of the callback, it needs to call - <citerefentry><refentrytitle>sd_bus_message_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry> - to create a new reference. - </para> - - <para> - If an error occurs during the callback invocation, the callback should - return a negative error number. If it wants other callbacks that match the - same rule to be called, it should return 0. Otherwise it should return a - positive integer. - </para> + <para>If the <parameter>bus</parameter> refers to a direct connection (i.e. not a bus connection, as set with + <citerefentry><refentrytitle>sd_bus_set_bus_client</refentrytitle><manvolnum>3</manvolnum></citerefentry>) the + match is only installed on the client side, and the synchronous and asynchronous functions operate the same.</para> </refsect1> <refsect1> <title>Return Value</title> <para> - On success, <function>sd_bus_add_match()</function> returns 0 or a - positive integer. On failure, it returns a negative errno-style error - code. + On success, <function>sd_bus_add_match()</function> and the other calls return 0 or a positive integer. On + failure, they return a negative errno-style error code. </para> </refsect1> <refsect1> + <title>Notes</title> + + <para><function>sd_bus_add_match()</function> and the other functions described here 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>See Also</title> <para> <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_slot_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_set_bus_client</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_slot_set_floating</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/sd_bus_creds_get_pid.xml b/man/sd_bus_creds_get_pid.xml index ffc526ea6..eec510f08 100644 --- a/man/sd_bus_creds_get_pid.xml +++ b/man/sd_bus_creds_get_pid.xml @@ -3,38 +3,14 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2014 Zbigniew Jędrzejewski-Szmek - - 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> -<refentry id="sd_bus_creds_get_pid"> +<refentry id="sd_bus_creds_get_pid" xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_bus_creds_get_pid</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>A monkey with a typewriter</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -338,8 +314,8 @@ -ENXIO is returned.</para> <para><function>sd_bus_creds_get_cgroup()</function> will retrieve - the cgroup path. See <ulink - url="https://www.kernel.org/doc/Documentation/cgroups/cgroups.txt">cgroups.txt</ulink>. + the control group path. See <ulink + url="https://www.kernel.org/doc/Documentation/cgroup-v1/cgroups.txt">cgroups.txt</ulink>. </para> <para><function>sd_bus_creds_get_session()</function> will @@ -454,11 +430,16 @@ <listitem><para>The given field is not specified for the described process or peer. This will be returned by - <function>sd_bus_get_session()</function>, and - <function>sd_bus_get_owner_uid()</function> if the process is + <function>sd_bus_creds_get_unit()</function>, + <function>sd_bus_creds_get_slice()</function>, + <function>sd_bus_creds_get_user_unit()</function>, + <function>sd_bus_creds_get_user_slice()</function>, and + <function>sd_bus_creds_get_session()</function> if the process is not part of a elogind system unit, systemd user unit, systemd - slice, or logind session. It will also be returned by - <function>sd_bus_creds_get_exe()</function> and + slice, or logind session. It will be returned by + <function>sd_bus_creds_get_owner_uid()</function> if the process is + not part of a elogind user unit or logind session. It will also be + returned by <function>sd_bus_creds_get_exe()</function> and <function>sd_bus_creds_get_cmdline()</function> for kernel threads (since these are not started from an executable binary, nor have a command line), and by @@ -486,16 +467,7 @@ </variablelist> </refsect1> - <refsect1> - <title>Notes</title> - - <para><function>sd_bus_creds_get_pid()</function> and the other - functions described here 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> + <xi:include href="libelogind-pkgconfig.xml" /> <refsect1> <title>See Also</title> diff --git a/man/sd_bus_creds_new_from_pid.xml b/man/sd_bus_creds_new_from_pid.xml index 1a507cf91..a3782440d 100644 --- a/man/sd_bus_creds_new_from_pid.xml +++ b/man/sd_bus_creds_new_from_pid.xml @@ -3,38 +3,14 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2014 Zbigniew Jędrzejewski-Szmek - - 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> -<refentry id="sd_bus_creds_new_from_pid"> +<refentry id="sd_bus_creds_new_from_pid" xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_bus_creds_new_from_pid</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>A monkey with a typewriter</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -318,16 +294,7 @@ </variablelist> </refsect1> - <refsect1> - <title>Notes</title> - - <para><function>sd_bus_creds_new_from_pid()</function> and the - other calls described here 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> + <xi:include href="libelogind-pkgconfig.xml" /> <refsect1> <title>See Also</title> diff --git a/man/sd_bus_default.xml b/man/sd_bus_default.xml index 13033a52e..f8b5cf0f1 100644 --- a/man/sd_bus_default.xml +++ b/man/sd_bus_default.xml @@ -3,38 +3,14 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2014 Zbigniew Jędrzejewski-Szmek - - 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> -<refentry id="sd_bus_default"> +<refentry id="sd_bus_default" xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_bus_default</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>A monkey with a typewriter</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -165,13 +141,17 @@ not set, a suitable default for the default system D-Bus instance will be used.</para> - <para><function>sd_bus_open_system_remote()</function> connects to - the system bus on the specified <parameter>host</parameter> using - <citerefentry - project='die-net'><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>. <parameter>host</parameter> - consists of an optional user name followed by the - <literal>@</literal> symbol, and the hostname. - </para> + <para><function>sd_bus_open_system_remote()</function> connects to the system bus on + the specified host using + <citerefentry project='die-net'><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + <parameter>host</parameter> consists of an optional user name followed by the + <literal>@</literal> symbol, and the hostname, optionally followed by a + <literal>:</literal> and a machine name. If the machine name is given, a connection + is created to the system bus in the specified container on the remote machine, and + otherwise a connection to the system bus on the specified host is created.</para> + + <para>Note that entering a container is a privileged operation, and will likely only + work for the root user on the remote machine.</para> <para><function>sd_bus_open_system_machine()</function> connects to the system bus in the specified <parameter>machine</parameter>, @@ -213,21 +193,26 @@ <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> to drop the reference.</para> - <para>Queued but unwritten/unread messages also keep a reference - to their bus connection object. For this reason, even if an - application dropped all references to a bus connection, it might - not get destroyed right away. Until all incoming queued - messages are read, and until all outgoing unwritten messages are - written, the bus object will stay - alive. <function>sd_bus_flush()</function> may be used to write - all outgoing queued messages so they drop their references. To - flush the unread incoming messages, use - <function>sd_bus_close()</function>, which will also close the bus - connection. When using the default bus logic, it is a good idea to - first invoke <function>sd_bus_flush()</function> followed by - <function>sd_bus_close()</function> when a thread or process - terminates, and thus its bus connection object should be - freed.</para> + <para>Queued but unwritten/unread messages keep a reference to their bus connection object. For this reason, even + if an application dropped all references to a bus connection, it might not get destroyed right away. Until all + incoming queued messages are read, and until all outgoing unwritten messages are written, the bus object will stay + alive. <function>sd_bus_flush()</function> may be used to write all outgoing queued messages so they drop their + references. To flush the unread incoming messages, use <function>sd_bus_close()</function>, which will also close + the bus connection. When using the default bus logic, it is a good idea to first invoke + <function>sd_bus_flush()</function> followed by <function>sd_bus_close()</function> when a thread or process + terminates, and thus its bus connection object should be freed.</para> + + <para>Normally, slot objects (as created by + <citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry> and similar + calls) keep a reference to their bus connection object, too. Thus, as long as a bus slot object remains referenced + its bus object will remain allocated too. Optionally, bus slot objects may be placed in "floating" mode. When in + floating mode the life cycle of the bus slot object is bound to the bus object, i.e. when the bus object is freed + the bus slot object is automatically unreferenced too. The floating state of a slot object may be controlled + explicitly with + <citerefentry><refentrytitle>sd_bus_slot_set_floating</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + though usually floating bus slot objects are created by passing <constant>NULL</constant> as the + <parameter>slot</parameter> parameter of <function>sd_bus_add_match()</function> and related calls, thus indicating + that the caller is not directly interested in referencing and managing the bus slot object.</para> <para>The life cycle of the default bus connection should be the responsibility of the code that creates/owns the thread the @@ -283,16 +268,7 @@ by returned. See <citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> </refsect1> - <refsect1> - <title>Notes</title> - - <para><function>sd_bus_open_user()</function> and the other - functions described here 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> + <xi:include href="libelogind-pkgconfig.xml" /> <refsect1> <title>See Also</title> diff --git a/man/sd_bus_error.xml b/man/sd_bus_error.xml index 23e463602..070032bfe 100644 --- a/man/sd_bus_error.xml +++ b/man/sd_bus_error.xml @@ -3,38 +3,14 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of systemd. - - Copyright 2014 Zbigniew Jędrzejewski-Szmek - - systemd 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. - - systemd 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 systemd; If not, see <http://www.gnu.org/licenses/>. + SPDX-License-Identifier: LGPL-2.1+ --> -<refentry id="sd_bus_error"> +<refentry id="sd_bus_error" xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_bus_error</title> <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>A monkey with a typewriter</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -363,15 +339,7 @@ </variablelist> </refsect1> - <refsect1> - <title>Notes</title> - - <para><function>sd_bus_set_error()</function> and other functions - described here 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> + <xi:include href="libelogind-pkgconfig.xml" /> <refsect1> <title>See Also</title> diff --git a/man/sd_bus_error_add_map.xml b/man/sd_bus_error_add_map.xml index 93c8d7f48..1c6cddd55 100644 --- a/man/sd_bus_error_add_map.xml +++ b/man/sd_bus_error_add_map.xml @@ -3,22 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2015 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> <refentry id="sd_bus_error_add_map"> @@ -26,15 +11,6 @@ <refentryinfo> <title>sd_bus_error_add_map</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> diff --git a/man/sd_bus_get_fd.xml b/man/sd_bus_get_fd.xml index 7617eaff2..b0b546fb3 100644 --- a/man/sd_bus_get_fd.xml +++ b/man/sd_bus_get_fd.xml @@ -3,22 +3,9 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. + SPDX-License-Identifier: LGPL-2.1+ - Copyright 2016 Julian Orth - - 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/>. + Copyright © 2016 Julian Orth --> <refentry id="sd_bus_get_fd"> @@ -26,14 +13,6 @@ <refentryinfo> <title>sd_bus_get_fd</title> <productname>elogind</productname> - - <authorgroup> - <author> - <firstname>Julian</firstname> - <surname>Orth</surname> - <email>ju.orth@gmail.com</email> - </author> - </authorgroup> </refentryinfo> <refmeta> diff --git a/man/sd_bus_is_open.xml b/man/sd_bus_is_open.xml new file mode 100644 index 000000000..b9f2f5cab --- /dev/null +++ b/man/sd_bus_is_open.xml @@ -0,0 +1,111 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + SPDX-License-Identifier: LGPL-2.1+ +--> + +<refentry id="sd_bus_is_open"> + + <refentryinfo> + <title>sd_bus_is_open</title> + <productname>elogind</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_is_open</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_is_open</refname> + <refname>sd_bus_is_ready</refname> + + <refpurpose>Check whether the a bus connection is open or ready.</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <elogind/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_is_open</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_is_ready</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_is_open()</function> checks whether the specified bus connection is open, i.e. in the + process of being established, already established or in the process of being torn down. It returns zero when the + connection has not been started yet + (i.e. <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry> or some + equivalent call has not been invoked yet), or is fully terminated again (for example after + <citerefentry><refentrytitle>sd_bus_close</refentrytitle><manvolnum>3</manvolnum></citerefentry>), it returns + positive otherwise.</para> + + <para><function>sd_bus_is_ready()</function> checks whether the specified connection is fully established, + i.e. completed the connection and authentication phases of the protocol and received the + <function>Hello()</function> method call response, and is not in the process of being torn down again. It returns + zero outside of this state, and positive otherwise. Effectively, this function returns positive while regular + messages can be sent or received on the connection.</para> + + <para>To be notified when the connection is fully established, use + <citerefentry><refentrytitle>sd_bus_set_connected_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry> and + install a match for the <function>Connected()</function> signal on the + <literal>org.freedesktop.DBus.Local</literal> interface. To be notified when the connection is torn down again, + install a match for the <function>Disconnected()</function> signal on the + <literal>org.freedesktop.DBus.Local</literal> interface.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style + error code.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-ECHILD</constant></term> + + <listitem><para>The bus connection has been created in a different process.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para><function>sd_bus_is_open()</function> and <function>sd_bus_is_ready()</function> 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>See Also</title> + + <para> + <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_close</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_set_connected_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_bus_message_append.xml b/man/sd_bus_message_append.xml index ba86f7afb..5a26d10de 100644 --- a/man/sd_bus_message_append.xml +++ b/man/sd_bus_message_append.xml @@ -3,22 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2014 Zbigniew Jędrzejewski-Szmek - - 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> <refentry id="sd_bus_message_append" @@ -27,15 +12,6 @@ <refentryinfo> <title>sd_bus_message_append</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>A monkey with a typewriter</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -240,15 +216,7 @@ sd_bus_message_append(m, "ynqiuxtd", y, n, q, i, u, x, t, d);</programlisting> <xi:include href="sd_bus_message_append_basic.xml" xpointer="errors" /> - <refsect1> - <title>Notes</title> - - <para><function>sd_bus_open_user()</function> and other functions - described here are available as a shared library, which can be - compiled and linked to with the - <constant>libelogind-bus</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> - </refsect1> + <xi:include href="libelogind-pkgconfig.xml" /> <refsect1> <title>See Also</title> diff --git a/man/sd_bus_message_append_array.xml b/man/sd_bus_message_append_array.xml index 9a893035e..9ed5860f5 100644 --- a/man/sd_bus_message_append_array.xml +++ b/man/sd_bus_message_append_array.xml @@ -3,22 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2014 Zbigniew Jędrzejewski-Szmek - - 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> <refentry id="sd_bus_message_append_array" @@ -27,15 +12,6 @@ <refentryinfo> <title>sd_bus_message_append_array</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>A monkey with a typewriter</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -187,15 +163,7 @@ <xi:include href="sd_bus_message_append_basic.xml" xpointer="errors" /> - <refsect1> - <title>Notes</title> - - <para><function>sd_bus_append_array()</function> and other - functions described here 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> + <xi:include href="libelogind-pkgconfig.xml" /> <refsect1> <title>See Also</title> diff --git a/man/sd_bus_message_append_basic.xml b/man/sd_bus_message_append_basic.xml index a49a18bba..49eb6d2f8 100644 --- a/man/sd_bus_message_append_basic.xml +++ b/man/sd_bus_message_append_basic.xml @@ -3,38 +3,14 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2014 Zbigniew Jędrzejewski-Szmek - - 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> -<refentry id="sd_bus_message_append_basic"> +<refentry id="sd_bus_message_append_basic" xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_bus_message_append_basic</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>A monkey with a typewriter</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -271,15 +247,7 @@ </variablelist> </refsect1> - <refsect1> - <title>Notes</title> - - <para>The <function>sd_bus_append_basic()</function> function - described here is 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> + <xi:include href="libelogind-pkgconfig.xml" /> <refsect1> <title>See Also</title> diff --git a/man/sd_bus_message_append_string_memfd.xml b/man/sd_bus_message_append_string_memfd.xml index 08f1fd001..f2de80abf 100644 --- a/man/sd_bus_message_append_string_memfd.xml +++ b/man/sd_bus_message_append_string_memfd.xml @@ -3,22 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2014 Zbigniew Jędrzejewski-Szmek - - 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> <refentry id="sd_bus_message_append_string_memfd" @@ -27,15 +12,6 @@ <refentryinfo> <title>sd_bus_message_append_string_memfd</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>A monkey with a typewriter</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -130,20 +106,17 @@ <xi:include href="sd_bus_message_append_basic.xml" xpointer="errors" /> - <refsect1> - <title>Notes</title> - - <para>The functions described here 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> + <xi:include href="libelogind-pkgconfig.xml" /> <refsect1> <title>See Also</title> <para> + <!-- 0 /// elogind is in section 8 + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + --><!-- else --> <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <!-- // 0 --> <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html">The D-Bus specification</ulink> diff --git a/man/sd_bus_message_append_strv.xml b/man/sd_bus_message_append_strv.xml index 458e21dcb..de21dd7c6 100644 --- a/man/sd_bus_message_append_strv.xml +++ b/man/sd_bus_message_append_strv.xml @@ -3,22 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2014 Zbigniew Jędrzejewski-Szmek - - 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> <refentry id="sd_bus_message_append_strv" @@ -27,15 +12,6 @@ <refentryinfo> <title>sd_bus_message_append_strv</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>A monkey with a typewriter</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -91,15 +67,7 @@ <xi:include href="sd_bus_message_append_basic.xml" xpointer="errors" /> - <refsect1> - <title>Notes</title> - - <para>The <function>sd_bus_append_append_strv()</function> function - described here is 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> + <xi:include href="libelogind-pkgconfig.xml" /> <refsect1> <title>See Also</title> diff --git a/man/sd_bus_message_get_cookie.xml b/man/sd_bus_message_get_cookie.xml index 7994d72aa..db3c64b5d 100644 --- a/man/sd_bus_message_get_cookie.xml +++ b/man/sd_bus_message_get_cookie.xml @@ -3,38 +3,15 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2013 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> -<refentry id="sd_bus_message_get_cookie"> +<refentry id="sd_bus_message_get_cookie" + xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_bus_message_get_cookie</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -122,22 +99,17 @@ </variablelist> </refsect1> - <refsect1> - <title>Notes</title> - - <para>The <function>sd_bus_message_get_cookie()</function> and - <function>sd_bus_message_get_reply_cookie()</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> + <xi:include href="libelogind-pkgconfig.xml" /> <refsect1> <title>See Also</title> <para> + <!-- 0 /// elogind is in section 8 + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + --><!-- else --> <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <!-- // 0 --> <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> diff --git a/man/sd_bus_message_get_monotonic_usec.xml b/man/sd_bus_message_get_monotonic_usec.xml index 4fb50252a..559a997ae 100644 --- a/man/sd_bus_message_get_monotonic_usec.xml +++ b/man/sd_bus_message_get_monotonic_usec.xml @@ -3,38 +3,15 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2013 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> -<refentry id="sd_bus_message_get_monotonic_usec"> +<refentry id="sd_bus_message_get_monotonic_usec" + xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_bus_message_get_monotonic_usec</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -152,24 +129,17 @@ </variablelist> </refsect1> - <refsect1> - <title>Notes</title> - - <para>The - <function>sd_bus_message_get_monotonic_usec()</function>, - <function>sd_bus_message_get_realtime_usec()</function>, and - <function>sd_bus_message_get_seqnum()</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> + <xi:include href="libelogind-pkgconfig.xml" /> <refsect1> <title>See Also</title> <para> + <!-- 0 /// elogind is in section 8 + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + --><!-- else --> <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <!-- // 0 --> <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_negotiate_timestamp</refentrytitle><manvolnum>3</manvolnum></citerefentry>, diff --git a/man/sd_bus_message_read_basic.xml b/man/sd_bus_message_read_basic.xml index bc5de5299..fb4df08e1 100644 --- a/man/sd_bus_message_read_basic.xml +++ b/man/sd_bus_message_read_basic.xml @@ -3,22 +3,9 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. + SPDX-License-Identifier: LGPL-2.1+ - Copyright 2016 Julian Orth - - 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/>. + Copyright © 2016 Julian Orth --> <refentry id="sd_bus_message_read_basic"> @@ -26,14 +13,6 @@ <refentryinfo> <title>sd_bus_message_read_basic</title> <productname>elogind</productname> - - <authorgroup> - <author> - <firstname>Julian</firstname> - <surname>Orth</surname> - <email>ju.orth@gmail.com</email> - </author> - </authorgroup> </refentryinfo> <refmeta> diff --git a/man/sd_bus_negotiate_fds.xml b/man/sd_bus_negotiate_fds.xml index 90404d2f2..0522bd549 100644 --- a/man/sd_bus_negotiate_fds.xml +++ b/man/sd_bus_negotiate_fds.xml @@ -3,38 +3,14 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2014 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> -<refentry id="sd_bus_negotiate_fds"> +<refentry id="sd_bus_negotiate_fds" xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_bus_negotiate_fds</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -93,17 +69,9 @@ default, file descriptor passing is negotiated for all connections.</para> - <para>Note that when bus activation is used, it is highly - recommended to set the <option>AcceptFileDescriptors=</option> - setting in the <filename>.busname</filename> unit file to the same - setting as negotiated by the program ultimately activated. By - default, file descriptor passing is enabled for both.</para> - - <para><function>sd_bus_negotiate_timestamps()</function> controls - whether implicit sender timestamps shall be attached automatically - to all incoming messages. Takes a bus object and a boolean, which, - when true, enables timestamping, and, when false, disables it. - Use + <para><function>sd_bus_negotiate_timestamp()</function> controls whether implicit sender + timestamps shall be attached automatically to all incoming messages. Takes a bus object and a + boolean, which, when true, enables timestamping, and, when false, disables it. Use <citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_message_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_message_get_seqnum</refentrytitle><manvolnum>3</manvolnum></citerefentry> @@ -171,15 +139,7 @@ </variablelist> </refsect1> - <refsect1> - <title>Notes</title> - - <para><function>sd_bus_negotiate_fds()</function> and the other - functions described here 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> + <xi:include href="libelogind-pkgconfig.xml" /> <refsect1> <title>See Also</title> @@ -192,8 +152,7 @@ <citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_message_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_message_get_seqnum</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>elogind.busname</refentrytitle><manvolnum>5</manvolnum></citerefentry> + <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/sd_bus_new.xml b/man/sd_bus_new.xml index 6be915ac9..938228018 100644 --- a/man/sd_bus_new.xml +++ b/man/sd_bus_new.xml @@ -3,38 +3,14 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2014 Zbigniew Jędrzejewski-Szmek - - 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> -<refentry id="sd_bus_new"> +<refentry id="sd_bus_new" xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_bus_new</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>A monkey with a typewriter</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -163,15 +139,7 @@ </variablelist> </refsect1> - <refsect1> - <title>Notes</title> - - <para><function>sd_bus_new()</function> and other functions - described here 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> + <xi:include href="libelogind-pkgconfig.xml" /> <refsect1> <title>See Also</title> diff --git a/man/sd_bus_path_encode.xml b/man/sd_bus_path_encode.xml index 3fbb37cea..d0a16ebfc 100644 --- a/man/sd_bus_path_encode.xml +++ b/man/sd_bus_path_encode.xml @@ -3,22 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2014 Zbigniew Jędrzejewski-Szmek - - 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> <refentry id="sd_bus_path_encode"> @@ -26,15 +11,6 @@ <refentryinfo> <title>sd_bus_path_encode</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>A monkey with a typewriter</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -66,7 +42,7 @@ <funcdef>int <function>sd_bus_path_encode_many</function></funcdef> <paramdef>char **<parameter>out</parameter></paramdef> <paramdef>const char *<parameter>path_template</parameter></paramdef> - <paramdef>...</paramdef> + <paramdef>…</paramdef> </funcprototype> <funcprototype> @@ -80,7 +56,7 @@ <funcdef>int <function>sd_bus_path_decode_many</function></funcdef> <paramdef>const char *<parameter>path</parameter></paramdef> <paramdef>const char *<parameter>path_template</parameter></paramdef> - <paramdef>...</paramdef> + <paramdef>…</paramdef> </funcprototype> </funcsynopsis> </refsynopsisdiv> @@ -179,7 +155,11 @@ <title>See Also</title> <para> + <!-- 0 /// elogind is in section 8 + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + --><!-- else --> <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <!-- // 0 --> <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> diff --git a/man/sd_bus_process.xml b/man/sd_bus_process.xml index 2b7b47766..2f2075197 100644 --- a/man/sd_bus_process.xml +++ b/man/sd_bus_process.xml @@ -3,22 +3,9 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. + SPDX-License-Identifier: LGPL-2.1+ - Copyright 2016 Julian Orth - - 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/>. + Copyright © 2016 Julian Orth --> <refentry id="sd_bus_process"> @@ -26,14 +13,6 @@ <refentryinfo> <title>sd_bus_process</title> <productname>elogind</productname> - - <authorgroup> - <author> - <firstname>Julian</firstname> - <surname>Orth</surname> - <email>ju.orth@gmail.com</email> - </author> - </authorgroup> </refentryinfo> <refmeta> diff --git a/man/sd_bus_request_name.xml b/man/sd_bus_request_name.xml index d627eded1..ec71f610b 100644 --- a/man/sd_bus_request_name.xml +++ b/man/sd_bus_request_name.xml @@ -3,22 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2013 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> <refentry id="sd_bus_request_name"> @@ -26,15 +11,6 @@ <refentryinfo> <title>sd_bus_request_name</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -44,7 +20,9 @@ <refnamediv> <refname>sd_bus_request_name</refname> + <refname>sd_bus_request_name_async</refname> <refname>sd_bus_release_name</refname> + <refname>sd_bus_release_name_async</refname> <refpurpose>Request or release a well-known service name on a bus</refpurpose> </refnamediv> @@ -60,70 +38,102 @@ </funcprototype> <funcprototype> + <funcdef>int <function>sd_bus_request_name_async</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + <paramdef>sd_bus_slot **<parameter>slot</parameter></paramdef> + <paramdef>const char *<parameter>name</parameter></paramdef> + <paramdef>uint64_t <parameter>flags</parameter></paramdef> + <paramdef>sd_bus_message_handler_t <parameter>callback</parameter></paramdef> + <paramdef>void *<parameter>userdata</parameter></paramdef> + </funcprototype> + + <funcprototype> <funcdef>int <function>sd_bus_release_name</function></funcdef> <paramdef>sd_bus *<parameter>bus</parameter></paramdef> <paramdef>const char *<parameter>name</parameter></paramdef> </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_release_name_async</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + <paramdef>sd_bus_slot **<parameter>slot</parameter></paramdef> + <paramdef>const char *<parameter>name</parameter></paramdef> + <paramdef>sd_bus_message_handler_t <parameter>callback</parameter></paramdef> + <paramdef>void *<parameter>userdata</parameter></paramdef> + </funcprototype> </funcsynopsis> </refsynopsisdiv> <refsect1> <title>Description</title> - <para><function>sd_bus_request_name()</function> requests a - well-known service name on a bus. It takes a bus connection, a - valid bus name and a flags parameter. The flags parameter is a - combination of the following flags:</para> + <para><function>sd_bus_request_name()</function> requests a well-known service name on a bus. It takes a bus + connection, a valid bus name and a flags parameter. The flags parameter is a combination of the following + flags:</para> <variablelist> <varlistentry> <term><varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname></term> - <listitem><para>After acquiring the name successfully, permit - other peers to take over the name when they try to acquire it - with the <varname>SD_BUS_NAME_REPLACE_EXISTING</varname> flag - set. If <varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname> is - not set on the original request, such a request by other peers - will be denied.</para></listitem> + <listitem><para>After acquiring the name successfully, permit other peers to take over the name when they try + to acquire it with the <varname>SD_BUS_NAME_REPLACE_EXISTING</varname> flag set. If + <varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname> is not set on the original request, such a request by other + peers will be denied.</para></listitem> </varlistentry> <varlistentry> <term><varname>SD_BUS_NAME_REPLACE_EXISTING</varname></term> - <listitem><para>Take over the name if it is already acquired - by another peer, and that other peer has permitted takeover by - setting <varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname> while - acquiring it.</para></listitem> + <listitem><para>Take over the name if it is already acquired by another peer, and that other peer has permitted + takeover by setting <varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname> while acquiring it.</para></listitem> </varlistentry> <varlistentry> <term><varname>SD_BUS_NAME_QUEUE</varname></term> - <listitem><para>Queue the acquisition of the name when the - name is already taken.</para></listitem> + <listitem><para>Queue the acquisition of the name when the name is already taken.</para></listitem> </varlistentry> </variablelist> - <para><function>sd_bus_release_name()</function> releases an - acquired well-known name. It takes a bus connection and a valid - bus name as parameters.</para> + <para><function>sd_bus_request_name()</function> operates in a synchronous fashion: a message requesting the name + is sent to the bus broker, and the call waits until the broker responds.</para> + + <para><function>sd_bus_request_name_async()</function> is an asynchronous version of + <function>sd_bus_release_name()</function>. Instead of waiting for the request to complete, the request message is + enqueued. The specified <parameter>callback</parameter> will be called when the broker's response is received. If + the parameter is specified as <constant>NULL</constant> a default implementation is used instead which will + terminate the connection when the name cannot be acquired. The function returns a slot object in its + <parameter>slot</parameter> parameter — if it is passed as non-<constant>NULL</constant> — which may be used as a + reference to the name request operation. Use + <citerefentry><refentrytitle>sd_bus_slot_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> to destroy + this reference. Note that destroying the reference will not unregister the name, but simply ensure the specified + callback is no longer called.</para> + + <para><function>sd_bus_release_name()</function> releases an acquired well-known name. It takes a bus connection + and a valid bus name as parameters. This function operates synchronously, sending a release request message to the + bus broker and waiting for it to reply.</para> + + <para><function>sd_bus_release_name_async()</function> is an asynchronous version of + <function>sd_bus_release_name()</function>. The specified <parameter>callback</parameter> function is called when + the name has been released successfully. If specified as <constant>NULL</constant> a generic implementation is used + that ignores the result of the operation. As above, the <parameter>slot</parameter> (if + non-<constant>NULL</constant>) is set to an object that may be used to reference the operation.</para> + + <para>These functions are supported only on bus connections, i.e. connections to a bus broker and not on direct + connections.</para> </refsect1> <refsect1> <title>Return Value</title> - <para>On success, these calls return 0 or a positive integer. On - failure, these calls return a negative errno-style error - code.</para> - - <para>If <varname>SD_BUS_NAME_QUEUE</varname> is specified, - <function>sd_bus_request_name()</function> will return 0 when the - name is already taken by another peer and the client has been - added to the queue for the name. In that case, the caller can - subscribe to <literal>NameOwnerChanged</literal> signals to be - notified when the name is successfully acquired. - <function>sd_bus_request_name()</function> returns > 0 when the - name has immediately been acquired successfully.</para> + <para>On success, these calls return 0 or a positive integer. On failure, these calls return a negative errno-style + error code.</para> + + <para>If <varname>SD_BUS_NAME_QUEUE</varname> is specified, <function>sd_bus_request_name()</function> will return + 0 when the name is already taken by another peer and the client has been added to the queue for the name. In that + case, the caller can subscribe to <literal>NameOwnerChanged</literal> signals to be notified when the name is + successfully acquired. <function>sd_bus_request_name()</function> returns > 0 when the name has immediately + been acquired successfully.</para> </refsect1> <refsect1> @@ -135,56 +145,50 @@ <varlistentry> <term><constant>-EALREADY</constant></term> - <listitem><para>The caller already is the owner of the - specified name.</para></listitem> + <listitem><para>The caller already is the owner of the specified name.</para></listitem> </varlistentry> <varlistentry> <term><constant>-EEXIST</constant></term> - <listitem><para>The name has already been acquired by a - different peer, and SD_BUS_NAME_REPLACE_EXISTING was not - specified or the other peer did not specify - SD_BUS_NAME_ALLOW_REPLACEMENT while acquiring the + <listitem><para>The name has already been acquired by a different peer, and SD_BUS_NAME_REPLACE_EXISTING was + not specified or the other peer did not specify SD_BUS_NAME_ALLOW_REPLACEMENT while acquiring the name.</para></listitem> </varlistentry> <varlistentry> <term><constant>-ESRCH</constant></term> - <listitem><para>It was attempted to release a name that is - currently not registered on the bus.</para></listitem> + <listitem><para>It was attempted to release a name that is currently not registered on the + bus.</para></listitem> </varlistentry> <varlistentry> <term><constant>-EADDRINUSE</constant></term> - <listitem><para>It was attempted to release a name that is - owned by a different peer on the bus.</para></listitem> + <listitem><para>It was attempted to release a name that is owned by a different peer on the + bus.</para></listitem> </varlistentry> <varlistentry> <term><constant>-EINVAL</constant></term> - <listitem><para>A specified parameter is invalid. This is also - generated when the requested name is a special service name - reserved by the D-Bus specification, or when the operation is - requested on a connection that does not refer to a - bus.</para></listitem> + <listitem><para>A specified parameter is invalid. This is also generated when the requested name is a special + service name reserved by the D-Bus specification, or when the operation is requested on a connection that does + not refer to a bus.</para></listitem> </varlistentry> <varlistentry> <term><constant>-ENOTCONN</constant></term> - <listitem><para>The bus connection has been - disconnected.</para></listitem> + <listitem><para>The bus connection has been disconnected.</para></listitem> </varlistentry> <varlistentry> <term><constant>-ECHILD</constant></term> - <listitem><para>The bus connection has been created in a - different process than the current one.</para></listitem> + <listitem><para>The bus connection has been created in a different process than the current + one.</para></listitem> </varlistentry> </variablelist> </refsect1> @@ -192,12 +196,9 @@ <refsect1> <title>Notes</title> - <para>The <function>sd_bus_acquire_name()</function> and - <function>sd_bus_release_name()</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> + <para>The <function>sd_bus_acquire_name()</function> and the other interfaces described here 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> @@ -206,7 +207,8 @@ <para> <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry> + <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_slot_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/sd_bus_set_connected_signal.xml b/man/sd_bus_set_connected_signal.xml new file mode 100644 index 000000000..a439c2e60 --- /dev/null +++ b/man/sd_bus_set_connected_signal.xml @@ -0,0 +1,117 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + SPDX-License-Identifier: LGPL-2.1+ +--> + +<refentry id="sd_bus_set_connected_signal"> + + <refentryinfo> + <title>sd_bus_set_connected_signal</title> + <productname>elogind</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_set_connected_signal</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_set_connected_signal</refname> + <refname>sd_bus_get_connected_signal</refname> + + <refpurpose>Control emmission of local connection establishment signal on bus connections</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <elogind/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_set_connected_signal</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + <paramdef>int <parameter>b</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_get_connected_signal</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_set_connected_signal()</function> may be used to control whether a local, synthetic + <function>Connected()</function> signal message shall be generated and enqueued for dispatching when the connection + is fully established. If the <parameter>b</parameter> parameter is zero the message is not generated (the default), + otherwise it is generated.</para> + + <para><function>sd_bus_get_connected_signal()</function> may be used to query whether this feature is enabled. It + returns zero if not, positive otherwise.</para> + + <para>The <function>Connected()</function> signal message is generated from the + <literal>org.freedesktop.DBus.Local</literal> service and interface, and + <literal>/org/freedesktop/DBus/Local</literal> object path. Use + <citerefentry><refentrytitle>sd_bus_match_signal_async</refentrytitle><manvolnum>3</manvolnum></citerefentry> to + match on this signal.</para> + + <para>This message is particularly useful on slow transports where connections take a long time to be + established. This is especially the case when + <citerefentry><refentrytitle>sd_bus_set_watch_bind</refentrytitle><manvolnum>3</manvolnum></citerefentry> is + used. The signal is generated when the + <citerefentry><refentrytitle>sd_bus_is_ready</refentrytitle><manvolnum>3</manvolnum></citerefentry> returns + positive for the first time.</para> + + <para>The <function>Connected()</function> signal corresponds with the <function>Disconnected()</function> signal + that is synthesized locally when the connection is terminated. The latter is generated unconditionally however, + unlike the former which needs to be enabled explicitly before it is generated, with + <function>sd_bus_set_connected_signal()</function>.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style + error code.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-ECHILD</constant></term> + + <listitem><para>The bus connection has been created in a different process.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para><function>sd_bus_set_connected_signal()</function> and <function>sd_bus_get_connected_signal()</function> 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>See Also</title> + + <para> + <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_match_signal_async</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_set_watch_bind</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_is_ready</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_bus_set_sender.xml b/man/sd_bus_set_sender.xml new file mode 100644 index 000000000..463f17bae --- /dev/null +++ b/man/sd_bus_set_sender.xml @@ -0,0 +1,110 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + SPDX-License-Identifier: LGPL-2.1+ +--> + +<refentry id="sd_bus_set_sender"> + + <refentryinfo> + <title>sd_bus_set_sender</title> + <productname>elogind</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_set_sender</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_set_sender</refname> + <refname>sd_bus_get_sender</refname> + + <refpurpose>Configure default sender for outgoing messages</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <elogind/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_set_sender</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + <paramdef>const char* <parameter>name</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_get_sender</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + <paramdef>const char** <parameter>name</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_set_sender()</function> configures the default sender service name to use for outgoing + messages. The service name specified in the <parameter>name</parameter> parameter is set on all outgoing messages + that are sent on the connection and have no sender set yet, for example through + <citerefentry><refentrytitle>sd_bus_message_set_sender</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Note + that this function is only supported on direct connections, i.e. not on connections to a bus broker as the broker + will fill in the sender service name automatically anyway. By default no sender name is configured, and hence + messages are sent without sender field set. If the <parameter>name</parameter> parameter is specified as + <constant>NULL</constant> the default sender service name is cleared, returning to the default state if a default + sender service name was set before. If passed as non-<constant>NULL</constant> the specified name must be a valid + unique or well-known service name.</para> + + <para><function>sd_bus_get_sender()</function> may be used to query the current default service name for outgoing + messages.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style + error code.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-ECHILD</constant></term> + + <listitem><para>The bus connection has been created in a different process.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EPERM</constant></term> + + <listitem><para>The specified bus connection object is a not a direct but a brokered connection.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para><function>sd_bus_set_sender()</function> and <function>sd_bus_get_sender()</function> 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>See Also</title> + + <para> + <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_message_set_sender</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_bus_set_watch_bind.xml b/man/sd_bus_set_watch_bind.xml new file mode 100644 index 000000000..927ed88f4 --- /dev/null +++ b/man/sd_bus_set_watch_bind.xml @@ -0,0 +1,126 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + SPDX-License-Identifier: LGPL-2.1+ +--> + +<refentry id="sd_bus_set_watch_bind"> + + <refentryinfo> + <title>sd_bus_set_watch_bind</title> + <productname>elogind</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_set_watch_bind</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_set_watch_bind</refname> + <refname>sd_bus_get_watch_bind</refname> + + <refpurpose>Control socket binding watching on bus connections</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <elogind/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_set_watch_bind</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + <paramdef>int <parameter>b</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_get_watch_bind</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_set_watch_bind()</function> may be used to enable or disable client-side watching of server + socket binding for a bus connection object. If the <parameter>b</parameter> is true, the feature is enabled, + otherwise disabled (which is the default). When enabled, and the selected bus address refers to an + <filename>AF_UNIX</filename> socket in the file system which does not exist while the connection attempt is made an + <citerefentry><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry> watch is installed on + it, waiting for the socket to appear. As soon as the socket appears the connection is made. This functionality is + useful in particular in early-boot programs that need to run before the system bus is available, but want to + connect to it the instant it may be connected to.</para> + + <para><function>sd_bus_get_watch_bind()</function> may be used to query the current setting of this feature. It + returns zero when the feature is disabled, and positive if enabled.</para> + + <para>Note that no timeout is applied while it is waited for the socket to appear. This means that any synchronous + remote operation (such as + <citerefentry><refentrytitle>sd_bus_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry> or + <citerefentry><refentrytitle>sd_bus_request_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>), that is + used on a connection with this feature enabled that is not established yet might block unbounded if the socket is + never created. However, asynchronous remote operations (such as + <citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_add_match_async</refentrytitle><manvolnum>3</manvolnum></citerefentry> or + <citerefentry><refentrytitle>sd_bus_request_match_async</refentrytitle><manvolnum>3</manvolnum></citerefentry>) do + not block in this case, and safely enqueue the requested operations to be dispatched the instant the connection is + set up.</para> + + <para>Use <citerefentry><refentrytitle>sd_bus_is_ready</refentrytitle><manvolnum>3</manvolnum></citerefentry> to + determine whether the connection is fully established, i.e. whether the peer socket has been bound, connected to + and authenticated. Use + <citerefentry><refentrytitle>sd_bus_set_connected_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry> to + be notified when the connection is fully established.</para> + + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style + error code.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-ECHILD</constant></term> + + <listitem><para>The bus connection has been created in a different process.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para><function>sd_bus_set_watch_bind()</function> and <function>sd_bus_get_watch_bind()</function> 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>See Also</title> + + <para> + <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_request_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_is_ready</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_set_connected_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_bus_slot_set_destroy_callback.xml b/man/sd_bus_slot_set_destroy_callback.xml new file mode 100644 index 000000000..c1ce4b92c --- /dev/null +++ b/man/sd_bus_slot_set_destroy_callback.xml @@ -0,0 +1,131 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- SPDX-License-Identifier: LGPL-2.1+ --> + +<refentry id="sd_bus_slot_set_destroy_callback" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_bus_slot_set_destroy_callback</title> + <productname>elogind</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_slot_set_destroy_callback</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_slot_set_destroy_callback</refname> + <refname>sd_bus_slot_get_destroy_callback</refname> + <refname>sd_bus_track_set_destroy_callback</refname> + <refname>sd_bus_track_get_destroy_callback</refname> + <refname>sd_bus_destroy_t</refname> + + <refpurpose>Define the callback function for resource cleanup.</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <elogind/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>typedef int (*<function>sd_bus_destroy_t</function>)</funcdef> + <paramdef>void *<parameter>userdata</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_slot_set_destroy_callback</function></funcdef> + <paramdef>sd_bus_slot *<parameter>slot</parameter></paramdef> + <paramdef>sd_bus_destroy_t <parameter>callback</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_slot_get_destroy_callback</function></funcdef> + <paramdef>sd_bus_slot *<parameter>slot</parameter></paramdef> + <paramdef>sd_bus_destroy_t *<parameter>callback</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_track_set_destroy_callback</function></funcdef> + <paramdef>sd_bus_track *<parameter>track</parameter></paramdef> + <paramdef>sd_bus_destroy_t <parameter>callback</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_track_get_destroy_callback</function></funcdef> + <paramdef>sd_bus_track *<parameter>track</parameter></paramdef> + <paramdef>sd_bus_destroy_t *<parameter>callback</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_slot_set_destroy_callback()</function> sets <parameter>callback</parameter> as the callback + function to be called right before the bus slot object <parameter>slot</parameter> is deallocated. The + <parameter>userdata</parameter> pointer from the slot object will be passed as the <parameter>userdata</parameter> + parameter. This pointer can be set by an argument to the constructor functions, see + <citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>, or directly, + see <citerefentry><refentrytitle>sd_bus_slot_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + This callback function is called even if <parameter>userdata</parameter> is <constant>NULL</constant>. Note that + this callback is invoked at a time where the bus slot object itself is already invalidated, and executing + operations or taking new references to the bus slot object is not permissible.</para> + + <para><function>sd_bus_slot_get_destroy_callback()</function> returns the current callback + for <parameter>slot</parameter> in the <parameter>callback</parameter> parameter.</para> + + <para><function>sd_bus_track_set_destroy_callback()</function> and + <function>sd_bus_track_get_destroy_callback</function> provide equivalent functionality for the + <parameter>userdata</parameter> pointer associated with bus peer tracking objects. For details about bus peer + tracking objects, see + <citerefentry><refentrytitle>sd_bus_track_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, <function>sd_bus_slot_set_destroy_callback()</function> and + <function>sd_bus_track_set_destroy_callback()</function> return 0 or a positive integer. On failure, they return a + negative errno-style error code.</para> + + <para><function>sd_bus_slot_get_destroy_callback()</function> and + <function>sd_bus_track_get_destroy_callback</function> return positive if the destroy callback function is set, 0 + if not. On failure, they return a negative errno-style error code.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>The <parameter>slot</parameter> or <parameter>track</parameter> parameter is + <constant>NULL</constant>.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <xi:include href="libelogind-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_slot_set_floating</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_track_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_slot_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_track_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_bus_slot_set_floating.xml b/man/sd_bus_slot_set_floating.xml new file mode 100644 index 000000000..a2a134e9f --- /dev/null +++ b/man/sd_bus_slot_set_floating.xml @@ -0,0 +1,118 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- SPDX-License-Identifier: LGPL-2.1+ --> + +<refentry id="sd_bus_slot_set_floating" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_bus_slot_set_floating</title> + <productname>elogind</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_bus_slot_set_floating</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_bus_slot_set_floating</refname> + <refname>sd_bus_slot_get_floating</refname> + + <refpurpose>Control whether a bus slot object is "floating".</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <elogind/sd-bus.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_bus_slot_set_floating</function></funcdef> + <paramdef>sd_bus_slot *<parameter>slot</parameter></paramdef> + <paramdef>int <parameter>b</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_slot_get_floating</function></funcdef> + <paramdef>sd_bus_slot *<parameter>slot</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_bus_slot_set_floating()</function> controls whether the specified bus slot object + <parameter>slot</parameter> shall be "floating" or not. A floating bus slot object's lifetime is bound to the + lifetime of the bus object it is associated with, meaning that it remains allocated as long as the bus object + itself and is freed automatically when the bus object is freed. Regular (i.e. non-floating) bus slot objects keep + the bus referenced, hence the bus object remains allocated at least as long as there remains at least one + referenced bus slot object around. The floating state hence controls the direction of referencing between the bus + object and the bus slot objects: if floating the bus pins the bus slot, and otherwise the bus slot pins the bus + objects. Use <function>sd_bus_slot_set_floating()</function> to switch between both modes: if the + <parameter>b</parameter> parameter is zero, the slot object is considered floating, otherwise it is made a regular + (non-floating) slot object.</para> + + <para>Bus slot objects may be allocated with calls such as + <citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If the + <parameter>slot</parameter> of these functions is non-<constant>NULL</constant> the slot object will be of the + regular kind (i.e. non-floating), otherwise it will be created floating. With + <function>sd_bus_slot_set_floating()</function> a bus slot object allocated as regular can be converted into a + floating object and back. This is particularly useful for creating a bus slot object, then changing parameters of + it, and then turning it into a floating object, whose lifecycle is managed by the bus object.</para> + + <para><function>sd_bus_slot_get_floating()</function> returns the current floating state of the specified bus slot + object. It returns negative on error, zero if the bus slot object is a regular (non-floating) object and positive + otherwise.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style + error code.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>The <parameter>slot</parameter> parameter is <constant>NULL</constant>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ECHILD</constant></term> + + <listitem><para>The bus connection has been created in a different process.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ESTALE</constant></term> + + <listitem><para>The bus object the specified bus slot object is associated with has already been freed, and + hence no change in the floating state can be made anymore.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <xi:include href="libelogind-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_slot_set_destroy_callback</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_bus_track_add_name.xml b/man/sd_bus_track_add_name.xml index 8496ee881..e40bb0063 100644 --- a/man/sd_bus_track_add_name.xml +++ b/man/sd_bus_track_add_name.xml @@ -3,38 +3,14 @@ "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/>. + SPDX-License-Identifier: LGPL-2.1+ --> -<refentry id="sd_bus_track_add_name"> +<refentry id="sd_bus_track_add_name" xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_bus_track_add_name</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -240,13 +216,7 @@ </variablelist> </refsect1> - <refsect1> - <title>Notes</title> - - <para><function>sd_bus_track_add_name()</function> and the other calls described here 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> + <xi:include href="libelogind-pkgconfig.xml" /> <refsect1> <title>See Also</title> diff --git a/man/sd_bus_track_new.xml b/man/sd_bus_track_new.xml index e8a252125..c290fb32b 100644 --- a/man/sd_bus_track_new.xml +++ b/man/sd_bus_track_new.xml @@ -3,38 +3,14 @@ "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/>. + SPDX-License-Identifier: LGPL-2.1+ --> -<refentry id="sd_bus_track_new"> +<refentry id="sd_bus_track_new" xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_bus_track_new</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -242,13 +218,7 @@ </variablelist> </refsect1> - <refsect1> - <title>Notes</title> - - <para><function>sd_bus_track_new()</function> and the other calls described here 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> + <xi:include href="libelogind-pkgconfig.xml" /> <refsect1> <title>See Also</title> diff --git a/man/sd_event_add_child.xml b/man/sd_event_add_child.xml index 9925cec33..447e797db 100644 --- a/man/sd_event_add_child.xml +++ b/man/sd_event_add_child.xml @@ -3,22 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2014 Zbigniew Jędrzejewski-Szmek - - 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> <refentry id="sd_event_add_child" xmlns:xi="http://www.w3.org/2001/XInclude"> @@ -26,15 +11,6 @@ <refentryinfo> <title>sd_event_add_child</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>More text</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -234,6 +210,7 @@ <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>, diff --git a/man/sd_event_add_defer.xml b/man/sd_event_add_defer.xml index dd88b0982..326579691 100644 --- a/man/sd_event_add_defer.xml +++ b/man/sd_event_add_defer.xml @@ -3,22 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2014 Zbigniew Jędrzejewski-Szmek - - 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> <refentry id="sd_event_add_defer" xmlns:xi="http://www.w3.org/2001/XInclude"> @@ -26,16 +11,7 @@ <refentryinfo> <title>sd_event_add_defer</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>More text</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> - </refentryinfo> + </refentryinfo> <refmeta> <refentrytitle>sd_event_add_defer</refentrytitle> @@ -205,6 +181,7 @@ <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>, diff --git a/man/sd_event_add_inotify.xml b/man/sd_event_add_inotify.xml new file mode 100644 index 000000000..b28847f92 --- /dev/null +++ b/man/sd_event_add_inotify.xml @@ -0,0 +1,193 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- SPDX-License-Identifier: LGPL-2.1+ --> + +<refentry id="sd_event_add_inotify" xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_event_add_inotify</title> + <productname>elogind</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_event_add_inotify</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_event_add_inotify</refname> + <refname>sd_event_source_get_inotify_mask</refname> + <refname>sd_event_inotify_handler_t</refname> + + <refpurpose>Add an "inotify" file system inode event source to an event loop</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <elogind/sd-event.h></funcsynopsisinfo> + + <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo> + + <funcprototype> + <funcdef>typedef int (*<function>sd_event_inotify_handler_t</function>)</funcdef> + <paramdef>sd_event_source *<parameter>s</parameter></paramdef> + <paramdef>const struct inotify_event *<parameter>event</parameter></paramdef> + <paramdef>void *<parameter>userdata</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_add_inotify</function></funcdef> + <paramdef>sd_event *<parameter>event</parameter></paramdef> + <paramdef>sd_event_source **<parameter>source</parameter></paramdef> + <paramdef>const char *<parameter>path</parameter></paramdef> + <paramdef>uint32_t <parameter>mask</parameter></paramdef> + <paramdef>sd_event_inotify_handler_t <parameter>handler</parameter></paramdef> + <paramdef>void *<parameter>userdata</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_source_get_inotify_mask</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + <paramdef>uint32_t *<parameter>mask</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_event_add_inotify()</function> adds a new <citerefentry + project='man-pages'><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry> file system inode + event source to an event loop. The event loop object is specified in the <parameter>event</parameter> parameter, + the event source object is returned in the <parameter>source</parameter> parameter. The <parameter>path</parameter> + parameter specifies the path of the file system inode to watch. The <parameter>handler</parameter> must reference a + function to call when the inode changes. The handler function will be passed the <parameter>userdata</parameter> + pointer, which may be chosen freely by the caller. The handler also receives a pointer to a <structname>struct + inotify_event</structname> structure containing information about the inode event. The <parameter>mask</parameter> + parameter specifie which types of inode events to watch specifically. It must contain an OR-ed combination of + <constant>IN_ACCESS</constant>, <constant>IN_ATTRIB</constant>, <constant>IN_CLOSE_WRITE</constant>, … flags. See + <citerefentry project='man-pages'><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry> for + further information.</para> + + <para>If multiple event sources are installed for the same inode the backing inotify watch descriptor is + automatically shared. The mask parameter may contain any flag defined by the inotify API, with the exception of + <constant>IN_MASK_ADD</constant>.</para> + + <para>The handler is enabled continuously (<constant>SD_EVENT_ON</constant>), but this may be changed with + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Alternatively, + the <constant>IN_ONESHOT</constant> mask flag may be used to request <constant>SD_EVENT_ONESHOT</constant> mode. + If the handler function returns a negative error code, it will be disabled after the invocation, even if the + <constant>SD_EVENT_ON</constant> mode was requested before. + </para> + + <para>As a special limitation the priority of inotify event sources may only be altered (see + <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>) + in the time between creation of the event source object with <function>sd_event_add_inotify()</function> and the + beginning of the next event loop iteration. Attempts of changing the priority any later will be refused. Consider + freeing and allocating a new inotify event source to change the priority at that point.</para> + + <para>To destroy an event source object use + <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, but note + that the event source is only removed from the event loop when all references to the event source are dropped. To + make sure an event source does not fire anymore, even when there's still a reference to it kept, consider disabling + it with + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + + <para>If the second parameter of <function>sd_event_add_inotify()</function> is passed as NULL no reference to the + event source object is returned. In this case the event source is considered "floating", and will be destroyed + implicitly when the event loop itself is destroyed.</para> + + <para><function>sd_event_source_get_inotify_mask()</function> retrieves the configured inotify watch mask of an + event source created previously with <function>sd_event_add_inotify()</function>. It takes the event source object + as the <parameter>source</parameter> parameter and a pointer to a <type>uint32_t</type> variable to return the mask + in.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style + error code.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-ENOMEM</constant></term> + + <listitem><para>Not enough memory to allocate an object.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>An invalid argument has been passed. This includes specifying a mask with + <constant>IN_MASK_ADD</constant> set.</para></listitem> + </varlistentry> + + <varlistentry> + <term><constant>-ESTALE</constant></term> + + <listitem><para>The event loop is already terminated.</para></listitem> + + </varlistentry> + + <varlistentry> + <term><constant>-ECHILD</constant></term> + + <listitem><para>The event loop has been created in a different process.</para></listitem> + + </varlistentry> + + <varlistentry> + <term><constant>-EDOM</constant></term> + + <listitem><para>The passed event source is not an inotify process event source.</para></listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <!-- 0 /// elogind has no inotify test program. + <refsect1> + <title>Examples</title> + + <example> + <title>A simple program that uses inotify to monitor one or two directories</title> + + <programlisting><xi:include href="inotify-watch-tmp.c" parse="text" /></programlisting> + </example> + </refsect1> + // 0 --> + + <xi:include href="libelogind-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_event_add_io.xml b/man/sd_event_add_io.xml index 3ba7c3bd3..07a0591a4 100644 --- a/man/sd_event_add_io.xml +++ b/man/sd_event_add_io.xml @@ -3,22 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2015 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> <refentry id="sd_event_add_io" xmlns:xi="http://www.w3.org/2001/XInclude"> @@ -26,15 +11,6 @@ <refentryinfo> <title>sd_event_add_io</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -49,6 +25,8 @@ <refname>sd_event_source_get_io_revents</refname> <refname>sd_event_source_get_io_fd</refname> <refname>sd_event_source_set_io_fd</refname> + <refname>sd_event_source_get_io_fd_own</refname> + <refname>sd_event_source_set_io_fd_own</refname> <refname>sd_event_source</refname> <refname>sd_event_io_handler_t</refname> @@ -108,6 +86,17 @@ <paramdef>int <parameter>fd</parameter></paramdef> </funcprototype> + <funcprototype> + <funcdef>int <function>sd_event_source_get_io_fd_own</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_source_set_io_fd_own</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + <paramdef>int <parameter>b</parameter></paramdef> + </funcprototype> + </funcsynopsis> </refsynopsisdiv> @@ -223,6 +212,17 @@ changes the UNIX file descriptor of an I/O event source created previously with <function>sd_event_add_io()</function>. It takes the event source object and the new file descriptor.</para> + + <para><function>sd_event_source_set_io_fd_own()</function> controls whether the file descriptor of the event source + shall be closed automatically when the event source is freed, i.e. whether it shall be considered 'owned' by the + event source object. By default it is not closed automatically, and the application has to do this on its own. The + <parameter>b</parameter> parameter is a boolean parameter: if zero, the file descriptor is not closed automatically + when the event source is freed, otherwise it is closed.</para> + + <para><function>sd_event_source_get_io_fd_own()</function> may be used to query the current setting of the file + descriptor ownership boolean flag as set with <function>sd_event_source_set_io_fd_own()</function>. It returns + positive if the file descriptor is closed automatically when the event source is destroyed, zero if not, and + negative on error.</para> </refsect1> <refsect1> @@ -279,7 +279,12 @@ <title>See Also</title> <para> + <!-- 0 /// elogind is in section 8 + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + --><!-- else --> <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <!-- // 0 --> <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>, diff --git a/man/sd_event_add_signal.xml b/man/sd_event_add_signal.xml index dec185a97..22c4399f8 100644 --- a/man/sd_event_add_signal.xml +++ b/man/sd_event_add_signal.xml @@ -3,22 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2014 Zbigniew Jędrzejewski-Szmek - - 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> <refentry id="sd_event_add_signal" xmlns:xi="http://www.w3.org/2001/XInclude"> @@ -26,15 +11,6 @@ <refentryinfo> <title>sd_event_add_signal</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>More text</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -209,6 +185,7 @@ <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>, diff --git a/man/sd_event_add_time.xml b/man/sd_event_add_time.xml index 426dff1c5..80d19f260 100644 --- a/man/sd_event_add_time.xml +++ b/man/sd_event_add_time.xml @@ -3,22 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2014 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> <refentry id="sd_event_add_time" xmlns:xi="http://www.w3.org/2001/XInclude"> @@ -26,15 +11,6 @@ <refentryinfo> <title>sd_event_add_time</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -299,6 +275,7 @@ <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>, diff --git a/man/sd_event_exit.xml b/man/sd_event_exit.xml index 7ac12ae5b..91d0bbf09 100644 --- a/man/sd_event_exit.xml +++ b/man/sd_event_exit.xml @@ -3,22 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2015 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> <refentry id="sd_event_exit" xmlns:xi="http://www.w3.org/2001/XInclude"> @@ -26,15 +11,6 @@ <refentryinfo> <title>sd_event_exit</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -153,7 +129,11 @@ <title>See Also</title> <para> + <!-- 0 /// elogind is in section 8 + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + --><!-- else --> <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <!-- // 0 --> <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry> diff --git a/man/sd_event_get_fd.xml b/man/sd_event_get_fd.xml index 88671a2b9..61fb83ce6 100644 --- a/man/sd_event_get_fd.xml +++ b/man/sd_event_get_fd.xml @@ -3,22 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2014 Zbigniew Jędrzejewski-Szmek - - 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> <refentry id="sd_event_get_fd" xmlns:xi="http://www.w3.org/2001/XInclude"> @@ -26,15 +11,6 @@ <refentryinfo> <title>sd_event_get_fd</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>More text</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> </refentryinfo> <refmeta> diff --git a/man/sd_event_new.xml b/man/sd_event_new.xml index 40a686b14..79449b938 100644 --- a/man/sd_event_new.xml +++ b/man/sd_event_new.xml @@ -3,22 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2014 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> <refentry id="sd_event_new" xmlns:xi="http://www.w3.org/2001/XInclude"> @@ -26,15 +11,6 @@ <refentryinfo> <title>sd_event_new</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> diff --git a/man/sd_event_now.xml b/man/sd_event_now.xml index b419e7d82..c746a9ff8 100644 --- a/man/sd_event_now.xml +++ b/man/sd_event_now.xml @@ -3,22 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2015 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> <refentry id="sd_event_now" xmlns:xi="http://www.w3.org/2001/XInclude"> @@ -26,15 +11,6 @@ <refentryinfo> <title>sd_event_now</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -135,7 +111,11 @@ <title>See Also</title> <para> + <!-- 0 /// elogind is in section 8 + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + --><!-- else --> <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <!-- // 0 --> <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, diff --git a/man/sd_event_run.xml b/man/sd_event_run.xml index d37febef4..16b900250 100644 --- a/man/sd_event_run.xml +++ b/man/sd_event_run.xml @@ -3,22 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2015 Zbigniew Jędrzejewski-Szmek - - 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> <refentry id="sd_event_run" xmlns:xi="http://www.w3.org/2001/XInclude"> @@ -26,15 +11,6 @@ <refentryinfo> <title>sd_event_run</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Tom</firstname> - <surname>Gundersen</surname> - <email>teg@jklm.no</email> - </author> - </authorgroup> </refentryinfo> <refmeta> diff --git a/man/sd_event_set_watchdog.xml b/man/sd_event_set_watchdog.xml index 230668c42..e1bca3815 100644 --- a/man/sd_event_set_watchdog.xml +++ b/man/sd_event_set_watchdog.xml @@ -3,22 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2015 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> <refentry id="sd_event_set_watchdog" xmlns:xi="http://www.w3.org/2001/XInclude"> @@ -26,15 +11,6 @@ <refentryinfo> <title>sd_event_set_watchdog</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -158,7 +134,11 @@ <title>See Also</title> <para> + <!-- 0 /// elogind is in section 8 + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + --><!-- else --> <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <!-- // 0 --> <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, diff --git a/man/sd_event_source_get_event.xml b/man/sd_event_source_get_event.xml index c9a52af68..33d0d481c 100644 --- a/man/sd_event_source_get_event.xml +++ b/man/sd_event_source_get_event.xml @@ -3,22 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2015 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> <refentry id="sd_event_source_get_event" xmlns:xi="http://www.w3.org/2001/XInclude"> @@ -26,15 +11,6 @@ <refentryinfo> <title>sd_event_source_get_event</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> diff --git a/man/sd_event_source_get_pending.xml b/man/sd_event_source_get_pending.xml index ea3c21db8..f9043354a 100644 --- a/man/sd_event_source_get_pending.xml +++ b/man/sd_event_source_get_pending.xml @@ -3,22 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2015 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> <refentry id="sd_event_source_get_pending" xmlns:xi="http://www.w3.org/2001/XInclude"> @@ -26,15 +11,6 @@ <refentryinfo> <title>sd_event_source_get_pending</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> diff --git a/man/sd_event_source_set_description.xml b/man/sd_event_source_set_description.xml index 9e8a1d6d9..c83396cca 100644 --- a/man/sd_event_source_set_description.xml +++ b/man/sd_event_source_set_description.xml @@ -3,22 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2014 Zbigniew Jędrzejewski-Szmek - - 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> <refentry id="sd_event_source_set_description" xmlns:xi="http://www.w3.org/2001/XInclude"> @@ -26,15 +11,6 @@ <refentryinfo> <title>sd_event_source_set_description</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>More text</contrib> - <firstname>Zbigniew</firstname> - <surname>Jędrzejewski-Szmek</surname> - <email>zbyszek@in.waw.pl</email> - </author> - </authorgroup> </refentryinfo> <refmeta> diff --git a/man/sd_event_source_set_destroy_callback.xml b/man/sd_event_source_set_destroy_callback.xml new file mode 100644 index 000000000..aa6d0e1b3 --- /dev/null +++ b/man/sd_event_source_set_destroy_callback.xml @@ -0,0 +1,112 @@ +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- SPDX-License-Identifier: LGPL-2.1+ --> + +<refentry id="sd_event_source_set_destroy_callback" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>sd_event_source_set_destroy_callback</title> + <productname>elogind</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>sd_event_source_set_destroy_callback</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_event_source_set_destroy_callback</refname> + <refname>sd_event_source_get_destroy_callback</refname> + <refname>sd_event_destroy_t</refname> + + <refpurpose>Define the callback function for resource cleanup.</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <elogind/sd-event.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>typedef int (*<function>sd_event_destroy_t</function>)</funcdef> + <paramdef>void *<parameter>userdata</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_source_set_destroy_callback</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + <paramdef>sd_event_destroy_t <parameter>callback</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_event_source_get_destroy_callback</function></funcdef> + <paramdef>sd_event_source *<parameter>source</parameter></paramdef> + <paramdef>sd_event_destroy_t *<parameter>callback</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_event_source_set_destroy_callback()</function> sets <parameter>callback</parameter> as the + callback function to be called right before the event source object <parameter>source</parameter> is + deallocated. The <parameter>userdata</parameter> pointer from the event source object will be passed as the + <parameter>userdata</parameter> parameter. This pointer can be set by an argument to the constructor functions, see + <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, or directly, + see + <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + This callback function is called even if <parameter>userdata</parameter> is <constant>NULL</constant>. Note that + this callback is invoked at a time where the event source object itself is already invalidated, and executing + operations or taking new references to the event source object is not permissible.</para> + + <para><function>sd_event_source_get_destroy_callback()</function> returns the current callback + for <parameter>source</parameter> in the <parameter>callback</parameter> parameter.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, <function>sd_event_source_set_destroy_callback()</function> returns 0 or a positive integer. On + failure, it returns a negative errno-style error code.</para> + + <para><function>sd_event_source_get_destroy_callback()</function> returns positive if the destroy callback function + is set, 0 if not. On failure, returns a negative errno-style error code.</para> + </refsect1> + + <refsect1> + <title>Errors</title> + + <para>Returned errors may indicate the following problems:</para> + + <variablelist> + <varlistentry> + <term><constant>-EINVAL</constant></term> + + <listitem><para>The <parameter>source</parameter> parameter is <constant>NULL</constant>.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <xi:include href="libelogind-pkgconfig.xml" /> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_event_source_set_enabled.xml b/man/sd_event_source_set_enabled.xml index dd7fa9932..ac6dcd74d 100644 --- a/man/sd_event_source_set_enabled.xml +++ b/man/sd_event_source_set_enabled.xml @@ -3,22 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2015 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> <refentry id="sd_event_source_set_enabled" xmlns:xi="http://www.w3.org/2001/XInclude"> @@ -26,15 +11,6 @@ <refentryinfo> <title>sd_event_source_set_enabled</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> diff --git a/man/sd_event_source_set_prepare.xml b/man/sd_event_source_set_prepare.xml index f0c8e6c42..28bb3e874 100644 --- a/man/sd_event_source_set_prepare.xml +++ b/man/sd_event_source_set_prepare.xml @@ -3,22 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2015 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> <refentry id="sd_event_source_set_prepare" xmlns:xi="http://www.w3.org/2001/XInclude"> @@ -26,15 +11,6 @@ <refentryinfo> <title>sd_event_source_set_prepare</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> diff --git a/man/sd_event_source_set_priority.xml b/man/sd_event_source_set_priority.xml index 3e325502e..faa9325b7 100644 --- a/man/sd_event_source_set_priority.xml +++ b/man/sd_event_source_set_priority.xml @@ -3,22 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2015 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> <refentry id="sd_event_source_set_priority" xmlns:xi="http://www.w3.org/2001/XInclude"> @@ -26,15 +11,6 @@ <refentryinfo> <title>sd_event_source_set_priority</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -119,6 +95,12 @@ particular event sources do not starve or dominate the event loop.</para> + <para>The priority of event sources may be changed at any time of their lifetime, with the exception of inotify + event sources (i.e. those created with + <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>) whose + priority may only be changed in the time between their initial creation and the first subsequent event loop + iteration.</para> + <para><function>sd_event_source_get_priority()</function> may be used to query the current priority assigned to the event source object <parameter>source</parameter>.</para> diff --git a/man/sd_event_source_set_userdata.xml b/man/sd_event_source_set_userdata.xml index 697539662..5d66c0582 100644 --- a/man/sd_event_source_set_userdata.xml +++ b/man/sd_event_source_set_userdata.xml @@ -3,22 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2015 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> <refentry id="sd_event_source_set_userdata" xmlns:xi="http://www.w3.org/2001/XInclude"> @@ -26,15 +11,6 @@ <refentryinfo> <title>sd_event_source_set_userdata</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> diff --git a/man/sd_event_source_unref.xml b/man/sd_event_source_unref.xml index 6bc122e1c..91bae59ab 100644 --- a/man/sd_event_source_unref.xml +++ b/man/sd_event_source_unref.xml @@ -3,22 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2015 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> <refentry id="sd_event_source_unref" xmlns:xi="http://www.w3.org/2001/XInclude"> @@ -26,15 +11,6 @@ <refentryinfo> <title>sd_event_source_unref</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> diff --git a/man/sd_event_wait.xml b/man/sd_event_wait.xml index 5d675ecea..c8721777a 100644 --- a/man/sd_event_wait.xml +++ b/man/sd_event_wait.xml @@ -3,22 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2015 Zbigniew Jędrzejewski-Szmek - - 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> <refentry id="sd_event_wait" xmlns:xi="http://www.w3.org/2001/XInclude"> @@ -26,15 +11,6 @@ <refentryinfo> <title>sd_event_wait</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Tom</firstname> - <surname>Gundersen</surname> - <email>teg@jklm.no</email> - </author> - </authorgroup> </refentryinfo> <refmeta> diff --git a/man/sd_get_seats.xml b/man/sd_get_seats.xml index 95e8b362b..05173b0b7 100644 --- a/man/sd_get_seats.xml +++ b/man/sd_get_seats.xml @@ -3,38 +3,15 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2010 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> -<refentry id="sd_get_seats" conditional='HAVE_PAM'> +<refentry id="sd_get_seats" conditional='HAVE_PAM' + xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_get_seats</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -117,7 +94,6 @@ errno-style error code.</para> </refsect1> - <refsect1> <title>Errors</title> @@ -133,24 +109,17 @@ </variablelist> </refsect1> - <refsect1> - <title>Notes</title> - - <para>The <function>sd_get_seats()</function>, - <function>sd_get_sessions()</function>, - <function>sd_get_uids()</function> and - <function>sd_get_machine_names()</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> + <xi:include href="libelogind-pkgconfig.xml" /> <refsect1> <title>See Also</title> <para> + <!-- 0 /// elogind is in section 8 + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + --><!-- else --> <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <!-- // 0 --> <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_session_get_seat</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> diff --git a/man/sd_id128_get_machine.xml b/man/sd_id128_get_machine.xml index cc1f2b30c..8ed5dfcb1 100644 --- a/man/sd_id128_get_machine.xml +++ b/man/sd_id128_get_machine.xml @@ -3,38 +3,14 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2012 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> -<refentry id="sd_id128_get_machine"> +<refentry id="sd_id128_get_machine" xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_id128_get_machine</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -127,20 +103,14 @@ <refsect1> <title>Return Value</title> - <para>The two calls return 0 on success (in which case - <parameter>ret</parameter> is filled in), or a negative - errno-style error code.</para> + <para>Those calls return 0 on success (in which case <parameter>ret</parameter> is filled in), + or a negative errno-style error code. In particular, <function>sd_id128_get_machine()</function> + and <function>sd_id128_get_machine_app_specific()</function> return <constant>-ENOENT</constant> + if <filename>/etc/machine-id</filename> is missing, and <constant>-ENOMEDIUM</constant> if is + empty or all zeros.</para> </refsect1> - <refsect1> - <title>Notes</title> - - <para>The <function>sd_id128_get_machine()</function>, <function>sd_id128_get_machine_app_specific()</function> - <function>sd_id128_get_boot()</function> and <function>sd_id128_get_invocation()</function> interfaces are - available as a shared library, which can be compiled and linked to with the - <literal>libelogind</literal> <citerefentry - project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para> - </refsect1> + <xi:include href="libelogind-pkgconfig.xml" /> <refsect1> <title>Examples</title> diff --git a/man/sd_id128_randomize.xml b/man/sd_id128_randomize.xml index f99d88e55..e968b199f 100644 --- a/man/sd_id128_randomize.xml +++ b/man/sd_id128_randomize.xml @@ -3,38 +3,14 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2012 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> -<refentry id="sd_id128_randomize"> +<refentry id="sd_id128_randomize" xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_id128_randomize</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -76,8 +52,11 @@ type, see <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> - <para><option>--new-id</option> option may be used as a command line +<!-- 0 /// elogind does not support journalctl + <para><citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s + <option>--new-id128</option> option may be used as a command line front-end for <function>sd_id128_randomize()</function>.</para> +// 0 --> </refsect1> <refsect1> @@ -88,21 +67,17 @@ errno-style error code.</para> </refsect1> - <refsect1> - <title>Notes</title> - - <para>The <function>sd_id128_randomize()</function> interface is - available as a shared library, which can be compiled and linked to - with the - <literal>libelogind</literal> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> - </refsect1> + <xi:include href="libelogind-pkgconfig.xml" /> <refsect1> <title>See Also</title> <para> + <!-- 0 /// elogind is in section 8 + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + --><!-- else --> <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <!-- // 0 --> <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry>, diff --git a/man/sd_id128_to_string.xml b/man/sd_id128_to_string.xml index 11bee6919..02a3758c0 100644 --- a/man/sd_id128_to_string.xml +++ b/man/sd_id128_to_string.xml @@ -3,38 +3,14 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2012 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> -<refentry id="sd_id128_to_string"> +<refentry id="sd_id128_to_string" xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_id128_to_string</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -106,22 +82,17 @@ errno-style error code.</para> </refsect1> - <refsect1> - <title>Notes</title> - - <para>The <function>sd_id128_to_string()</function> and - <function>sd_id128_from_string()</function> interfaces are - available as a shared library, which can be compiled and linked to - with the - <literal>libelogind</literal> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> - </refsect1> + <xi:include href="libelogind-pkgconfig.xml" /> <refsect1> <title>See Also</title> <para> + <!-- 0 /// elogind is in section 8 + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + --><!-- else --> <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <!-- // 0 --> <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> diff --git a/man/sd_is_fifo.xml b/man/sd_is_fifo.xml index 3dac5a900..11021d541 100644 --- a/man/sd_is_fifo.xml +++ b/man/sd_is_fifo.xml @@ -3,22 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2010 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> <refentry id="sd_is_fifo" @@ -27,15 +12,6 @@ <refentryinfo> <title>sd_is_fifo</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -148,7 +124,7 @@ whether the specified file descriptor refers to a special file. If the <parameter>path</parameter> parameter is not <constant>NULL</constant>, it is checked whether the file - descriptor is bound to the specified file name. Special files in + descriptor is bound to the specified filename. Special files in this context are character device nodes and files in <filename>/proc</filename> or <filename>/sys</filename>.</para> </refsect1> diff --git a/man/sd_listen_fds.xml b/man/sd_listen_fds.xml index 0d3479efb..ba03836d0 100644 --- a/man/sd_listen_fds.xml +++ b/man/sd_listen_fds.xml @@ -3,22 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of systemd. - - Copyright 2010 Lennart Poettering - - systemd 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. - - systemd 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 systemd; If not, see <http://www.gnu.org/licenses/>. + SPDX-License-Identifier: LGPL-2.1+ --> <refentry id="sd_listen_fds" @@ -27,15 +12,6 @@ <refentryinfo> <title>sd_listen_fds</title> <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> diff --git a/man/sd_login_monitor_new.xml b/man/sd_login_monitor_new.xml index 0b5b474a5..8f9c218d2 100644 --- a/man/sd_login_monitor_new.xml +++ b/man/sd_login_monitor_new.xml @@ -3,38 +3,15 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2010 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> -<refentry id="sd_login_monitor_new" conditional='HAVE_PAM'> +<refentry id="sd_login_monitor_new" conditional='HAVE_PAM' + xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_login_monitor_new</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -257,20 +234,7 @@ else { </variablelist> </refsect1> - <refsect1> - <title>Notes</title> - - <para>The <function>sd_login_monitor_new()</function>, - <function>sd_login_monitor_unref()</function>, - <function>sd_login_monitor_flush()</function>, - <function>sd_login_monitor_get_fd()</function>, - <function>sd_login_monitor_get_events()</function> and - <function>sd_login_monitor_get_timeout()</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> + <xi:include href="libelogind-pkgconfig.xml" /> <refsect1> <title>See Also</title> diff --git a/man/sd_machine_get_class.xml b/man/sd_machine_get_class.xml index be872eac8..d848686b1 100644 --- a/man/sd_machine_get_class.xml +++ b/man/sd_machine_get_class.xml @@ -3,38 +3,14 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2014 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> -<refentry id="sd_machine_get_class"> +<refentry id="sd_machine_get_class" xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_machine_get_class</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -127,24 +103,19 @@ </variablelist> </refsect1> - <refsect1> - <title>Notes</title> - - <para>The <function>sd_machine_get_class()</function> and - <function>sd_machine_get_ifindices()</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> + <xi:include href="libelogind-pkgconfig.xml" /> <refsect1> <title>See Also</title> <para> + <!-- 0 /// elogind is in section 8 + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + --><!-- else --> <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <!-- // 0 --> <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>elogind-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_pid_get_machine_name</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/sd_notify.xml b/man/sd_notify.xml index a15426c1d..4efb2733c 100644 --- a/man/sd_notify.xml +++ b/man/sd_notify.xml @@ -3,22 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2010 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> <refentry id="sd_notify" @@ -27,15 +12,6 @@ <refentryinfo> <title>sd_notify</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -122,12 +98,10 @@ <varlistentry> <term>READY=1</term> - <listitem><para>Tells the service manager that service startup - is finished. This is only used by elogind if the service - definition file has Type=notify set. Since there is little - value in signaling non-readiness, the only value services - should send is <literal>READY=1</literal> (i.e. - <literal>READY=0</literal> is not defined).</para></listitem> + <listitem><para>Tells the service manager that service startup is finished, or the service finished loading its + configuration. This is only used by elogind if the service definition file has <varname>Type=notify</varname> + set. Since there is little value in signaling non-readiness, the only value services should send is + <literal>READY=1</literal> (i.e. <literal>READY=0</literal> is not defined).</para></listitem> </varlistentry> <varlistentry> @@ -139,7 +113,8 @@ present it to the user. Note that a service that sends this notification must also send a <literal>READY=1</literal> notification when it completed reloading its - configuration.</para></listitem> + configuration. Reloads are propagated in the same way as they + are when initiated by the user.</para></listitem> </varlistentry> <varlistentry> @@ -201,6 +176,26 @@ watchdog is enabled. </para></listitem> </varlistentry> + <varlistentry> + <term>WATCHDOG_USEC=…</term> + + <listitem><para>Reset <varname>watchdog_usec</varname> value during runtime. + Notice that this is not available when using <function>sd_event_set_watchdog()</function> + or <function>sd_watchdog_enabled()</function>. + Example : <literal>WATCHDOG_USEC=20000000</literal></para></listitem> + </varlistentry> + + <varlistentry> + <term>EXTEND_TIMEOUT_USEC=…</term> + + <listitem><para>Tells the service manager to extend the startup, runtime or shutdown service timeout + corresponding the current state. The value specified is a time in microseconds during which the service must + send a new message. A service timeout will occur if the message isn't received, but only if the runtime of the + current state is beyond the original maximium times of <varname>TimeoutStartSec=</varname>, <varname>RuntimeMaxSec=</varname>, + and <varname>TimeoutStopSec=</varname>. + See <citerefentry><refentrytitle>elogind.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for effects on the service timeouts.</para></listitem> + </varlistentry> <varlistentry> <term>FDSTORE=1</term> @@ -227,33 +222,25 @@ </varlistentry> <varlistentry> - <term>FDNAME=…</term> + <term>FDSTOREREMOVE=1</term> - <listitem><para>When used in combination with - <varname>FDSTORE=1</varname>, specifies a name for the - submitted file descriptors. This name is passed to the service - during activation, and may be queried using - <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>. File - descriptors submitted without this field set, will implicitly - get the name <literal>stored</literal> assigned. Note that, if - multiple file descriptors are submitted at once, the specified - name will be assigned to all of them. In order to assign - different names to submitted file descriptors, submit them in - separate invocations of - <function>sd_pid_notify_with_fds()</function>. The name may - consist of any ASCII character, but must not contain control - characters or <literal>:</literal>. It may not be longer than - 255 characters. If a submitted name does not follow these - restrictions, it is ignored.</para></listitem> + <listitem><para>Removes file descriptors from the file descriptor store. This field needs to be combined with + <varname>FDNAME=</varname> to specify the name of the file descriptors to remove.</para></listitem> </varlistentry> <varlistentry> - <term>WATCHDOG_USEC=…</term> + <term>FDNAME=…</term> - <listitem><para>Reset <varname>watchdog_usec</varname> value during runtime. - Notice that this is not available when using <function>sd_event_set_watchdog()</function> - or <function>sd_watchdog_enabled()</function>. - Example : <literal>WATCHDOG_USEC=20000000</literal></para></listitem> + <listitem><para>When used in combination with <varname>FDSTORE=1</varname>, specifies a name for the submitted + file descriptors. When used with <varname>FDSTOREREMOVE=1</varname>, specifies the name for the file + descriptors to remove. This name is passed to the service during activation, and may be queried using + <citerefentry><refentrytitle>sd_listen_fds_with_names</refentrytitle><manvolnum>3</manvolnum></citerefentry>. File + descriptors submitted without this field set, will implicitly get the name <literal>stored</literal> + assigned. Note that, if multiple file descriptors are submitted at once, the specified name will be assigned to + all of them. In order to assign different names to submitted file descriptors, submit them in separate + invocations of <function>sd_pid_notify_with_fds()</function>. The name may consist of arbitrary ASCII + characters except control characters or <literal>:</literal>. It may not be longer than 255 characters. If a + submitted name does not follow these restrictions, it is ignored.</para></listitem> </varlistentry> </variablelist> diff --git a/man/sd_pid_get_session.xml b/man/sd_pid_get_owner_uid.xml index f85b413f0..573e3fece 100644 --- a/man/sd_pid_get_session.xml +++ b/man/sd_pid_get_owner_uid.xml @@ -3,57 +3,38 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2010 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> -<refentry id="sd_pid_get_session" conditional='HAVE_PAM'> +<refentry id="sd_pid_get_owner_uid" conditional='HAVE_PAM' + xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> - <title>sd_pid_get_session</title> + <title>sd_pid_get_owner_uid</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_pid_get_session</refentrytitle> + <refentrytitle>sd_pid_get_owner_uid</refentrytitle> <manvolnum>3</manvolnum> </refmeta> <refnamediv> - <refname>sd_pid_get_session</refname> <refname>sd_pid_get_owner_uid</refname> + <refname>sd_pid_get_session</refname> + <refname>sd_pid_get_user_unit</refname> + <refname>sd_pid_get_unit</refname> <refname>sd_pid_get_machine_name</refname> <refname>sd_pid_get_cgroup</refname> - <refname>sd_peer_get_session</refname> <refname>sd_peer_get_owner_uid</refname> + <refname>sd_peer_get_session</refname> + <refname>sd_peer_get_user_unit</refname> + <refname>sd_peer_get_unit</refname> <refname>sd_peer_get_machine_name</refname> <refname>sd_peer_get_cgroup</refname> - <refpurpose>Determine session, unit, owner of a session, - container/VM or slice of a specific PID or socket - peer</refpurpose> + <refpurpose>Determine the owner uid of the user unit or session, + or the session, user unit, system unit, container/VM or slice that + a specific PID or socket peer belongs to.</refpurpose> </refnamediv> <refsynopsisdiv> @@ -61,15 +42,27 @@ <funcsynopsisinfo>#include <elogind/sd-login.h></funcsynopsisinfo> <funcprototype> + <funcdef>int <function>sd_pid_get_owner_uid</function></funcdef> + <paramdef>pid_t <parameter>pid</parameter></paramdef> + <paramdef>uid_t *<parameter>uid</parameter></paramdef> + </funcprototype> + + <funcprototype> <funcdef>int <function>sd_pid_get_session</function></funcdef> <paramdef>pid_t <parameter>pid</parameter></paramdef> <paramdef>char **<parameter>session</parameter></paramdef> </funcprototype> <funcprototype> - <funcdef>int <function>sd_pid_get_owner_uid</function></funcdef> + <funcdef>int <function>sd_pid_get_user_unit</function></funcdef> <paramdef>pid_t <parameter>pid</parameter></paramdef> - <paramdef>uid_t *<parameter>uid</parameter></paramdef> + <paramdef>char **<parameter>unit</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_pid_get_unit</function></funcdef> + <paramdef>pid_t <parameter>pid</parameter></paramdef> + <paramdef>char **<parameter>unit</parameter></paramdef> </funcprototype> <funcprototype> @@ -85,15 +78,27 @@ </funcprototype> <funcprototype> + <funcdef>int <function>sd_peer_get_owner_uid</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>uid_t *<parameter>uid</parameter></paramdef> + </funcprototype> + + <funcprototype> <funcdef>int <function>sd_peer_get_session</function></funcdef> <paramdef>int <parameter>fd</parameter></paramdef> <paramdef>char **<parameter>session</parameter></paramdef> </funcprototype> <funcprototype> - <funcdef>int <function>sd_peer_get_owner_uid</function></funcdef> + <funcdef>int <function>sd_peer_get_user_unit</function></funcdef> <paramdef>int <parameter>fd</parameter></paramdef> - <paramdef>uid_t *<parameter>uid</parameter></paramdef> + <paramdef>char **<parameter>unit</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_peer_get_unit</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>char **<parameter>unit</parameter></paramdef> </funcprototype> <funcprototype> @@ -113,27 +118,48 @@ <refsect1> <title>Description</title> + <para><function>sd_pid_get_owner_uid()</function> may be used to + determine the Unix UID (user identifier) which owns the login + session or systemd user unit of a process identified by the + specified PID. For processes which are not part of a login session + and not managed by a user manager, this function will fail with + <constant>-ENODATA</constant>.</para> + <para><function>sd_pid_get_session()</function> may be used to determine the login session identifier of a process identified by the specified process identifier. The session identifier is a - short string, suitable for usage in file system paths. Note that - not all processes are part of a login session (e.g. system service - processes, user processes that are shared between multiple - sessions of the same user, or kernel threads). For processes not - being part of a login session, this function will fail with - -ENODATA. The returned string needs to be freed with the libc - <citerefentry + short string, suitable for usage in file system paths. Please + note the login session may be limited to a stub process or two. + User processes may instead be started from their systemd user + manager, e.g. GUI applications started using DBus activation, as + well as service processes which are shared between multiple logins + of the same user. For processes which are not part of a login + session, this function will fail with <constant>-ENODATA</constant>. + The returned string needs to be freed with the libc <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> call after use.</para> - <para><function>sd_pid_get_owner_uid()</function> may be used to - determine the Unix UID (user identifier) of the owner of the - session of a process identified the specified PID. Note that this - function will succeed for user processes which are shared between - multiple login sessions of the same user, whereas - <function>sd_pid_get_session()</function> will fail. For processes - not being part of a login session and not being a shared process - of a user, this function will fail with -ENODATA.</para> + <para><function>sd_pid_get_user_unit()</function> may be used to + determine the systemd user unit (i.e. user service or scope unit) + identifier of a process identified by the specified PID. The + unit name is a short string, suitable for usage in file system + paths. For processes which are not managed by a user manager, this + function will fail with <constant>-ENODATA</constant>. The + returned string needs to be freed with the libc <citerefentry + project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use.</para> + + <para><function>sd_pid_get_unit()</function> may be used to + determine the systemd system unit (i.e. system service or scope + unit) identifier of a process identified by the specified PID. The + unit name is a short string, suitable for usage in file system + paths. Note that not all processes are part of a system + unit/service. For processes not being part of a systemd system + unit, this function will fail with <constant>-ENODATA</constant>. + (More specifically, this call will not work for kernel threads.) + The returned string needs to be freed with the libc <citerefentry + project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use.</para> <para><function>sd_pid_get_machine_name()</function> may be used to determine the name of the VM or container is a member of. The @@ -141,8 +167,20 @@ paths. The returned string needs to be freed with the libc <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use. For processes not part of a VM or containers, this - function fails with -ENODATA.</para> + call after use. For processes not part of a VM or container, this + function fails with <constant>-ENODATA</constant>.</para> + + <para><function>sd_pid_get_slice()</function> may be used to + determine the slice unit the process is a member of. See + <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details about slices. The returned string needs to be freed + with the libc + <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use.</para> + + <para>Similarly, <function>sd_pid_get_user_slice()</function> + returns the user slice (as managed by the user's systemd instance) + of a process.</para> <para><function>sd_pid_get_cgroup()</function> returns the control group path of the specified process, relative to the root of the @@ -159,9 +197,13 @@ functions is passed as 0, the operation is executed for the calling process.</para> - <para>The <function>sd_peer_get_session()</function>, - <function>sd_peer_get_owner_uid()</function>, - <function>sd_peer_get_machine_name()</function> and + <para>The <function>sd_peer_get_owner_uid()</function>, + <function>sd_peer_get_session()</function>, + <function>sd_peer_get_user_unit()</function>, + <function>sd_peer_get_unit()</function>, + <function>sd_peer_get_machine_name()</function>, + <function>sd_peer_get_slice()</function>, + <function>sd_peer_get_user_slice()</function> and <function>sd_peer_get_cgroup()</function> calls operate similar to their PID counterparts, but operate on a connected AF_UNIX socket and retrieve information about the connected peer process. Note @@ -226,16 +268,7 @@ <refsect1> <title>Notes</title> - <para>The <function>sd_pid_get_session()</function>, - <function>sd_pid_get_owner_uid()</function>, - <function>sd_pid_get_machine_name()</function>, - <function>sd_peer_get_session()</function>, - <function>sd_peer_get_owner_uid()</function>, - <function>sd_peer_get_machine_name()</function>, - 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> + <xi:include href="libelogind-pkgconfig.xml" xpointer="pkgconfig-text"/> <para>Note that the login session identifier as returned by <function>sd_pid_get_session()</function> diff --git a/man/sd_seat_get_active.xml b/man/sd_seat_get_active.xml index 33a8697ff..fb0ed5527 100644 --- a/man/sd_seat_get_active.xml +++ b/man/sd_seat_get_active.xml @@ -3,38 +3,15 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2010 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> -<refentry id="sd_seat_get_active" conditional='HAVE_PAM'> +<refentry id="sd_seat_get_active" conditional='HAVE_PAM' + xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_seat_get_active</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -186,25 +163,17 @@ </variablelist> </refsect1> - <refsect1> - <title>Notes</title> - - <para>The <function>sd_seat_get_active()</function>, - <function>sd_seat_get_sessions()</function>, - <function>sd_seat_can_multi_session()</function>, - <function>sd_seat_can_tty()</function> and - <function>sd_seat_can_graphical()</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> + <xi:include href="libelogind-pkgconfig.xml" /> <refsect1> <title>See Also</title> <para> + <!-- 0 /// elogind is in section 8 + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + --><!-- else --> <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <!-- // 0 --> <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_session_get_seat</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> diff --git a/man/sd_session_is_active.xml b/man/sd_session_is_active.xml index d457010b8..22b869729 100644 --- a/man/sd_session_is_active.xml +++ b/man/sd_session_is_active.xml @@ -3,38 +3,15 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2010 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> -<refentry id="sd_session_is_active" conditional='HAVE_PAM'> +<refentry id="sd_session_is_active" conditional='HAVE_PAM' + xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_session_is_active</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -327,31 +304,17 @@ </variablelist> </refsect1> - <refsect1> - <title>Notes</title> - - <para>The <function>sd_session_is_active()</function>, - <function>sd_session_get_state()</function>, - <function>sd_session_get_uid()</function>, - <function>sd_session_get_seat()</function>, - <function>sd_session_get_service()</function>, - <function>sd_session_get_type()</function>, - <function>sd_session_get_class()</function>, - <function>sd_session_get_display()</function>, - <function>sd_session_get_remote_host()</function>, - <function>sd_session_get_remote_user()</function> and - <function>sd_session_get_tty()</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> + <xi:include href="libelogind-pkgconfig.xml" /> <refsect1> <title>See Also</title> <para> + <!-- 0 /// elogind is in section 8 + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + --><!-- else --> <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <!-- // 0 --> <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_pid_get_session</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> diff --git a/man/sd_uid_get_state.xml b/man/sd_uid_get_state.xml index 20aa92b96..ae670ff57 100644 --- a/man/sd_uid_get_state.xml +++ b/man/sd_uid_get_state.xml @@ -3,38 +3,15 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2010 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> -<refentry id="sd_uid_get_state" conditional='HAVE_PAM'> +<refentry id="sd_uid_get_state" conditional='HAVE_PAM' + xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_uid_get_state</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> @@ -208,14 +185,7 @@ </variablelist> </refsect1> - <refsect1> - <title>Notes</title> - - <para>Functions described here are available as a shared library, - and can be compiled and linked to using the - <constant>libelogind</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - entry.</para> - </refsect1> + <xi:include href="libelogind-pkgconfig.xml" /> <refsect1> <title>History</title> diff --git a/man/sd_watchdog_enabled.xml b/man/sd_watchdog_enabled.xml index 9ba70dd5c..b3c67d83d 100644 --- a/man/sd_watchdog_enabled.xml +++ b/man/sd_watchdog_enabled.xml @@ -3,22 +3,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of elogind. - - Copyright 2013 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/>. + SPDX-License-Identifier: LGPL-2.1+ --> <refentry id="sd_watchdog_enabled" @@ -27,15 +12,6 @@ <refentryinfo> <title>sd_watchdog_enabled</title> <productname>elogind</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> </refentryinfo> <refmeta> diff --git a/man/standard-conf.xml b/man/standard-conf.xml deleted file mode 100644 index 807702493..000000000 --- a/man/standard-conf.xml +++ /dev/null @@ -1,73 +0,0 @@ -<?xml version="1.0"?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> -<!DOCTYPE refsection PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" - "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> - -<refsection> - <refsection id='confd'> - <title>Configuration Directories and Precedence</title> - - <para>Configuration files are read from directories in - <filename>/etc/</filename>, <filename>/run/</filename>, and - <filename>/usr/lib/</filename>, in order of precedence. - Each configuration file in these configuration directories shall be named in - the style of <filename><replaceable>filename</replaceable>.conf</filename>. - Files in <filename>/etc/</filename> override files with the same name in - <filename>/run/</filename> and <filename>/usr/lib/</filename>. Files in - <filename>/run/</filename> override files with the same name in - <filename>/usr/lib/</filename>.</para> - - <para>Packages should install their configuration files in - <filename>/usr/lib/</filename>. Files in <filename>/etc/</filename> are - reserved for the local administrator, who may use this logic to override the - configuration files installed by vendor packages. All configuration files - are sorted by their filename in lexicographic order, regardless of which of - the directories they reside in. If multiple files specify the same option, - the entry in the file with the lexicographically latest name will take - precedence. It is recommended to prefix all filenames with a two-digit number - and a dash, to simplify the ordering of the files.</para> - - <para>If the administrator wants to disable a configuration file supplied by - the vendor, the recommended way is to place a symlink to - <filename>/dev/null</filename> in the configuration directory in - <filename>/etc/</filename>, with the same filename as the vendor - configuration file. If the vendor configuration file is included in - the initrd image, the image has to be regenerated.</para> - - </refsection> - - <refsection id='main-conf'> - <title>Configuration Directories and Precedence</title> - - <para>The default configuration is defined during compilation, so a - configuration file is only needed when it is necessary to deviate - from those defaults. By default, the configuration file in - <filename>/etc/elogind/</filename> contains commented out entries - showing the defaults as a guide to the administrator. This file - can be edited to create local overrides. - </para> - - <para>When packages need to customize the configuration, they can - install configuration snippets in - <filename>/usr/lib/elogind/*.conf.d/</filename>. Files in - <filename>/etc/</filename> are reserved for the local - administrator, who may use this logic to override the - configuration files installed by vendor packages. The main - configuration file is read before any of the configuration - directories, and has the lowest precedence; entries in a file in - any configuration directory override entries in the single - configuration file. Files in the - <filename>*.conf.d/</filename> configuration subdirectories - are sorted by their filename in lexicographic order, regardless of - which of the subdirectories they reside in. If multiple files - specify the same option, the entry in the file with the - lexicographically latest name takes precedence. It is recommended - to prefix all filenames in those subdirectories with a two-digit - number and a dash, to simplify the ordering of the files.</para> - - <para>To disable a configuration file supplied by the vendor, the - recommended way is to place a symlink to - <filename>/dev/null</filename> in the configuration directory in - <filename>/etc/</filename>, with the same filename as the vendor - configuration file.</para> - </refsection> -</refsection> diff --git a/man/standard-options.xml b/man/standard-options.xml index f718451a1..bea92e89f 100644 --- a/man/standard-options.xml +++ b/man/standard-options.xml @@ -2,6 +2,10 @@ <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<!-- + SPDX-License-Identifier: LGPL-2.1+ +--> + <variablelist> <varlistentry id='help'> <term><option>-h</option></term> @@ -42,4 +46,13 @@ footer with hints.</para> </listitem> </varlistentry> + + <varlistentry id='cat-config'> + <term><option>--cat-config</option></term> + + <listitem> + <para>Copy the contents of config files to standard output. + Before each file, the filename is printed as a comment.</para> + </listitem> + </varlistentry> </variablelist> diff --git a/man/user-system-options.xml b/man/user-system-options.xml index 8616c5424..a2624787a 100644 --- a/man/user-system-options.xml +++ b/man/user-system-options.xml @@ -2,9 +2,14 @@ <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<!-- + SPDX-License-Identifier: LGPL-2.1+ +--> + <variablelist> + <!-- 0 /// With elogind there is no calling user systemd instance. <varlistentry id='user'> - <term><option>--user</option></term> + <term><option>--user</option></term> <listitem id='user-text'> <para>Talk to the service manager of the calling user, @@ -13,13 +18,14 @@ </varlistentry> <varlistentry id='system'> - <term><option>--system</option></term> + <term><option>--system</option></term> <listitem id='system-text'> <para>Talk to the service manager of the system. This is the implied default.</para> </listitem> </varlistentry> + // 0 --> <varlistentry id='host'> <term><option>-H</option></term> |