mirror of
https://github.com/systemd/systemd.git
synced 2024-12-23 21:35:11 +03:00
Luca Boccassi
GitHub
commit
d20110b459
1
TODO
1
TODO
@ -1419,7 +1419,6 @@ Features:
|
||||
- teach it to copy in unified kernel images and maybe type #1 boot loader spec entries from host
|
||||
- make it operate on loopback files, dissecting enough to find ESP to operate on
|
||||
- bootspec: properly support boot attempt counters when parsing entry file names
|
||||
- support --quiet in is-installed, update
|
||||
|
||||
* kernel-install:
|
||||
- optionally, support generating type #2 entries instead of type #1, including signing them
|
||||
|
||||
@ -686,7 +686,7 @@
|
||||
<varlistentry>
|
||||
<term><option>--luks-cipher=</option><replaceable>CIPHER</replaceable></term>
|
||||
<term><option>--luks-cipher-mode=</option><replaceable>MODE</replaceable></term>
|
||||
<term><option>--luks-volume-key-size=</option><replaceable>BITS</replaceable></term>
|
||||
<term><option>--luks-volume-key-size=</option><replaceable>BYTES</replaceable></term>
|
||||
<term><option>--luks-pbkdf-type=</option><replaceable>TYPE</replaceable></term>
|
||||
<term><option>--luks-pbkdf-hash-algorithm=</option><replaceable>ALGORITHM</replaceable></term>
|
||||
<term><option>--luks-pbkdf-time-cost=</option><replaceable>SECONDS</replaceable></term>
|
||||
@ -696,7 +696,12 @@
|
||||
<listitem><para>Configures various cryptographic parameters for the LUKS2 storage mechanism. See
|
||||
<citerefentry
|
||||
project='man-pages'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
|
||||
for details on the specific attributes.</para></listitem>
|
||||
for details on the specific attributes.</para>
|
||||
|
||||
<para>Note that <command>homectl</command> uses bytes for key size, like
|
||||
<filename>/proc/crypto</filename>, but <citerefentry
|
||||
project='man-pages'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
|
||||
uses bits.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
|
||||
18
man/sd_bus_error-example.c
Normal file
18
man/sd_bus_error-example.c
Normal file
@ -0,0 +1,18 @@
|
||||
/* SPDX-License-Identifier: CC0-1.0 */
|
||||
|
||||
#include <errno.h>
|
||||
#include <string.h>
|
||||
#include <unistd.h>
|
||||
#include <sd-bus.h>
|
||||
|
||||
int writer_with_negative_errno_return(int fd, sd_bus_error *error) {
|
||||
const char *message = "Hello, World!\n";
|
||||
|
||||
ssize_t n = write(fd, message, strlen(message));
|
||||
if (n >= 0)
|
||||
return n; /* On success, return the number of bytes written, possibly 0. */
|
||||
|
||||
/* On error, initialize the error structure, and also propagate the errno
|
||||
* value that write(2) set for us. */
|
||||
return sd_bus_error_set_errnof(error, errno, "Failed to write to fd %i: %m", fd);
|
||||
}
|
||||
@ -246,10 +246,15 @@
|
||||
values in <parameter>e</parameter>, if <parameter>e</parameter> has been set with an error value before.
|
||||
Otherwise, it will return immediately. If the strings in <parameter>e</parameter> were set using
|
||||
<function>sd_bus_error_set_const()</function>, they will be shared. Otherwise, they will be
|
||||
copied. Returns a converted <varname>errno</varname>-like, negative error code or <constant>0</constant>.
|
||||
Before this call, <parameter>dst</parameter> must be unset, i.e. either freshly initialized with
|
||||
copied. Before this call, <parameter>dst</parameter> must be unset, i.e. either freshly initialized with
|
||||
<constant>NULL</constant> or reset using <function>sd_bus_error_free()</function>.</para>
|
||||
|
||||
<para><function>sd_bus_error_copy()</function> generally returns <constant>0</constant> or a negative
|
||||
<varname>errno</varname>-like value based on the input parameter <parameter>e</parameter>:
|
||||
<constant>0</constant> if it was unset and a negative integer if it was set to some error, similarly to
|
||||
<function>sd_bus_error_set()</function>. It may however also return an error generated internally, for
|
||||
example <constant>-ENOMEM</constant> if a memory allocation fails.</para>
|
||||
|
||||
<para><function>sd_bus_error_move()</function> is similar to <function>sd_bus_error_copy()</function>,
|
||||
but will move any error information from <parameter>e</parameter> into <parameter>dst</parameter>,
|
||||
resetting the former. This function cannot fail, as no new memory is allocated. Note that if
|
||||
@ -286,6 +291,18 @@
|
||||
to <constant>NULL</constant>. The structure may be reused afterwards.</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Reference ownership</title>
|
||||
|
||||
<para><structname>sd_bus_error</structname> is not reference-counted. Users should destroy resources held
|
||||
by it by calling <function>sd_bus_error_free()</function>. Usually, error structures are allocated on the
|
||||
stack or passed in as function parameters, but they may also be allocated dynamically, in which case it
|
||||
is the duty of the caller to <citerefentry
|
||||
project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> the memory
|
||||
held by the structure itself after freeing its contents with
|
||||
<function>sd_bus_error_free()</function>.</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Return Value</title>
|
||||
|
||||
@ -297,7 +314,8 @@
|
||||
<function>sd_bus_error_set_errnofv()</function>, return <constant>0</constant> when the specified error
|
||||
value is <constant>0</constant>, and a negative errno-like value corresponding to the
|
||||
<parameter>error</parameter> parameter otherwise. If an error occurs internally, one of the negative
|
||||
error values listed below will be returned.</para>
|
||||
error values listed below will be returned. This allows those functions to be conveniently used in a
|
||||
<constant>return</constant> statement, see the example below.</para>
|
||||
|
||||
<para><function>sd_bus_error_get_errno()</function> returns
|
||||
<constant>false</constant> when <parameter>e</parameter> is
|
||||
@ -305,7 +323,9 @@
|
||||
<parameter>e->name</parameter> otherwise.</para>
|
||||
|
||||
<para><function>sd_bus_error_copy()</function> and <function>sd_bus_error_move()</function> return a
|
||||
negative error value converted from the source error, and zero if the error has not been set.</para>
|
||||
negative error value converted from the source error, and zero if the error has not been set. This
|
||||
allows those functions to be conveniently used in a <constant>return</constant> statement, see the
|
||||
example below.</para>
|
||||
|
||||
<para><function>sd_bus_error_is_set()</function> returns a
|
||||
non-zero value when <parameter>e</parameter> and the
|
||||
@ -316,32 +336,18 @@
|
||||
<function>sd_bus_error_has_names_sentinel()</function> return a non-zero value when <parameter>e</parameter> is
|
||||
non-<constant>NULL</constant> and the <structfield>name</structfield> field is equal to one of the given
|
||||
names, zero otherwise.</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Reference ownership</title>
|
||||
<para><structname>sd_bus_error</structname> is not reference
|
||||
counted. Users should destroy resources held by it by calling
|
||||
<function>sd_bus_error_free()</function>. Usually, error structures
|
||||
are allocated on the stack or passed in as function parameters,
|
||||
but they may also be allocated dynamically, in which case it is
|
||||
the duty of the caller to <citerefentry
|
||||
project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||
the memory held by the structure itself after freeing its contents
|
||||
with <function>sd_bus_error_free()</function>.</para>
|
||||
|
||||
<refsect2>
|
||||
<title>Errors</title>
|
||||
|
||||
<para>Returned errors may indicate the following problems:</para>
|
||||
<para>Return value may indicate the following problems in the invocation of the function itself:</para>
|
||||
|
||||
<variablelist>
|
||||
|
||||
<varlistentry>
|
||||
<term><constant>-EINVAL</constant></term>
|
||||
|
||||
<listitem><para>Error was already set in <structname>sd_bus_error</structname> structure when one
|
||||
the error-setting functions was called.</para></listitem>
|
||||
<listitem><para>Error was already set in the <structname>sd_bus_error</structname> structure when
|
||||
one the error-setting functions was called.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
@ -350,9 +356,29 @@
|
||||
<listitem><para>Memory allocation failed.</para></listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
<para>On success, <function>sd_bus_error_set()</function>, <function>sd_bus_error_setf()</function>,
|
||||
<function>sd_bus_error_set_const()</function>, <function>sd_bus_error_set_errno()</function>,
|
||||
<function>sd_bus_error_set_errnof()</function>, <function>sd_bus_error_set_errnofv()</function>,
|
||||
<function>sd_bus_error_copy()</function>, and <function>sd_bus_error_move()</function> will return a
|
||||
negative converted <varname>errno</varname>-style value, or <constant>0</constant> if the error
|
||||
parameter is <constant>NULL</constant> or unset. D-Bus errors are converted to the integral
|
||||
<varname>errno</varname>-style value, and the mapping mechanism is extensible, see the discussion
|
||||
above. This effectively means that almost any negative <varname>errno</varname>-style value can be
|
||||
returned.</para>
|
||||
</refsect2>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Examples</title>
|
||||
|
||||
<example>
|
||||
<title>Using the negative return value to propagate an error</title>
|
||||
|
||||
<programlisting><xi:include href="sd_bus_error-example.c" parse="text" /></programlisting>
|
||||
</example>
|
||||
</refsect1>
|
||||
|
||||
<xi:include href="libsystemd-pkgconfig.xml" />
|
||||
|
||||
<refsect1>
|
||||
|
||||
@ -18,7 +18,7 @@
|
||||
|
||||
<refnamediv>
|
||||
<refname>shutdown</refname>
|
||||
<refpurpose>Halt, power-off or reboot the machine</refpurpose>
|
||||
<refpurpose>Halt, power off or reboot the machine</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
@ -33,8 +33,7 @@
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
|
||||
<para><command>shutdown</command> may be used to halt, power-off
|
||||
or reboot the machine.</para>
|
||||
<para><command>shutdown</command> may be used to halt, power off, or reboot the machine.</para>
|
||||
|
||||
<para>The first argument may be a time string (which is usually
|
||||
<literal>now</literal>). Optionally, this may be followed by a
|
||||
@ -81,47 +80,41 @@
|
||||
<term><option>-P</option></term>
|
||||
<term><option>--poweroff</option></term>
|
||||
|
||||
<listitem><para>Power-off the machine (the
|
||||
default).</para></listitem>
|
||||
<listitem><para>Power the machine off (the default).</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>-r</option></term>
|
||||
<term><option>--reboot</option></term>
|
||||
|
||||
<listitem><para>Reboot the
|
||||
machine.</para></listitem>
|
||||
<listitem><para>Reboot the machine.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>-h</option></term>
|
||||
|
||||
<listitem><para>Equivalent to <option>--poweroff</option>,
|
||||
unless <option>--halt</option> is specified.</para></listitem>
|
||||
<listitem><para>The same as <option>--poweroff</option>, but does not override the action to take if
|
||||
it is "halt". E.g. <command>shutdown --reboot -h</command> means "poweroff", but <command>shutdown
|
||||
--halt -h</command> means "halt".</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>-k</option></term>
|
||||
|
||||
<listitem><para>Do not halt, power-off, reboot, just write
|
||||
wall message.</para></listitem>
|
||||
<listitem><para>Do not halt, power off, or reboot, but just write the wall message.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>--no-wall</option></term>
|
||||
|
||||
<listitem><para>Do not send wall
|
||||
message before
|
||||
halt, power-off, reboot.</para></listitem>
|
||||
<listitem><para>Do not send wall message before halt, power off, or reboot.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><option>-c</option></term>
|
||||
|
||||
<listitem><para>Cancel a pending shutdown. This may be used
|
||||
to cancel the effect of an invocation of
|
||||
<command>shutdown</command> with a time argument that is not
|
||||
<literal>+0</literal> or
|
||||
<listitem><para>Cancel a pending shutdown. This may be used to cancel the effect of an invocation of
|
||||
<command>shutdown</command> with a time argument that is not <literal>+0</literal> or
|
||||
<literal>now</literal>.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
|
||||
@ -26,10 +26,9 @@
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
|
||||
<para>A unit configuration file whose name ends in
|
||||
<literal>.automount</literal> encodes information about a file
|
||||
system automount point controlled and supervised by
|
||||
systemd.</para>
|
||||
<para>A unit configuration file whose name ends in <literal>.automount</literal> encodes information
|
||||
about a file system automount point controlled and supervised by systemd. Automount units may be used to
|
||||
implement on-demand mounting as well as parallelized mounting of file systems.</para>
|
||||
|
||||
<para>This man page lists the configuration options specific to
|
||||
this unit type. See
|
||||
@ -39,13 +38,13 @@
|
||||
[Install] sections. The automount specific configuration options
|
||||
are configured in the [Automount] section.</para>
|
||||
|
||||
<para>Automount units must be named after the automount directories they control. Example: the automount point
|
||||
<filename index="false">/home/lennart</filename> must be configured in a unit file
|
||||
<filename>home-lennart.automount</filename>. For details about the escaping logic used to convert a file system
|
||||
path to a unit name see
|
||||
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Note that
|
||||
automount units cannot be templated, nor is it possible to add multiple names to an automount unit by creating
|
||||
additional symlinks to its unit file.</para>
|
||||
<para>Automount units must be named after the automount directories they control. Example: the automount
|
||||
point <filename index="false">/home/lennart</filename> must be configured in a unit file
|
||||
<filename>home-lennart.automount</filename>. For details about the escaping logic used to convert a file
|
||||
system path to a unit name see
|
||||
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Note
|
||||
that automount units cannot be templated, nor is it possible to add multiple names to an automount unit
|
||||
by creating symlinks to its unit file.</para>
|
||||
|
||||
<para>For each automount unit file a matching mount unit file (see
|
||||
<citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||||
@ -55,9 +54,6 @@
|
||||
accesses <filename>/home/lennart</filename> the mount unit
|
||||
<filename>home-lennart.mount</filename> will be activated.</para>
|
||||
|
||||
<para>Automount units may be used to implement on-demand mounting
|
||||
as well as parallelized mounting of file systems.</para>
|
||||
|
||||
<para>Note that automount units are separate from the mount itself, so you
|
||||
should not set <varname>After=</varname> or <varname>Requires=</varname>
|
||||
for mount dependencies here. For example, you should not set
|
||||
@ -65,8 +61,11 @@
|
||||
filesystems. Doing so may result in an ordering cycle.</para>
|
||||
|
||||
<para>Note that automount support on Linux is privileged, automount units are hence only available in the
|
||||
system service manager (and root's user service manager), but not in unprivileged user's service
|
||||
manager.</para>
|
||||
system service manager (and root's user service manager), but not in unprivileged users' service
|
||||
managers.</para>
|
||||
|
||||
<para>Note that automount units should not be nested. (The establishment of the inner automount point
|
||||
would unconditionally pin the outer mount point, defeating its purpose.)</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
@ -78,12 +77,12 @@
|
||||
<para>The following dependencies are implicitly added:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>If an automount unit is beneath another mount unit in the
|
||||
file system hierarchy, both a requirement and an ordering
|
||||
dependency between both units are created automatically.</para></listitem>
|
||||
<listitem><para>If an automount unit is beneath another mount unit in the file system hierarchy, a
|
||||
requirement and ordering dependencies are created to the on the unit higher in the hierarchy.
|
||||
</para></listitem>
|
||||
|
||||
<listitem><para>An implicit <varname>Before=</varname> dependency is created
|
||||
between an automount unit and the mount unit it activates.</para></listitem>
|
||||
<listitem><para>An implicit <varname>Before=</varname> dependency is created between an automount
|
||||
unit and the mount unit it activates.</para></listitem>
|
||||
</itemizedlist>
|
||||
</refsect2>
|
||||
|
||||
@ -161,6 +160,7 @@
|
||||
creating these directories. Takes an access mode in octal
|
||||
notation. Defaults to 0755.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>TimeoutIdleSec=</varname></term>
|
||||
<listitem><para>Configures an idle timeout. Once the mount has been
|
||||
|
||||
@ -59,12 +59,13 @@
|
||||
does not read any options from <filename>/etc/fstab</filename>, and
|
||||
must be run as UID 0.</para>
|
||||
|
||||
<para>Mount units must be named after the mount point directories they control. Example: the mount point <filename
|
||||
index="false">/home/lennart</filename> must be configured in a unit file <filename>home-lennart.mount</filename>.
|
||||
For details about the escaping logic used to convert a file system path to a unit name, see
|
||||
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Note that mount
|
||||
units cannot be templated, nor is possible to add multiple names to a mount unit by creating additional symlinks to
|
||||
it.</para>
|
||||
<para>Mount units must be named after the mount point directories they control. Example: the mount point
|
||||
<filename index="false">/home/lennart</filename> must be configured in a unit file
|
||||
<filename>home-lennart.mount</filename>. For details about the escaping logic used to convert a file
|
||||
system path to a unit name, see
|
||||
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Note
|
||||
that mount units cannot be templated, nor is possible to add multiple names to a mount unit by creating
|
||||
symlinks to its unit file.</para>
|
||||
|
||||
<para>Optionally, a mount unit may be accompanied by an automount
|
||||
unit, to allow on-demand or parallelized mounting. See
|
||||
|
||||
Loading…
Reference in New Issue
Block a user