sd-daemon: add sd_pid_notifyf_with_fds()

I guess it was only a question of time until we need to add the final
frontier of notification functions: one that combines the features of
all the others:

1. specifiying a source PID
2. taking a list of fds to send along
3. accepting a format string for the status string

Hence, let's add it.

2 files changed, 24 insertions, 7 deletions

diff --git a/man/rules/meson.build b/man/rules/meson.build
index ca3b471281..13d2bd9b58 100644
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@@ -808,7 +808,8 @@ manpages = [
    'sd_notifyf',
    'sd_pid_notify',
    'sd_pid_notify_with_fds',
-   'sd_pid_notifyf'],
+   'sd_pid_notifyf',
+   'sd_pid_notifyf_with_fds'],
   ''],
  ['sd_path_lookup', '3', ['sd_path_lookup_strv'], ''],
  ['sd_pid_get_owner_uid',
diff --git a/man/sd_notify.xml b/man/sd_notify.xml
index f93542e329..b82d145860 100644
--- a/man/sd_notify.xml
+++ b/man/sd_notify.xml
@@ -22,6 +22,7 @@
     <refname>sd_pid_notify</refname>
     <refname>sd_pid_notifyf</refname>
     <refname>sd_pid_notify_with_fds</refname>
+    <refname>sd_pid_notifyf_with_fds</refname>
     <refname>sd_notify_barrier</refname>
     <refpurpose>Notify service manager about start-up completion and other service status changes</refpurpose>
   </refnamediv>
@@ -68,6 +69,16 @@
       </funcprototype>
 
       <funcprototype>
+        <funcdef>int <function>sd_pid_notifyf_with_fds</function></funcdef>
+        <paramdef>pid_t <parameter>pid</parameter></paramdef>
+        <paramdef>int <parameter>unset_environment</parameter></paramdef>
+        <paramdef>const int *<parameter>fds</parameter></paramdef>
+        <paramdef>size_t <parameter>n_fds</parameter></paramdef>
+        <paramdef>const char *<parameter>format</parameter></paramdef>
+        <paramdef>…</paramdef>
+      </funcprototype>
+
+      <funcprototype>
         <funcdef>int <function>sd_notify_barrier</function></funcdef>
         <paramdef>int <parameter>unset_environment</parameter></paramdef>
         <paramdef>uint64_t <parameter>timeout</parameter></paramdef>
@@ -326,12 +337,12 @@
     able to properly attribute the message to the unit, and thus will ignore it, even if
     <varname>NotifyAccess=</varname><option>all</option> is set for it.</para>
 
-    <para>Hence, to eliminate all race conditions involving lookup of the client's unit and attribution of notifications
-    to units correctly, <function>sd_notify_barrier()</function> may be used. This call acts as a synchronization point
-    and ensures all notifications sent before this call have been picked up by the service manager when it returns
-    successfully. Use of <function>sd_notify_barrier()</function> is needed for clients which are not invoked by the
-    service manager, otherwise this synchronization mechanism is unnecessary for attribution of notifications to the
-    unit.</para>
+    <para>Hence, to eliminate all race conditions involving lookup of the client's unit and attribution of
+    notifications to units correctly, <function>sd_notify_barrier()</function> may be used. This call acts as
+    a synchronization point and ensures all notifications sent before this call have been picked up by the
+    service manager when it returns successfully. Use of <function>sd_notify_barrier()</function> is needed
+    for clients which are not invoked by the service manager, otherwise this synchronization mechanism is
+    unnecessary for attribution of notifications to the unit.</para>
 
     <para><function>sd_notifyf()</function> is similar to <function>sd_notify()</function> but takes a
     <function>printf()</function>-like format string plus arguments.</para>
@@ -352,6 +363,11 @@
     that file descriptors sent to the service manager on a message without <literal>FDSTORE=1</literal> are
     immediately closed on reception.</para>
 
+    <para><function>sd_pid_notifyf_with_fds()</function> is a combination of
+    <function>sd_pid_notify_with_fds()</function> and <function>sd_notifyf()</function>, i.e. it accepts both
+    a PID and a set of file descriptors as input, and processes a format string to generate the state
+    string.</para>
+
     <para><function>sd_notify_barrier()</function> allows the caller to synchronize against reception of
     previously sent notification messages and uses the <varname>BARRIER=1</varname> command. It takes a
     relative <varname>timeout</varname> value in microseconds which is passed to