From 4054d76151678edc7c6b77ebdebb9a32d1dc11c9 Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Fri, 14 Apr 2023 17:48:47 +0200
Subject: 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.
---
 man/sd_notify.xml | 28 ++++++++++++++++++++++------
 1 file changed, 22 insertions(+), 6 deletions(-)

(limited to 'man/sd_notify.xml')

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>
@@ -67,6 +68,16 @@
         <paramdef>unsigned <parameter>n_fds</parameter></paramdef>
       </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>
@@ -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
-- 
cgit v1.2.1