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 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. 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 + + + + + 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. diff --git a/man/systemd.automount.xml b/man/systemd.automount.xml index da35a7d26b..67c59e132c 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 @@ -39,13 +38,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 @@ -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,11 @@ 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. + + 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.) @@ -78,12 +77,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. @@ -161,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 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