man: add missing description for udev_enumerate_new functions

Add proper description section for udev_enumerate_new(), udev_enumerate_ref(),
and udev_enumerate_unref() functions. The description matches the source code
comments for consistency.

Signed-off-by: Osama Abdelkader <osama.abdelkader@gmail.com>

docs/BOOT.md

@@ -67,7 +67,7 @@ options    root=PARTUUID=084917b7-8be2-4e86-838d-f771a9902e08
 title      My kernel with initrd
 linux      /bzImage
 initrd     /initrd.img
-options    root=PARTUUID=084917b7-8be2-4e86-838d-f771a9902e08 quiet`
+options    root=PARTUUID=084917b7-8be2-4e86-838d-f771a9902e08 quiet
 ```
 
 

man/pam_systemd.xml

@@ -159,6 +159,19 @@
           </tgroup>
         </table>
 
+        <para>If no session class is specified via either the PAM module option or via the
+        <varname>$XDG_SESSION_CLASS</varname> environment variable, the class is automatically chosen, depending on
+        various session parameters, such as the session type (if known), whether the session has a TTY or X11
+        display, and the user disposition. Note that various tools allow setting the session class for newly
+        allocated PAM sessions explicitly by means of the <varname>$XDG_SESSION_CLASS</varname> environment variable.
+        For example, classic UNIX cronjobs support environment variable assignments (see
+        <citerefentry project='man-pages'><refentrytitle>crontab</refentrytitle><manvolnum>5</manvolnum></citerefentry>),
+        which may be used to choose between the <constant>background</constant> and
+        <constant>background-light</constant> session class individually per cronjob, or
+        <command>run0 --setenv=XDG_SESSION_CLASS=user-light</command> may be used
+        to choose between <constant>user</constant> and <constant>user-light</constant> for invoked privileged sessions.
+        </para>
+
         <xi:include href="version-info.xml" xpointer="v197"/></listitem>
       </varlistentry>
 

man/udev_enumerate_new.xml

@@ -49,11 +49,16 @@
     </funcsynopsis>
   </refsynopsisdiv>
 
-  <!--<refsect1>
+  <refsect1>
     <title>Description</title>
 
-    <para>XXX: Add short description.</para>
-  </refsect1>-->
+    <para><function>udev_enumerate_new()</function> creates an enumeration context to scan /sys.</para>
+
+    <para><function>udev_enumerate_ref()</function> takes a reference of an enumeration context.</para>
+
+    <para><function>udev_enumerate_unref()</function> drops a reference of an enumeration context. If the refcount reaches zero,
+    all resources of the enumeration context will be released.</para>
+  </refsect1>
 
   <refsect1>
     <title>Return Value</title>

src/login/pam_systemd.c

@@ -921,11 +921,13 @@ static void session_context_mangle(
         assert(c);
         assert(ur);
 
+        /* The session class can be overridden via the PAM environment, and we try to honor that selection. */
         if (streq_ptr(c->service, "systemd-user")) {
                 /* If we detect that we are running in the "systemd-user" PAM stack, then let's patch the class to
                  * 'manager' if not set, simply for robustness reasons. */
                 c->type = "unspecified";
-                c->class = IN_SET(user_record_disposition(ur), USER_INTRINSIC, USER_SYSTEM, USER_DYNAMIC) ?
+                if (isempty(c->class))
+                        c->class = IN_SET(user_record_disposition(ur), USER_INTRINSIC, USER_SYSTEM, USER_DYNAMIC) ?
                         "manager-early" : "manager";
                 c->tty = NULL;
 
@@ -942,14 +944,16 @@ static void session_context_mangle(
                  * (as they otherwise even try to update it!) — but cron doesn't actually allocate a TTY for its forked
                  * off processes.) */
                 c->type = "unspecified";
-                c->class = "background";
+                if (isempty(c->class))
+                        c->class = "background";
                 c->tty = NULL;
 
         } else if (streq_ptr(c->tty, "ssh")) {
                 /* ssh has been setting PAM_TTY to "ssh" (for the same reason as cron does this, see above. For further
                  * details look for "PAM_TTY_KLUDGE" in the openssh sources). */
                 c->type = "tty";
-                c->class = "user";
+                if (isempty(c->class))
+                        c->class = "user";
                 c->tty = NULL; /* This one is particularly sad, as this means that ssh sessions — even though
                                * usually associated with a pty — won't be tracked by their tty in
                                * logind. This is because ssh does the PAM session registration early for new
@@ -1708,9 +1712,10 @@ static int close_osc_context(pam_handle_t *handle) {
         if (r < 0)
                 return pam_syslog_errno(handle, LOG_ERR, r, "Failed to prepare OSC sequence: %m");
 
+        /* When we are closing things, the TTY might not take our writes anymore. Accept that gracefully. */
         r = loop_write(fd, osc, SIZE_MAX);
         if (r < 0)
-                return pam_syslog_errno(handle, LOG_ERR, r, "Failed to write OSC sequence to TTY: %m");
+                pam_syslog_errno(handle, LOG_DEBUG, r, "Failed to write OSC sequence to TTY, ignoring: %m");
 
         return PAM_SUCCESS;
 }

test/units/TEST-64-UDEV-STORAGE.sh

@@ -836,7 +836,7 @@ EOF
     btrfs filesystem show
     helper_check_device_symlinks
     helper_check_device_units
-    wipefs -a -f "${devices[0]}"
+    udevadm lock --timeout=30 --device="${devices[0]}" wipefs -a "${devices[0]}"
     udevadm wait --settle --timeout=30 --removed /dev/disk/by-partlabel/diskpart{1..4}
 
     echo "Multiple devices: using disks, data: raid10, metadata: raid10, mixed mode"