man: document fd ownership for sd-bus fd marshalling

Fixes: #8003

man/sd_bus_message_append.xml

@@ -146,8 +146,10 @@
       </tgroup>
     </table>
 
-    <para>For types "s" and "g" (unicode string or signature), the pointer may be
-    <constant>NULL</constant>, which is equivalent to an empty string. See
+    <para>For types <literal>s</literal> and <literal>g</literal> (unicode string or signature), the pointer
+    may be <constant>NULL</constant>, which is equivalent to an empty string. For <literal>h</literal> (UNIX
+    file descriptor), the descriptor is duplicated by this call and the passed descriptor stays in possession
+    of the caller. See
     <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>
     for the precise interpretation of those and other types.</para>
   </refsect1>

man/sd_bus_message_read.xml

@@ -73,7 +73,10 @@
     should be read. See the table below for a complete list of allowed arguments and their types. Note that,
     if the basic type is a pointer (e.g., <type>const char *</type> in the case of a string), the argument is
     a pointer to a pointer, and also the pointer value that is written is only borrowed and the contents must
-    be copied if they are to be used after the end of the messages lifetime.</para>
+    be copied if they are to be used after the end of the messages lifetime. If the type is
+    <literal>h</literal> (UNIX file descriptor), the descriptor is not duplicated by this call and the
+    returned descriptor remains in possession of the message object, and needs to be duplicated by the caller
+    in order to keep an open reference to it after the message object is freed.</para>
 
     <para>Each argument may also be <constant>NULL</constant>, in which case the value is read and ignored.
     </para>
@@ -228,6 +231,15 @@ const char *s, *t, *u;
 
 sd_bus_message_read(m, "a{is}", 3, &amp;i, &amp;s, &amp;j, &amp;t, &amp;k, &amp;u);
      </programlisting>
+
+     <para>Read a single file descriptor, and duplicate it in order to keep it open after the message is
+     freed.</para>
+
+     <programlisting>sd_bus_message *m;
+int fd, fd_copy;
+
+sd_bus_message_read(m, "h", &amp;fd);
+fd_copy = fcntl(fd, FD_DUPFD_CLOEXEC, 3);</programlisting>
   </refsect1>
 
   <refsect1>

man/sd_bus_message_read_basic.xml

@@ -52,17 +52,19 @@
     </para>
 
     <para>
-      If <parameter>p</parameter> is not <constant>NULL</constant>, it should contain
-      a pointer to an appropriate object. For example, if <parameter>type</parameter>
-      is <constant>'y'</constant>, the object passed in <parameter>p</parameter>
-      should have type <type>uint8_t *</type>. If <parameter>type</parameter> is
-      <constant>'s'</constant>, the object passed in <parameter>p</parameter> should
-      have type <type>const char **</type>. Note that, if the basic type is a pointer
-      (e.g., <type>const char *</type> in the case of a string), the pointer is only
-      borrowed and the contents must be copied if they are to be used after the end
-      of the messages lifetime. Similarly, during the lifetime of such a pointer, the
-      message must not be modified. See the table below for a complete list of allowed
-      types.
+      If <parameter>p</parameter> is not <constant>NULL</constant>, it should contain a pointer to an
+      appropriate object. For example, if <parameter>type</parameter> is <constant>'y'</constant>, the object
+      passed in <parameter>p</parameter> should have type <type>uint8_t *</type>. If
+      <parameter>type</parameter> is <constant>'s'</constant>, the object passed in <parameter>p</parameter>
+      should have type <type>const char **</type>. Note that, if the basic type is a pointer (e.g.,
+      <type>const char *</type> in the case of a string), the pointer is only borrowed and the contents must
+      be copied if they are to be used after the end of the messages lifetime. Similarly, during the lifetime
+      of such a pointer, the message must not be modified. If <parameter>type</parameter> is
+      <constant>'h'</constant> (UNIX file descriptor), the descriptor is not duplicated by this call and the
+      returned descriptor remains in possession of the message object, and needs to be duplicated by the caller
+      in order to keep an open reference to it after the message object is freed (for example by calling
+      <literal>fcntl(fd, FD_DUPFD_CLOEXEC, 3)</literal>). See the table below for a complete list of
+      allowed types.
     </para>
 
     <table id='format-specifiers'>

src/home/homed-home.c

@@ -1045,7 +1045,7 @@ static int home_start_work(Home *h, const char *verb, UserRecord *hr, UserRecord
                 homework = getenv("SYSTEMD_HOMEWORK_PATH") ?: SYSTEMD_HOMEWORK_PATH;
 
                 execl(homework, homework, verb, NULL);
-                log_error_errno(errno, "Failed to invoke " SYSTEMD_HOMEWORK_PATH ": %m");
+                log_error_errno(errno, "Failed to invoke %s: %m", homework);
                 _exit(EXIT_FAILURE);
         }
 

src/resolve/resolved-dns-transaction.c

@@ -364,6 +364,14 @@ void dns_transaction_complete(DnsTransaction *t, DnsTransactionState state) {
         dns_transaction_gc(t);
 }
 
+static void dns_transaction_complete_errno(DnsTransaction *t, int error) {
+        assert(t);
+        assert(error != 0);
+
+        t->answer_errno = abs(error);
+        dns_transaction_complete(t, DNS_TRANSACTION_ERRNO);
+}
+
 static int dns_transaction_pick_server(DnsTransaction *t) {
         DnsServer *server;
 
@@ -415,10 +423,8 @@ static void dns_transaction_retry(DnsTransaction *t, bool next_server) {
                 dns_scope_next_dns_server(t->scope);
 
         r = dns_transaction_go(t);
-        if (r < 0) {
-                t->answer_errno = -r;
-                dns_transaction_complete(t, DNS_TRANSACTION_ERRNO);
-        }
+        if (r < 0)
+                dns_transaction_complete_errno(t, r);
 }
 
 static int dns_transaction_maybe_restart(DnsTransaction *t) {
@@ -466,10 +472,8 @@ static void on_transaction_stream_error(DnsTransaction *t, int error) {
                 dns_transaction_retry(t, true);
                 return;
         }
-        if (error != 0) {
-                t->answer_errno = error;
-                dns_transaction_complete(t, DNS_TRANSACTION_ERRNO);
-        }
+        if (error != 0)
+                dns_transaction_complete_errno(t, error);
 }
 
 static int dns_transaction_on_stream_packet(DnsTransaction *t, DnsPacket *p) {
@@ -836,8 +840,7 @@ static void dns_transaction_process_dnssec(DnsTransaction *t) {
         return;
 
 fail:
-        t->answer_errno = -r;
-        dns_transaction_complete(t, DNS_TRANSACTION_ERRNO);
+        dns_transaction_complete_errno(t, r);
 }
 
 static int dns_transaction_has_positive_answer(DnsTransaction *t, DnsAnswerFlags *flags) {
@@ -1169,8 +1172,7 @@ void dns_transaction_process_reply(DnsTransaction *t, DnsPacket *p) {
         return;
 
 fail:
-        t->answer_errno = -r;
-        dns_transaction_complete(t, DNS_TRANSACTION_ERRNO);
+        dns_transaction_complete_errno(t, r);
 }
 
 static int on_dns_packet(sd_event_source *s, int fd, uint32_t revents, void *userdata) {
@@ -1182,7 +1184,7 @@ static int on_dns_packet(sd_event_source *s, int fd, uint32_t revents, void *use
         assert(t->scope);
 
         r = manager_recv(t->scope->manager, fd, DNS_PROTOCOL_DNS, &p);
-        if (ERRNO_IS_DISCONNECT(-r)) {
+        if (ERRNO_IS_DISCONNECT(r)) {
                 usec_t usec;
 
                 /* UDP connection failures get reported via ICMP and then are possibly delivered to us on the
@@ -1196,8 +1198,7 @@ static int on_dns_packet(sd_event_source *s, int fd, uint32_t revents, void *use
                 return 0;
         }
         if (r < 0) {
-                dns_transaction_complete(t, DNS_TRANSACTION_ERRNO);
-                t->answer_errno = -r;
+                dns_transaction_complete_errno(t, r);
                 return 0;
         }
         if (r == 0)
@@ -1736,7 +1737,7 @@ int dns_transaction_go(DnsTransaction *t) {
                 dns_transaction_complete(t, DNS_TRANSACTION_RR_TYPE_UNSUPPORTED);
                 return 0;
         }
-        if (t->scope->protocol == DNS_PROTOCOL_LLMNR && ERRNO_IS_DISCONNECT(-r)) {
+        if (t->scope->protocol == DNS_PROTOCOL_LLMNR && ERRNO_IS_DISCONNECT(r)) {
                 /* On LLMNR, if we cannot connect to a host via TCP when doing reverse lookups. This means we cannot
                  * answer this request with this protocol. */
                 dns_transaction_complete(t, DNS_TRANSACTION_NOT_FOUND);
@@ -1833,7 +1834,7 @@ static int dns_transaction_add_dnssec_transaction(DnsTransaction *t, DnsResource
 
         r = set_ensure_put(&t->dnssec_transactions, NULL, aux);
         if (r < 0)
-                return r;;
+                return r;
 
         r = set_ensure_put(&aux->notify_transactions, NULL, t);
         if (r < 0) {

src/tmpfiles/tmpfiles.c

@@ -3402,7 +3402,7 @@ static int run(int argc, char *argv[]) {
                 }
         }
 
-        if (ERRNO_IS_RESOURCE(-r))
+        if (ERRNO_IS_RESOURCE(r))
                 return r;
         if (invalid_config)
                 return EX_DATAERR;