From 19cb82799e1d84243f43c9e1db3c1dfdf1250344 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 20 May 2022 17:31:53 +0200 Subject: [PATCH 1/7] man: do not say "additional symlinks" for mount/automount aliases "additional" implies that the unit itself is a symlink, which it is not. Also "link to the mount unit", not "link to the mount". --- man/systemd.automount.xml | 14 +++++++------- man/systemd.mount.xml | 13 +++++++------ 2 files changed, 14 insertions(+), 13 deletions(-) diff --git a/man/systemd.automount.xml b/man/systemd.automount.xml index da35a7d26b..513f939dd2 100644 --- a/man/systemd.automount.xml +++ b/man/systemd.automount.xml @@ -39,13 +39,13 @@ [Install] sections. The automount specific configuration options are configured in the [Automount] section. - Automount units must be named after the automount directories they control. Example: the automount point - /home/lennart must be configured in a unit file - home-lennart.automount. For details about the escaping logic used to convert a file system - path to a unit name see - systemd.unit5. 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. + Automount units must be named after the automount directories they control. Example: the automount + point /home/lennart must be configured in a unit file + home-lennart.automount. For details about the escaping logic used to convert a file + system path to a unit name see + systemd.unit5. 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. For each automount unit file a matching mount unit file (see systemd.mount5 diff --git a/man/systemd.mount.xml b/man/systemd.mount.xml index 6d21d32778..8f4ebfc788 100644 --- a/man/systemd.mount.xml +++ b/man/systemd.mount.xml @@ -59,12 +59,13 @@ does not read any options from /etc/fstab, and must be run as UID 0. - Mount units must be named after the mount point directories they control. Example: the mount point /home/lennart must be configured in a unit file home-lennart.mount. - For details about the escaping logic used to convert a file system path to a unit name, see - systemd.unit5. Note that mount - units cannot be templated, nor is possible to add multiple names to a mount unit by creating additional symlinks to - it. + Mount units must be named after the mount point directories they control. Example: the mount point + /home/lennart must be configured in a unit file + home-lennart.mount. For details about the escaping logic used to convert a file + system path to a unit name, see + systemd.unit5. 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. Optionally, a mount unit may be accompanied by an automount unit, to allow on-demand or parallelized mounting. See From 3844a421382e01ca95f85789674410bea821f275 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Wed, 25 May 2022 16:36:50 +0200 Subject: [PATCH 2/7] TODO: drop entry Implemented in 14e6e444dd9eaa0db229548c31baecd75de4478e. --- TODO | 1 - 1 file changed, 1 deletion(-) diff --git a/TODO b/TODO index 9ff2a90fd4..88d0885bec 100644 --- a/TODO +++ b/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 From 93dbc22a9533ab4fbf8a4b6c176b95f8cef7a9a6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 20 May 2022 17:35:17 +0200 Subject: [PATCH 3/7] man/systemd.automount: move the main description up and clarify deps --- man/systemd.automount.xml | 24 ++++++++++-------------- 1 file changed, 10 insertions(+), 14 deletions(-) diff --git a/man/systemd.automount.xml b/man/systemd.automount.xml index 513f939dd2..253ffebe3f 100644 --- a/man/systemd.automount.xml +++ b/man/systemd.automount.xml @@ -26,10 +26,9 @@ Description - A unit configuration file whose name ends in - .automount encodes information about a file - system automount point controlled and supervised by - systemd. + A unit configuration file whose name ends in .automount 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. This man page lists the configuration options specific to this unit type. See @@ -55,9 +54,6 @@ accesses /home/lennart the mount unit home-lennart.mount will be activated. - Automount units may be used to implement on-demand mounting - as well as parallelized mounting of file systems. - Note that automount units are separate from the mount itself, so you should not set After= or Requires= for mount dependencies here. For example, you should not set @@ -65,8 +61,8 @@ filesystems. Doing so may result in an ordering cycle. 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. + system service manager (and root's user service manager), but not in unprivileged users' service + managers. @@ -78,12 +74,12 @@ The following dependencies are implicitly added: - 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. + 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. + - An implicit Before= dependency is created - between an automount unit and the mount unit it activates. + An implicit Before= dependency is created between an automount + unit and the mount unit it activates. From 223a359f21af1572a5b98629a3c684f764f3f26e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Thu, 26 May 2022 14:28:43 +0200 Subject: [PATCH 4/7] man/automount: say that automounts should not be nested Fixes #21832. --- man/systemd.automount.xml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/man/systemd.automount.xml b/man/systemd.automount.xml index 253ffebe3f..67c59e132c 100644 --- a/man/systemd.automount.xml +++ b/man/systemd.automount.xml @@ -63,6 +63,9 @@ 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 users' service managers. + + 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.) @@ -157,6 +160,7 @@ creating these directories. Takes an access mode in octal notation. Defaults to 0755. + TimeoutIdleSec= Configures an idle timeout. Once the mount has been From 5ee38adea4d590424fc840cd0e411a3cde73695e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Thu, 26 May 2022 13:14:08 +0200 Subject: [PATCH 5/7] man/shutdown: explain -h more Fixes #23401 --- man/shutdown.xml | 29 +++++++++++------------------ 1 file changed, 11 insertions(+), 18 deletions(-) diff --git a/man/shutdown.xml b/man/shutdown.xml index b07736ee68..97f33e802a 100644 --- a/man/shutdown.xml +++ b/man/shutdown.xml @@ -18,7 +18,7 @@ shutdown - Halt, power-off or reboot the machine + Halt, power off or reboot the machine @@ -33,8 +33,7 @@ Description - shutdown may be used to halt, power-off - or reboot the machine. + shutdown may be used to halt, power off, or reboot the machine. The first argument may be a time string (which is usually now). Optionally, this may be followed by a @@ -81,47 +80,41 @@ - Power-off the machine (the - default). + Power the machine off (the default). - Reboot the - machine. + Reboot the machine. - Equivalent to , - unless is specified. + The same as , but does not override the action to take if + it is "halt". E.g. shutdown --reboot -h means "poweroff", but shutdown + --halt -h means "halt". - Do not halt, power-off, reboot, just write - wall message. + Do not halt, power off, or reboot, but just write the wall message. - Do not send wall - message before - halt, power-off, reboot. + Do not send wall message before halt, power off, or reboot. - Cancel a pending shutdown. This may be used - to cancel the effect of an invocation of - shutdown with a time argument that is not - +0 or + Cancel a pending shutdown. This may be used to cancel the effect of an invocation of + shutdown with a time argument that is not +0 or now. From 8f2477715691f96b93d277b023f086203f76653f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Thu, 26 May 2022 14:04:52 +0200 Subject: [PATCH 6/7] man/sd-bus: discuss negative-return values and add example Fixes #22816. --- man/sd_bus_error-example.c | 18 ++++++++++ man/sd_bus_error.xml | 68 ++++++++++++++++++++++++++------------ 2 files changed, 65 insertions(+), 21 deletions(-) create mode 100644 man/sd_bus_error-example.c diff --git a/man/sd_bus_error-example.c b/man/sd_bus_error-example.c new file mode 100644 index 0000000000..abea13ca45 --- /dev/null +++ b/man/sd_bus_error-example.c @@ -0,0 +1,18 @@ +/* SPDX-License-Identifier: CC0-1.0 */ + +#include +#include +#include +#include + +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); +} diff --git a/man/sd_bus_error.xml b/man/sd_bus_error.xml index 5697ce7323..f4d0fea2e6 100644 --- a/man/sd_bus_error.xml +++ b/man/sd_bus_error.xml @@ -246,10 +246,15 @@ values in e, if e has been set with an error value before. Otherwise, it will return immediately. If the strings in e were set using sd_bus_error_set_const(), they will be shared. Otherwise, they will be - copied. Returns a converted errno-like, negative error code or 0. - Before this call, dst must be unset, i.e. either freshly initialized with + copied. Before this call, dst must be unset, i.e. either freshly initialized with NULL or reset using sd_bus_error_free(). + sd_bus_error_copy() generally returns 0 or a negative + errno-like value based on the input parameter e: + 0 if it was unset and a negative integer if it was set to some error, similarly to + sd_bus_error_set(). It may however also return an error generated internally, for + example -ENOMEM if a memory allocation fails. + sd_bus_error_move() is similar to sd_bus_error_copy(), but will move any error information from e into dst, resetting the former. This function cannot fail, as no new memory is allocated. Note that if @@ -286,6 +291,18 @@ to NULL. The structure may be reused afterwards. + + Reference ownership + + sd_bus_error is not reference-counted. Users should destroy resources held + by it by calling sd_bus_error_free(). 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 free3 the memory + held by the structure itself after freeing its contents with + sd_bus_error_free(). + + Return Value @@ -297,7 +314,8 @@ sd_bus_error_set_errnofv(), return 0 when the specified error value is 0, and a negative errno-like value corresponding to the error parameter otherwise. If an error occurs internally, one of the negative - error values listed below will be returned. + error values listed below will be returned. This allows those functions to be conveniently used in a + return statement, see the example below. sd_bus_error_get_errno() returns false when e is @@ -305,7 +323,9 @@ e->name otherwise. sd_bus_error_copy() and sd_bus_error_move() return a - negative error value converted from the source error, and zero if the error has not been set. + 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 return statement, see the + example below. sd_bus_error_is_set() returns a non-zero value when e and the @@ -316,32 +336,18 @@ sd_bus_error_has_names_sentinel() return a non-zero value when e is non-NULL and the name field is equal to one of the given names, zero otherwise. - - - - Reference ownership - sd_bus_error is not reference - counted. Users should destroy resources held by it by calling - sd_bus_error_free(). 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 free3 - the memory held by the structure itself after freeing its contents - with sd_bus_error_free(). Errors - Returned errors may indicate the following problems: + Return value may indicate the following problems in the invocation of the function itself: - -EINVAL - Error was already set in sd_bus_error structure when one - the error-setting functions was called. + Error was already set in the sd_bus_error structure when + one the error-setting functions was called. @@ -350,9 +356,29 @@ Memory allocation failed. + + On success, sd_bus_error_set(), sd_bus_error_setf(), + sd_bus_error_set_const(), sd_bus_error_set_errno(), + sd_bus_error_set_errnof(), sd_bus_error_set_errnofv(), + sd_bus_error_copy(), and sd_bus_error_move() will return a + negative converted errno-style value, or 0 if the error + parameter is NULL or unset. D-Bus errors are converted to the integral + errno-style value, and the mapping mechanism is extensible, see the discussion + above. This effectively means that almost any negative errno-style value can be + returned. + + Examples + + + Using the negative return value to propagate an error + + + + + From b72308d34440530df3bb8b6b3d272dfc303d1d37 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Thu, 26 May 2022 14:23:27 +0200 Subject: [PATCH 7/7] man/homectl: adjust man page to match code Fixes #22966. Since there are competing conventions, let's not change our code, but make the docs match what is implemented. --- man/homectl.xml | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/man/homectl.xml b/man/homectl.xml index dacbd17b1e..6fd5340370 100644 --- a/man/homectl.xml +++ b/man/homectl.xml @@ -686,7 +686,7 @@ CIPHER MODE - BITS + BYTES TYPE ALGORITHM SECONDS @@ -696,7 +696,12 @@ Configures various cryptographic parameters for the LUKS2 storage mechanism. See cryptsetup8 - for details on the specific attributes. + for details on the specific attributes. + + Note that homectl uses bytes for key size, like + /proc/crypto, but cryptsetup8 + uses bits.