diff options
| author | Sven Eden <yamakuzure@gmx.net> | 2016-12-30 15:43:50 +0100 |
|---|---|---|
| committer | Sven Eden <yamakuzure@gmx.net> | 2017-03-14 10:18:27 +0100 |
| commit | 1532f28b7cf3e6e02e74691450b2b5379be6b805 (patch) | |
| tree | 184d2f253b46da8658037e51c1670122983a32c8 /man | |
| parent | 37570c53dc8865f07ae8ff5a9915d7ed797b951f (diff) | |
Prep v222: Update build system:
- The content of the man pages directory has been overhauled
- Makefile-man.am was regenerated
- Makefile.am and configure.ac needed a few addtitions and fixes
- Some masked functions had to be unmasked
- Now superfluous files have been removed
Diffstat (limited to 'man')
| -rw-r--r-- | man/Makefile | 28 | ||||
| -rw-r--r-- | man/custom-html.xsl | 22 | ||||
| -rw-r--r-- | man/custom-man.xsl | 8 | ||||
| -rw-r--r-- | man/elogind.conf.xml | 58 | ||||
| -rw-r--r-- | man/loginctl.xml | 19 | ||||
| -rw-r--r-- | man/pam_elogind.xml | 14 | ||||
| -rw-r--r-- | man/sd-login.xml | 135 | ||||
| -rw-r--r-- | man/sd_get_seats.xml | 14 | ||||
| -rw-r--r-- | man/sd_id128_get_machine.xml | 129 | ||||
| -rw-r--r-- | man/sd_id128_randomize.xml | 114 | ||||
| -rw-r--r-- | man/sd_id128_to_string.xml | 132 | ||||
| -rw-r--r-- | man/sd_is_fifo.xml | 20 | ||||
| -rw-r--r-- | man/sd_login_monitor_new.xml | 233 | ||||
| -rw-r--r-- | man/sd_machine_get_class.xml | 123 | ||||
| -rw-r--r-- | man/sd_notify.xml | 376 | ||||
| -rw-r--r-- | man/sd_seat_get_active.xml | 14 | ||||
| -rw-r--r-- | man/sd_session_is_active.xml | 14 | ||||
| -rw-r--r-- | man/sd_uid_get_state.xml | 204 | ||||
| -rw-r--r-- | man/sd_watchdog_enabled.xml | 175 |
19 files changed, 1203 insertions, 629 deletions
diff --git a/man/Makefile b/man/Makefile new file mode 100644 index 000000000..9d0750519 --- /dev/null +++ b/man/Makefile @@ -0,0 +1,28 @@ +# 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/>. + +# This file is a dirty trick to simplify compilation from within +# emacs. This file is not intended to be distributed. So, don't touch +# it, even better ignore it! + +all: + $(MAKE) -C .. + +clean: + $(MAKE) -C .. clean + +.PHONY: all clean diff --git a/man/custom-html.xsl b/man/custom-html.xsl index 99acc4341..27714633e 100644 --- a/man/custom-html.xsl +++ b/man/custom-html.xsl @@ -1,22 +1,22 @@ <?xml version='1.0'?> <!--*-nxml-*--> <!-- - This file is part of systemd. + This file is part of elogind. Copyright 2011 Lennart Poettering - systemd is free software; you can redistribute it and/or modify it + 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. - systemd is distributed in the hope that it will be useful, but + 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 systemd; If not, see <http://www.gnu.org/licenses/>. + 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"> @@ -271,10 +271,22 @@ <xsl:text>index.html</xsl:text> </xsl:attribute> <xsl:text>Index </xsl:text> + </a>· + <a> + <xsl:attribute name="href"> + <xsl:text>elogind.directives.html</xsl:text> + </xsl:attribute> + <xsl:text>Directives </xsl:text> + </a>· + <a> + <xsl:attribute name="href"> + <xsl:text>../python-elogind/index.html</xsl:text> + </xsl:attribute> + <xsl:text>Python </xsl:text> </a> <span style="float:right"> - <xsl:text>elogind</xsl:text> + <xsl:text>elogind </xsl:text> <xsl:value-of select="$elogind.version"/> </span> <hr/> diff --git a/man/custom-man.xsl b/man/custom-man.xsl index bb82f5911..853e214d1 100644 --- a/man/custom-man.xsl +++ b/man/custom-man.xsl @@ -1,22 +1,22 @@ <?xml version='1.0'?> <!--*-nxml-*--> <!-- - This file is part of systemd. + This file is part of elogind. Copyright 2013 Zbigniew Jędrzejewski-Szmek - systemd is free software; you can redistribute it and/or modify it + 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. - systemd is distributed in the hope that it will be useful, but + 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 systemd; If not, see <http://www.gnu.org/licenses/>. + along with elogind; If not, see <http://www.gnu.org/licenses/>. --> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" diff --git a/man/elogind.conf.xml b/man/elogind.conf.xml index b6392a693..268e6d822 100644 --- a/man/elogind.conf.xml +++ b/man/elogind.conf.xml @@ -3,25 +3,26 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of systemd. + This file is part of elogind. Copyright 2010 Lennart Poettering - systemd is free software; you can redistribute it and/or modify it + 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. - systemd is distributed in the hope that it will be useful, but + 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 systemd; If not, see <http://www.gnu.org/licenses/>. + along with elogind; If not, see <http://www.gnu.org/licenses/>. --> -<refentry id="elogind.conf" xmlns:xi="http://www.w3.org/2001/XInclude"> +<refentry id="elogind.conf" conditional='ENABLE_LOGIND' + xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>elogind.conf</title> <productname>elogind</productname> @@ -43,7 +44,6 @@ <refnamediv> <refname>elogind.conf</refname> - <refname>elogind.conf.d</refname> <refpurpose>Login manager configuration files</refpurpose> </refnamediv> @@ -56,6 +56,7 @@ <para>These files configure various parameters of the elogind login manager, + <citerefentry><refentrytitle>elogind-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. </para> </refsect1> @@ -70,6 +71,48 @@ <variablelist> <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> + + <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> + + <varlistentry> <term><varname>KillUserProcesses=</varname></term> <listitem><para>Takes a boolean argument. Configures whether @@ -253,7 +296,10 @@ <refsect1> <title>See Also</title> <para> + <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/loginctl.xml b/man/loginctl.xml index 1c2d9132e..54a9a73d7 100644 --- a/man/loginctl.xml +++ b/man/loginctl.xml @@ -3,25 +3,26 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of systemd. + This file is part of elogind. Copyright 2010 Lennart Poettering - systemd is free software; you can redistribute it and/or modify it + 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. - systemd is distributed in the hope that it will be useful, but + 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 systemd; If not, see <http://www.gnu.org/licenses/>. + along with elogind; If not, see <http://www.gnu.org/licenses/>. --> -<refentry id="loginctl" xmlns:xi="http://www.w3.org/2001/XInclude"> +<refentry id="loginctl" conditional='ENABLE_LOGIND' + xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>loginctl</title> @@ -60,7 +61,10 @@ <title>Description</title> <para><command>loginctl</command> may be used to introspect and - control the state of the elogind login manager</para> + control the state of the + <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry> + login manager + <citerefentry><refentrytitle>elogind-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> </refsect1> <refsect1> @@ -401,6 +405,9 @@ <refsect1> <title>See Also</title> <para> + <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>elogind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/pam_elogind.xml b/man/pam_elogind.xml index 927ad1f08..700f0cc88 100644 --- a/man/pam_elogind.xml +++ b/man/pam_elogind.xml @@ -3,22 +3,22 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of systemd. + This file is part of elogind. Copyright 2010 Lennart Poettering - systemd is free software; you can redistribute it and/or modify it + 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. - systemd is distributed in the hope that it will be useful, but + 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 systemd; If not, see <http://www.gnu.org/licenses/>. + along with elogind; If not, see <http://www.gnu.org/licenses/>. --> <refentry id="pam_elogind" conditional='HAVE_PAM'> @@ -56,7 +56,7 @@ <para><command>pam_elogind</command> registers user sessions with the elogind login manager - <citerefentry><refentrytitle>logind</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, and hence the elogind control group hierarchy.</para> <para>On login, this module ensures the following:</para> @@ -280,12 +280,16 @@ session required pam_elogind.so</programlisting> <title>See Also</title> <para> <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>elogind.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>pam.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry project='man-pages'><refentrytitle>pam_loginuid</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind.scope</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/sd-login.xml b/man/sd-login.xml deleted file mode 100644 index 06ffc6906..000000000 --- a/man/sd-login.xml +++ /dev/null @@ -1,135 +0,0 @@ -<?xml version='1.0'?> <!--*-nxml-*--> -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - -<!-- - This file is part of 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/>. ---> - -<refentry id="sd-login" conditional='HAVE_PAM' - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>sd-login</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </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>See <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/multiseat">Multi-Seat - on Linux</ulink> for an introduction into multi-seat support on - Linux, the background for this set of APIs.</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 - 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 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> - - <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> - </refsect1> - -</refentry> diff --git a/man/sd_get_seats.xml b/man/sd_get_seats.xml index c6b133e66..5a456a5f4 100644 --- a/man/sd_get_seats.xml +++ b/man/sd_get_seats.xml @@ -3,29 +3,29 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of systemd. + This file is part of elogind. Copyright 2010 Lennart Poettering - systemd is free software; you can redistribute it and/or modify it + 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. - systemd is distributed in the hope that it will be useful, but + 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 systemd; If not, see <http://www.gnu.org/licenses/>. + along with elogind; If not, see <http://www.gnu.org/licenses/>. --> <refentry id="sd_get_seats" conditional='HAVE_PAM'> <refentryinfo> <title>sd_get_seats</title> - <productname>systemd</productname> + <productname>elogind</productname> <authorgroup> <author> @@ -52,7 +52,7 @@ <refsynopsisdiv> <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo> + <funcsynopsisinfo>#include <elogind/sd-login.h></funcsynopsisinfo> <funcprototype> <funcdef>int <function>sd_get_seats</function></funcdef> @@ -132,7 +132,7 @@ <title>See Also</title> <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <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 new file mode 100644 index 000000000..a3fcfb552 --- /dev/null +++ b/man/sd_id128_get_machine.xml @@ -0,0 +1,129 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of elogind. + + Copyright 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/>. +--> + +<refentry id="sd_id128_get_machine"> + + <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> + <refentrytitle>sd_id128_get_machine</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_id128_get_machine</refname> + <refname>sd_id128_get_boot</refname> + <refpurpose>Retrieve 128-bit IDs</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <elogind/sd-id128.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_id128_get_machine</function></funcdef> + <paramdef>sd_id128_t *<parameter>ret</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_id128_get_boot</function></funcdef> + <paramdef>sd_id128_t *<parameter>ret</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_id128_get_machine()</function> returns the + machine ID of the executing host. This reads and parses the + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> + file. This function caches the machine ID internally to make + retrieving the machine ID a cheap operation.</para> + + <para><function>sd_id128_get_boot()</function> returns the boot ID + of the executing kernel. This reads and parses the + <filename>/proc/sys/kernel/random/boot_id</filename> file exposed + by the kernel. It is randomly generated early at boot and is + unique for every running kernel instance. See + <citerefentry project='man-pages'><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> + for more information. This function also internally caches the + returned ID to make this call a cheap operation.</para> + + <para>Note that <function>sd_id128_get_boot()</function> always + returns a UUID v4 compatible ID. + <function>sd_id128_get_machine()</function> will also return a + UUID v4-compatible ID on new installations but might not on older. + It is possible to convert the machine ID into a UUID v4-compatible + one. For more information, see + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + + <para>For more information about the <literal>sd_id128_t</literal> + type see + <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + </refsect1> + + <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> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para>The <function>sd_id128_get_machine()</function> and + <function>sd_id128_get_boot()</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> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <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>, + <citerefentry><refentrytitle>sd_id128_randomize</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_id128_randomize.xml b/man/sd_id128_randomize.xml new file mode 100644 index 000000000..a5daae2bd --- /dev/null +++ b/man/sd_id128_randomize.xml @@ -0,0 +1,114 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of elogind. + + Copyright 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/>. +--> + +<refentry id="sd_id128_randomize"> + + <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> + <refentrytitle>sd_id128_randomize</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_id128_randomize</refname> + <refpurpose>Generate 128-bit IDs</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <elogind/sd-id128.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_id128_randomize</function></funcdef> + <paramdef>sd_id128_t *<parameter>ret</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_id128_randomize()</function> generates a new + randomized 128-bit ID and returns it in + <parameter>ret</parameter>. Every invocation returns a new + randomly generated ID. This uses the + <filename>/dev/urandom</filename> kernel random number + generator.</para> + + <para>Note that <function>sd_id128_randomize()</function> always + returns a UUID v4-compatible ID.</para> + + <para>For more information about the <literal>sd_id128_t</literal> + type, see + <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + + <para><citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s + <option>--new-id</option> option may be used as a command line + front-end for <function>sd_id128_randomize()</function>.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>The call returns 0 on success (in which case + <parameter>ret</parameter> is filled in), or a negative + 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> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <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>, + <citerefentry><refentrytitle>sd_id128_get_machine</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_id128_to_string.xml b/man/sd_id128_to_string.xml new file mode 100644 index 000000000..afbf82c37 --- /dev/null +++ b/man/sd_id128_to_string.xml @@ -0,0 +1,132 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of elogind. + + Copyright 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/>. +--> + +<refentry id="sd_id128_to_string"> + + <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> + <refentrytitle>sd_id128_to_string</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_id128_to_string</refname> + <refname>sd_id128_from_string</refname> + <refpurpose>Format or parse 128-bit IDs as strings</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <elogind/sd-id128.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>char *<function>sd_id128_to_string</function></funcdef> + <paramdef>sd_id128_t <parameter>id</parameter>, char <parameter>s</parameter>[33]</paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_id128_from_string</function></funcdef> + <paramdef>const char *<parameter>s</parameter>, sd_id128_t *<parameter>ret</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_id128_to_string()</function> formats a 128-bit + ID as a character string. It expects the ID and a string array + capable of storing 33 characters. The ID will be formatted as 32 + lowercase hexadecimal digits and be terminated by a + <constant>NUL</constant> byte.</para> + + <para><function>sd_id128_from_string()</function> implements the + reverse operation: it takes a 33 character string with 32 + hexadecimal digits (either lowercase or uppercase, terminated by + <constant>NUL</constant>) and parses them back into a 128-bit ID + returned in <parameter>ret</parameter>. Alternatively, this call + can also parse a 37-character string with a 128-bit ID formatted + as RFC UUID.</para> + + <para>For more information about the <literal>sd_id128_t</literal> + type see + <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + Note that these calls operate the same way on all architectures, + i.e. the results do not depend on endianness.</para> + + <para>When formatting a 128-bit ID into a string, it is often + easier to use a format string for + <citerefentry project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + This is easily done using the + <function>SD_ID128_FORMAT_STR</function> and + <function>SD_ID128_FORMAT_VAL()</function> macros. For more + information see + <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para><function>sd_id128_to_string()</function> always succeeds + and returns a pointer to the string array passed in. + <function>sd_id128_from_string</function> returns 0 on success, in + which case <parameter>ret</parameter> is filled in, or a negative + 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> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_is_fifo.xml b/man/sd_is_fifo.xml index 627cb87aa..64f23cb6f 100644 --- a/man/sd_is_fifo.xml +++ b/man/sd_is_fifo.xml @@ -3,22 +3,22 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of systemd. + This file is part of elogind. Copyright 2010 Lennart Poettering - systemd is free software; you can redistribute it and/or modify it + 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. - systemd is distributed in the hope that it will be useful, but + 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 systemd; If not, see <http://www.gnu.org/licenses/>. + along with elogind; If not, see <http://www.gnu.org/licenses/>. --> <refentry id="sd_is_fifo" @@ -26,7 +26,7 @@ <refentryinfo> <title>sd_is_fifo</title> - <productname>systemd</productname> + <productname>elogind</productname> <authorgroup> <author> @@ -55,7 +55,7 @@ <refsynopsisdiv> <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo> + <funcsynopsisinfo>#include <elogind/sd-daemon.h></funcsynopsisinfo> <funcprototype> <funcdef>int <function>sd_is_fifo</function></funcdef> @@ -178,7 +178,7 @@ <refsect1> <title>Notes</title> - <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> + <xi:include href="libelogind-pkgconfig.xml" xpointer="pkgconfig-text"/> <para>Internally, these function use a combination of <filename>fstat()</filename> and @@ -189,11 +189,11 @@ <refsect1> <title>See Also</title> <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> + <citerefentry><refentrytitle>elogind.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry> </para> </refsect1> diff --git a/man/sd_login_monitor_new.xml b/man/sd_login_monitor_new.xml deleted file mode 100644 index 7319c061c..000000000 --- a/man/sd_login_monitor_new.xml +++ /dev/null @@ -1,233 +0,0 @@ -<?xml version='1.0'?> <!--*-nxml-*--> -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - -<!-- - This file is part of 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/>. ---> - -<refentry id="sd_login_monitor_new" conditional='HAVE_PAM'> - - <refentryinfo> - <title>sd_login_monitor_new</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_login_monitor_new</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_login_monitor_new</refname> - <refname>sd_login_monitor_unref</refname> - <refname>sd_login_monitor_flush</refname> - <refname>sd_login_monitor_get_fd</refname> - <refname>sd_login_monitor_get_events</refname> - <refname>sd_login_monitor_get_timeout</refname> - <refname>sd_login_monitor</refname> - <refpurpose>Monitor login sessions, seats, users and virtual machines/containers</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_login_monitor_new</function></funcdef> - <paramdef>const char *<parameter>category</parameter></paramdef> - <paramdef>sd_login_monitor **<parameter>ret</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>sd_login_monitor *<function>sd_login_monitor_unref</function></funcdef> - <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_login_monitor_flush</function></funcdef> - <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_login_monitor_get_fd</function></funcdef> - <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_login_monitor_get_events</function></funcdef> - <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_login_monitor_get_timeout</function></funcdef> - <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef> - <paramdef>uint64_t *<parameter>timeout_usec</parameter></paramdef> - </funcprototype> - - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_login_monitor_new()</function> may be used to - monitor login sessions, users, seats, and virtual - machines/containers. Via a monitor object a file descriptor can be - integrated into an application defined event loop which is woken - up each time a user logs in, logs out or a seat is added or - removed, or a session, user, seat or virtual machine/container - changes state otherwise. The first parameter takes a string which - can be <literal>seat</literal> (to get only notifications about - seats being added, removed or changed), <literal>session</literal> - (to get only notifications about sessions being created or removed - or changed), <literal>uid</literal> (to get only notifications - when a user changes state in respect to logins) or - <literal>machine</literal> (to get only notifications when a - virtual machine or container is started or stopped). If - notifications shall be generated in all these conditions, - <constant>NULL</constant> may be passed. Note that in the future - additional categories may be defined. The second parameter returns - a monitor object and needs to be freed with the - <function>sd_login_monitor_unref()</function> call after - use.</para> - - <para><function>sd_login_monitor_unref()</function> may be used to - destroy a monitor object. Note that this will invalidate any file - descriptor returned by - <function>sd_login_monitor_get_fd()</function>.</para> - - <para><function>sd_login_monitor_flush()</function> may be used to - reset the wakeup state of the monitor object. Whenever an event - causes the monitor to wake up the event loop via the file - descriptor this function needs to be called to reset the wake-up - state. If this call is not invoked, the file descriptor will - immediately wake up the event loop again.</para> - - <para><function>sd_login_monitor_get_fd()</function> may be used - to retrieve the file descriptor of the monitor object that may be - integrated in an application defined event loop, based around - <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry> - or a similar interface. The application should include the - returned file descriptor as wake-up source for the events mask - returned by <function>sd_login_monitor_get_events()</function>. It - should pass a timeout value as returned by - <function>sd_login_monitor_get_timeout()</function>. Whenever a - wake-up is triggered the file descriptor needs to be reset via - <function>sd_login_monitor_flush()</function>. An application - needs to reread the login state with a function like - <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry> - or similar to determine what changed.</para> - - <para><function>sd_login_monitor_get_events()</function> will - return the <function>poll()</function> mask to wait for. This - function will return a combination of <constant>POLLIN</constant>, - <constant>POLLOUT</constant> and similar to fill into the - <literal>.events</literal> field of <varname>struct - pollfd</varname>.</para> - - <para><function>sd_login_monitor_get_timeout()</function> will - return a timeout value for usage in <function>poll()</function>. - This returns a value in microseconds since the epoch of - <constant>CLOCK_MONOTONIC</constant> for timing out - <function>poll()</function> in <varname>timeout_usec</varname>. - See - <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for details about <constant>CLOCK_MONOTONIC</constant>. If there - is no timeout to wait for this will fill in <constant>(uint64_t) - -1</constant> instead. Note that <function>poll()</function> takes - a relative timeout in milliseconds rather than an absolute timeout - in microseconds. To convert the absolute 'us' timeout into - relative 'ms', use code like the following:</para> - - <programlisting>uint64_t t; -int msec; -sd_login_monitor_get_timeout(m, &t); -if (t == (uint64_t) -1) - msec = -1; -else { - struct timespec ts; - uint64_t n; - clock_getttime(CLOCK_MONOTONIC, &ts); - n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000; - msec = t > n ? (int) ((t - n + 999) / 1000) : 0; -}</programlisting> - - <para>The code above does not do any error checking for brevity's - sake. The calculated <varname>msec</varname> integer can be passed - directly as <function>poll()</function>'s timeout - parameter.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, - <function>sd_login_monitor_new()</function>, - <function>sd_login_monitor_flush()</function> and - <function>sd_login_monitor_get_timeout()</function> - return 0 or a positive integer. On success, - <function>sd_login_monitor_get_fd()</function> returns - a Unix file descriptor. On success, - <function>sd_login_monitor_get_events()</function> - returns a combination of <constant>POLLIN</constant>, - <constant>POLLOUT</constant> and suchlike. On failure, - these calls return a negative errno-style error - code.</para> - - <para><function>sd_login_monitor_unref()</function> - always returns <constant>NULL</constant>.</para> - </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> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_get_seats</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>poll</refentrytitle><manvolnum>2</manvolnum></citerefentry>, - <citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_machine_get_class.xml b/man/sd_machine_get_class.xml new file mode 100644 index 000000000..1de911657 --- /dev/null +++ b/man/sd_machine_get_class.xml @@ -0,0 +1,123 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of elogind. + + Copyright 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/>. +--> + +<refentry id="sd_machine_get_class"> + + <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> + <refentrytitle>sd_machine_get_class</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_machine_get_class</refname> + <refname>sd_machine_get_ifindices</refname> + <refpurpose>Determine the class and network interface indices of a + locally running virtual machine or container.</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <elogind/sd-login.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_machine_get_class</function></funcdef> + <paramdef>const char* <parameter>machine</parameter></paramdef> + <paramdef>char *<parameter>class</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_machine_get_ifindices</function></funcdef> + <paramdef>const char* <parameter>machine</parameter></paramdef> + <paramdef>int **<parameter>ifindices</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><function>sd_machine_get_class()</function> may be used to + determine the class of a locally running virtual machine or + container that is registered with + <citerefentry><refentrytitle>elogind-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + The string returned is either <literal>vm</literal> or + <literal>container</literal>. 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_machine_get_ifindices()</function> may be used + to determine the numeric indices of the network interfaces on the + host that are pointing towards the specified locally running + virtual machine or container that is registered with + <citerefentry><refentrytitle>elogind-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + The returned array needs to be freed with the libc <citerefentry + project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call after use.</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> + </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> + + <refsect1> + <title>See Also</title> + + <para> + <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <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> + +</refentry> diff --git a/man/sd_notify.xml b/man/sd_notify.xml new file mode 100644 index 000000000..41c3f3fa7 --- /dev/null +++ b/man/sd_notify.xml @@ -0,0 +1,376 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of elogind. + + Copyright 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/>. +--> + +<refentry id="sd_notify" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <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> + <refentrytitle>sd_notify</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_notify</refname> + <refname>sd_notifyf</refname> + <refname>sd_pid_notify</refname> + <refname>sd_pid_notifyf</refname> + <refname>sd_pid_notify_with_fds</refname> + <refpurpose>Notify service manager about start-up completion and other service status changes</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <elogind/sd-daemon.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_notify</function></funcdef> + <paramdef>int <parameter>unset_environment</parameter></paramdef> + <paramdef>const char *<parameter>state</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_notifyf</function></funcdef> + <paramdef>int <parameter>unset_environment</parameter></paramdef> + <paramdef>const char *<parameter>format</parameter></paramdef> + <paramdef>...</paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_pid_notify</function></funcdef> + <paramdef>pid_t <parameter>pid</parameter></paramdef> + <paramdef>int <parameter>unset_environment</parameter></paramdef> + <paramdef>const char *<parameter>state</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_pid_notifyf</function></funcdef> + <paramdef>pid_t <parameter>pid</parameter></paramdef> + <paramdef>int <parameter>unset_environment</parameter></paramdef> + <paramdef>const char *<parameter>format</parameter></paramdef> + <paramdef>...</paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_pid_notify_with_fds</function></funcdef> + <paramdef>pid_t <parameter>pid</parameter></paramdef> + <paramdef>int <parameter>unset_environment</parameter></paramdef> + <paramdef>const char *<parameter>state</parameter></paramdef> + <paramdef>const int *<parameter>fds</parameter></paramdef> + <paramdef>unsigned <parameter>n_fds</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para><function>sd_notify()</function> may be called by a service + to notify the service manager about state changes. It can be used + to send arbitrary information, encoded in an + environment-block-like string. Most importantly it can be used for + start-up completion notification.</para> + + <para>If the <parameter>unset_environment</parameter> parameter is + non-zero, <function>sd_notify()</function> will unset the + <varname>$NOTIFY_SOCKET</varname> environment variable before + returning (regardless of whether the function call itself + succeeded or not). Further calls to + <function>sd_notify()</function> will then fail, but the variable + is no longer inherited by child processes.</para> + + <para>The <parameter>state</parameter> parameter should contain a + newline-separated list of variable assignments, similar in style + to an environment block. A trailing newline is implied if none is + specified. The string may contain any kind of variable + assignments, but the following shall be considered + well-known:</para> + + <variablelist> + <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> + </varlistentry> + + <varlistentry> + <term>RELOADING=1</term> + + <listitem><para>Tells the service manager that the service is + reloading its configuration. This is useful to allow the + service manager to track the service's internal state, and + 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> + </varlistentry> + + <varlistentry> + <term>STOPPING=1</term> + + <listitem><para>Tells the service manager that the service is + beginning its shutdown. This is useful to allow the service + manager to track the service's internal state, and present it + to the user.</para></listitem> + </varlistentry> + + <varlistentry> + <term>STATUS=...</term> + + <listitem><para>Passes a single-line UTF-8 status string back + to the service manager that describes the service state. This + is free-form and can be used for various purposes: general + state feedback, fsck-like programs could pass completion + percentages and failing programs could pass a human readable + error message. Example: <literal>STATUS=Completed 66% of file + system check...</literal></para></listitem> + </varlistentry> + + <varlistentry> + <term>ERRNO=...</term> + + <listitem><para>If a service fails, the errno-style error + code, formatted as string. Example: <literal>ERRNO=2</literal> + for ENOENT.</para></listitem> + </varlistentry> + + <varlistentry> + <term>BUSERROR=...</term> + + <listitem><para>If a service fails, the D-Bus error-style + error code. Example: + <literal>BUSERROR=org.freedesktop.DBus.Error.TimedOut</literal></para></listitem> + </varlistentry> + + <varlistentry> + <term>MAINPID=...</term> + + <listitem><para>The main process ID (PID) of the service, in + case the service manager did not fork off the process itself. + Example: <literal>MAINPID=4711</literal></para></listitem> + </varlistentry> + + <varlistentry> + <term>WATCHDOG=1</term> + + <listitem><para>Tells the service manager to update the + watchdog timestamp. This is the keep-alive ping that services + need to issue in regular intervals if + <varname>WatchdogSec=</varname> is enabled for it. See + <citerefentry><refentrytitle>elogind.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for information how to enable this functionality and + <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for the details of how the service can check whether the + watchdog is enabled. </para></listitem> + </varlistentry> + + + <varlistentry> + <term>FDSTORE=1</term> + + <listitem><para>Stores additional file descriptors in the + service manager. File descriptors sent this way will be + maintained per-service by the service manager and be passed + again using the usual file descriptor passing logic on the + next invocation of the service (see + <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>). + This is useful for implementing service restart schemes where + services serialize their state to <filename>/run</filename>, + push their file descriptors to the system manager, and are + then restarted, retrieving their state again via socket + passing and <filename>/run</filename>. Note that the service + manager will accept messages for a service only if + <varname>FileDescriptorStoreMax=</varname> is set to non-zero + for it (defaults to zero). See + <citerefentry><refentrytitle>elogind.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details. Multiple arrays of file descriptors may be sent + in separate messages, in which case the arrays are combined. + Note that the service manager removes duplicate file + descriptors before passing them to the service. Use + <function>sd_pid_notify_with_fds()</function> to send messages + with <literal>FDSTORE=1</literal>, see + below.</para></listitem> + </varlistentry> + + </variablelist> + + <para>It is recommended to prefix variable names that are not + listed above with <varname>X_</varname> to avoid namespace + clashes.</para> + + <para>Note that elogind will accept status data sent from a + service only if the <varname>NotifyAccess=</varname> option is + correctly set in the service definition file. See + <citerefentry><refentrytitle>elogind.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para> + + <para><function>sd_notifyf()</function> is similar to + <function>sd_notify()</function> but takes a + <function>printf()</function>-like format string plus + arguments.</para> + + <para><function>sd_pid_notify()</function> and + <function>sd_pid_notifyf()</function> are similar to + <function>sd_notify()</function> and + <function>sd_notifyf()</function> but take a process ID (PID) to + use as originating PID for the message as first argument. This is + useful to send notification messages on behalf of other processes, + provided the appropriate privileges are available. If the PID + argument is specified as 0 the process ID of the calling process + is used, in which case the calls are fully equivalent to + <function>sd_notify()</function> and + <function>sd_notifyf()</function>.</para> + + <para><function>sd_pid_notify_with_fds()</function> is similar to + <function>sd_pid_notify()</function> but takes an additional array + of file descriptors. These file descriptors are sent along the + notification message to the service manager. This is particularly + useful for sending <literal>FDSTORE=1</literal> messages, as + described above. The additional arguments are a pointer to the + file descriptor array plus the number of file descriptors in the + array. If the number of file descriptors is passed as 0, the call + is fully equivalent to <function>sd_pid_notify()</function>, i.e. + no file descriptors are passed. Note that sending file descriptors + to the service manager on messages that do not expect them (i.e. + without <literal>FDSTORE=1</literal>) they are immediately closed + on reception.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On failure, these calls return a negative errno-style error + code. If <varname>$NOTIFY_SOCKET</varname> was not set and hence + no status data could be sent, 0 is returned. If the status was + sent, these functions return with a positive return value. In + order to support both, init systems that implement this scheme and + those which do not, it is generally recommended to ignore the + return value of this call.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <xi:include href="libelogind-pkgconfig.xml" xpointer="pkgconfig-text"/> + + <para>Internally, these functions send a single datagram with the + state string as payload to the <constant>AF_UNIX</constant> socket + referenced in the <varname>$NOTIFY_SOCKET</varname> environment + variable. If the first character of + <varname>$NOTIFY_SOCKET</varname> is <literal>@</literal>, the + string is understood as Linux abstract namespace socket. The + datagram is accompanied by the process credentials of the sending + service, using SCM_CREDENTIALS.</para> + </refsect1> + + <refsect1> + <title>Environment</title> + + <variablelist class='environment-variables'> + <varlistentry> + <term><varname>$NOTIFY_SOCKET</varname></term> + + <listitem><para>Set by the service manager for supervised + processes for status and start-up completion notification. + This environment variable specifies the socket + <function>sd_notify()</function> talks to. See above for + details.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + + <example> + <title>Start-up Notification</title> + + <para>When a service finished starting up, it might issue the + following call to notify the service manager:</para> + + <programlisting>sd_notify(0, "READY=1");</programlisting> + </example> + + <example> + <title>Extended Start-up Notification</title> + + <para>A service could send the following after completing + initialization:</para> + + <programlisting>sd_notifyf(0, "READY=1\n" + "STATUS=Processing requests...\n" + "MAINPID=%lu", + (unsigned long) getpid());</programlisting> + </example> + + <example> + <title>Error Cause Notification</title> + + <para>A service could send the following shortly before exiting, on failure:</para> + + <programlisting>sd_notifyf(0, "STATUS=Failed to start up: %s\n" + "ERRNO=%i", + strerror(errno), + errno);</programlisting> + </example> + + <example> + <title>Store a File Descriptor in the Service Manager</title> + + <para>To store an open file descriptor in the service manager, + in order to continue operation after a service restart without + losing state use <literal>FDSTORE=1</literal>:</para> + + <programlisting>sd_pid_notify_with_fds(0, 0, "FDSTORE=1", &fd, 1);</programlisting> + </example> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/sd_seat_get_active.xml b/man/sd_seat_get_active.xml index e0002c205..793bbc8c9 100644 --- a/man/sd_seat_get_active.xml +++ b/man/sd_seat_get_active.xml @@ -3,29 +3,29 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of systemd. + This file is part of elogind. Copyright 2010 Lennart Poettering - systemd is free software; you can redistribute it and/or modify it + 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. - systemd is distributed in the hope that it will be useful, but + 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 systemd; If not, see <http://www.gnu.org/licenses/>. + along with elogind; If not, see <http://www.gnu.org/licenses/>. --> <refentry id="sd_seat_get_active" conditional='HAVE_PAM'> <refentryinfo> <title>sd_seat_get_active</title> - <productname>systemd</productname> + <productname>elogind</productname> <authorgroup> <author> @@ -53,7 +53,7 @@ <refsynopsisdiv> <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo> + <funcsynopsisinfo>#include <elogind/sd-login.h></funcsynopsisinfo> <funcprototype> <funcdef>int <function>sd_seat_get_active</function></funcdef> @@ -166,7 +166,7 @@ <title>See Also</title> <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <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 069cbe091..55726f96a 100644 --- a/man/sd_session_is_active.xml +++ b/man/sd_session_is_active.xml @@ -3,29 +3,29 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- - This file is part of systemd. + This file is part of elogind. Copyright 2010 Lennart Poettering - systemd is free software; you can redistribute it and/or modify it + 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. - systemd is distributed in the hope that it will be useful, but + 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 systemd; If not, see <http://www.gnu.org/licenses/>. + along with elogind; If not, see <http://www.gnu.org/licenses/>. --> <refentry id="sd_session_is_active" conditional='HAVE_PAM'> <refentryinfo> <title>sd_session_is_active</title> - <productname>systemd</productname> + <productname>elogind</productname> <authorgroup> <author> @@ -62,7 +62,7 @@ <refsynopsisdiv> <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo> + <funcsynopsisinfo>#include <elogind/sd-login.h></funcsynopsisinfo> <funcprototype> <funcdef>int <function>sd_session_is_active</function></funcdef> @@ -313,7 +313,7 @@ <title>See Also</title> <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <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 deleted file mode 100644 index 4218f7381..000000000 --- a/man/sd_uid_get_state.xml +++ /dev/null @@ -1,204 +0,0 @@ -<?xml version='1.0'?> <!--*-nxml-*--> -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - -<!-- - This file is part of 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/>. ---> - -<refentry id="sd_uid_get_state" conditional='HAVE_PAM'> - - <refentryinfo> - <title>sd_uid_get_state</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>sd_uid_get_state</refentrytitle> - <manvolnum>3</manvolnum> - </refmeta> - - <refnamediv> - <refname>sd_uid_get_state</refname> - <refname>sd_uid_is_on_seat</refname> - <refname>sd_uid_get_sessions</refname> - <refname>sd_uid_get_seats</refname> - <refname>sd_uid_get_display</refname> - <refpurpose>Determine login state of a specific Unix user ID</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo> - - <funcprototype> - <funcdef>int <function>sd_uid_get_state</function></funcdef> - <paramdef>uid_t <parameter>uid</parameter></paramdef> - <paramdef>char **<parameter>state</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_uid_is_on_seat</function></funcdef> - <paramdef>uid_t <parameter>uid</parameter></paramdef> - <paramdef>int <parameter>require_active</parameter></paramdef> - <paramdef>const char *<parameter>seat</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_uid_get_sessions</function></funcdef> - <paramdef>uid_t <parameter>uid</parameter></paramdef> - <paramdef>int <parameter>require_active</parameter></paramdef> - <paramdef>char ***<parameter>sessions</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_uid_get_seats</function></funcdef> - <paramdef>uid_t <parameter>uid</parameter></paramdef> - <paramdef>int <parameter>require_active</parameter></paramdef> - <paramdef>char ***<parameter>seats</parameter></paramdef> - </funcprototype> - - <funcprototype> - <funcdef>int <function>sd_uid_get_display</function></funcdef> - <paramdef>uid_t <parameter>uid</parameter></paramdef> - <paramdef>char **<parameter>session</parameter></paramdef> - </funcprototype> - </funcsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><function>sd_uid_get_state()</function> may be used to - determine the login state of a specific Unix user identifier. The - following states are currently known: <literal>offline</literal> - (user not logged in at all), <literal>lingering</literal> (user - not logged in, but some user services running), - <literal>online</literal> (user logged in, but not active, i.e. - has no session in the foreground), <literal>active</literal> (user - logged in, and has at least one active session, i.e. one session - in the foreground), <literal>closing</literal> (user not logged - in, and not lingering, but some processes are still around). In - the future additional states might be defined, client code should - be written to be robust in regards to additional state strings - being returned. 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_uid_is_on_seat()</function> may be used to - determine whether a specific user is logged in or active on a - specific seat. Accepts a Unix user identifier and a seat - identifier string as parameters. The - <parameter>require_active</parameter> parameter is a boolean - value. If non-zero (true), this function will test if the user is - active (i.e. has a session that is in the foreground and accepting - user input) on the specified seat, otherwise (false) only if the - user is logged in (and possibly inactive) on the specified - seat.</para> - - <para><function>sd_uid_get_sessions()</function> may be used to - determine the current sessions of the specified user. Accepts a - Unix user identifier as parameter. The - <parameter>require_active</parameter> parameter controls whether - the returned list shall consist of only those sessions where the - user is currently active (> 0), where the user is currently - online but possibly inactive (= 0), or logged in at all but - possibly closing the session (< 0). The call returns a - <constant>NULL</constant> terminated string array of session - identifiers in <parameter>sessions</parameter> which needs to be - freed by the caller with the libc - <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> - call after use, including all the strings referenced. If the - string array parameter is passed as <constant>NULL</constant>, the - array will not be filled in, but the return code still indicates - the number of current sessions. Note that instead of an empty - array <constant>NULL</constant> may be returned and should be - considered equivalent to an empty array.</para> - - <para>Similarly, <function>sd_uid_get_seats()</function> may be - used to determine the list of seats on which the user currently - has sessions. Similar semantics apply, however note that the user - may have multiple sessions on the same seat as well as sessions - with no attached seat and hence the number of entries in the - returned array may differ from the one returned by - <function>sd_uid_get_sessions()</function>.</para> - - <para><function>sd_uid_get_display()</function> returns the name - of the "primary" session of a user. If the user has graphical - sessions, it will be the oldest graphical session. Otherwise, it - will be the oldest open session.</para> - </refsect1> - - <refsect1> - <title>Return Value</title> - - <para>On success, <function>sd_uid_get_state()</function> returns - 0 or a positive integer. If the test succeeds, - <function>sd_uid_is_on_seat()</function> returns a positive - integer; if it fails, 0. - <function>sd_uid_get_sessions()</function> and - <function>sd_uid_get_seats()</function> return the number of - entries in the returned arrays. - <function>sd_uid_get_display()</function> returns a non-negative - code on success. On failure, these calls return a negative - errno-style error code.</para> - </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> - - <refsect1> - <title>History</title> - - <para><function>sd_uid_get_state()</function>, - <function>sd_uid_is_on_seat()</function>, - <function>sd_uid_get_sessions()</function>, and - <function>sd_uid_get_seats()</function> functions were added in - systemd-31.</para> - - <para><function>sd_uid_get_display()</function> was added in - systemd-213.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_pid_get_owner_uid</refentrytitle><manvolnum>3</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/sd_watchdog_enabled.xml b/man/sd_watchdog_enabled.xml new file mode 100644 index 000000000..e588b0401 --- /dev/null +++ b/man/sd_watchdog_enabled.xml @@ -0,0 +1,175 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + This file is part of elogind. + + Copyright 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/>. +--> + +<refentry id="sd_watchdog_enabled" + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <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> + <refentrytitle>sd_watchdog_enabled</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname>sd_watchdog_enabled</refname> + <refpurpose>Check whether the service manager expects watchdog keep-alive notifications from a service</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <elogind/sd-daemon.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>int <function>sd_watchdog_enabled</function></funcdef> + <paramdef>int <parameter>unset_environment</parameter></paramdef> + <paramdef>uint64_t *<parameter>usec</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para><function>sd_watchdog_enabled()</function> may be called by + a service to detect whether the service manager expects regular + keep-alive watchdog notification events from it, and the timeout + after which the manager will act on the service if it did not get + such a notification.</para> + + <para>If the <varname>$WATCHDOG_USEC</varname> environment + variable is set, and the <varname>$WATCHDOG_PID</varname> variable + is unset or set to the PID of the current process, the service + manager expects notifications from this process. The manager will + usually terminate a service when it does not get a notification + message within the specified time after startup and after each + previous message. It is recommended that a daemon sends a + keep-alive notification message to the service manager every half + of the time returned here. Notification messages may be sent with + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> + with a message string of <literal>WATCHDOG=1</literal>.</para> + + <para>If the <parameter>unset_environment</parameter> parameter is + non-zero, <function>sd_watchdog_enabled()</function> will unset + the <varname>$WATCHDOG_USEC</varname> and + <varname>$WATCHDOG_PID</varname> environment variables before + returning (regardless of whether the function call itself + succeeded or not). Those variables are no longer inherited by + child processes. Further calls to + <function>sd_watchdog_enabled()</function> will also return with + zero.</para> + + <para>If the <parameter>usec</parameter> parameter is non-NULL, + <function>sd_watchdog_enabled()</function> will write the timeout + in µs for the watchdog logic to it.</para> + + <para>To enable service supervision with the watchdog logic, use + <varname>WatchdogSec=</varname> in service files. See + <citerefentry><refentrytitle>elogind.service</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On failure, this call returns a negative errno-style error + code. If the service manager expects watchdog keep-alive + notification messages to be sent, > 0 is returned, otherwise 0 + is returned. Only if the return value is > 0, the + <parameter>usec</parameter> parameter is valid after the + call.</para> + </refsect1> + + <refsect1> + <title>Notes</title> + + <xi:include href="libelogind-pkgconfig.xml" xpointer="pkgconfig-text"/> + + <para>Internally, this functions parses the + <varname>$WATCHDOG_PID</varname> and + <varname>$WATCHDOG_USEC</varname> environment variable. The call + will ignore these variables if <varname>$WATCHDOG_PID</varname> + does not contain the PID of the current process, under the + assumption that in that case, the variables were set for a + different process further up the process tree.</para> + </refsect1> + + <refsect1> + <title>Environment</title> + + <variablelist class='environment-variables'> + <varlistentry> + <term><varname>$WATCHDOG_PID</varname></term> + + <listitem><para>Set by the system manager for supervised + process for which watchdog support is enabled, and contains + the PID of that process. See above for + details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>$WATCHDOG_USEC</varname></term> + + <listitem><para>Set by the system manager for supervised + process for which watchdog support is enabled, and contains + the watchdog timeout in µs See above for + details.</para></listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>History</title> + + <para>The watchdog functionality and the + <varname>$WATCHDOG_USEC</varname> variable were added in + elogind-41.</para> + + <para><function>sd_watchdog_enabled()</function> function was + added in elogind-209. Since that version the + <varname>$WATCHDOG_PID</varname> variable is also set.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>elogind.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> |