From: Lennart Poettering <lennart@poettering.net>
Date: Thu, 9 Oct 2025 08:57:25 +0000 (+0200)
Subject: sd-varlink: add sd_varlink_is_connected()
X-Git-Tag: v259-rc1~307^2~1
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=73740ca2fcee5e3cec5a0656697aa87673737fd3;p=thirdparty%2Fsystemd.git

sd-varlink: add sd_varlink_is_connected()
---

diff --git a/man/rules/meson.build b/man/rules/meson.build
index 92dab90478d..95687afce83 100644
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@@ -912,6 +912,7 @@ manpages = [
    'sd_uid_get_sessions',
    'sd_uid_is_on_seat'],
   'HAVE_PAM'],
+ ['sd_varlink_is_connected', '3', ['sd_varlink_is_idle'], ''],
  ['sd_varlink_push_fd', '3', ['sd_varlink_push_dup_fd'], ''],
  ['sd_varlink_send', '3', ['sd_varlink_sendb', 'sd_varlink_sendbo'], ''],
  ['sd_varlink_server_new', '3', [], ''],
diff --git a/man/sd_varlink_is_connected.xml b/man/sd_varlink_is_connected.xml
new file mode 100644
index 00000000000..905cd3db19b
--- /dev/null
+++ b/man/sd_varlink_is_connected.xml
@@ -0,0 +1,93 @@
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
+
+<refentry id="sd_varlink_is_connected" xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <refentryinfo>
+    <title>sd_varlink_is_connected</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>sd_varlink_is_connected</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>sd_varlink_is_connected</refname>
+    <refname>sd_varlink_is_idle</refname>
+
+    <refpurpose>Query if a Varlink connection object is currently connected or idle</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>#include &lt;systemd/sd-varlink.h&gt;</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>int <function>sd_varlink_is_connected</function></funcdef>
+        <paramdef>sd_varlink *<parameter>link</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_varlink_is_idle</function></funcdef>
+        <paramdef>sd_varlink *<parameter>link</parameter></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><function>sd_varlink_is_connected()</function> checks whether the specified Varlink connection
+    object is currently connected or whether it has been fully disconnected already.</para>
+
+    <para><function>sd_varlink_is_idle()</function> checks whether the specified Varlink connection object is
+    currently connected but idle, i.e. may accept a method call for enqueuing (if client side of a Varlink
+    connection) or is waiting for more incoming method calls to arrive (if server side of a Varlink
+    connection).</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Return Value</title>
+
+    <para>If the connection is currently connected <function>sd_varlink_is_connected()</function> returns a
+    positive non-zero value. If disconnected it returns 0. If the connection currently is idle
+    <function>sd_varlink_is_idle()</function> returns a positive non-zero integer. If not, returns 0. On
+    failure, both functions return a negative <varname>errno</varname> error code.</para>
+
+    <refsect2>
+      <title>Errors</title>
+
+      <para>Returned errors may indicate the following problems:</para>
+
+      <variablelist>
+        <varlistentry>
+          <term><constant>-EINVAL</constant></term>
+
+          <listitem><para>The specified Varlink connection is invalid.</para></listitem>
+        </varlistentry>
+      </variablelist>
+    </refsect2>
+  </refsect1>
+
+  <xi:include href="libsystemd-pkgconfig.xml" />
+
+  <refsect1>
+    <title>History</title>
+    <para><function>sd_varlink_is_connected()</function> was added in version 259.</para>
+    <para><function>sd_varlink_is_idle()</function> was added in version 257.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+
+    <para><simplelist type="inline">
+      <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>sd-varlink</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
+    </simplelist></para>
+  </refsect1>
+
+</refentry>
diff --git a/src/libsystemd/libsystemd.sym b/src/libsystemd/libsystemd.sym
index 2cdb9152a78..d0e000bd0ca 100644
--- a/src/libsystemd/libsystemd.sym
+++ b/src/libsystemd/libsystemd.sym
@@ -1078,3 +1078,8 @@ global:
         sd_varlink_reset_fds;
         sd_varlink_server_listen_name;
 } LIBSYSTEMD_257;
+
+LIBSYSTEMD_259 {
+global:
+        sd_varlink_is_connected;
+} LIBSYSTEMD_258;
diff --git a/src/libsystemd/sd-varlink/sd-varlink.c b/src/libsystemd/sd-varlink/sd-varlink.c
index e0d5bf20aaa..2b2d4ecd627 100644
--- a/src/libsystemd/sd-varlink/sd-varlink.c
+++ b/src/libsystemd/sd-varlink/sd-varlink.c
@@ -1684,6 +1684,14 @@ _public_ int sd_varlink_is_idle(sd_varlink *v) {
         return IN_SET(v->state, VARLINK_DISCONNECTED, VARLINK_IDLE_CLIENT, VARLINK_IDLE_SERVER);
 }
 
+_public_ int sd_varlink_is_connected(sd_varlink *v) {
+        assert_return(v, -EINVAL);
+
+        /* Returns true if the connection is still connected */
+
+        return v->state != VARLINK_DISCONNECTED;
+}
+
 _public_ int sd_varlink_get_fd(sd_varlink *v) {
 
         assert_return(v, -EINVAL);
diff --git a/src/systemd/sd-varlink.h b/src/systemd/sd-varlink.h
index 27ad5bf7f8d..cf279bd551d 100644
--- a/src/systemd/sd-varlink.h
+++ b/src/systemd/sd-varlink.h
@@ -110,6 +110,7 @@ int sd_varlink_process(sd_varlink *v);
 int sd_varlink_wait(sd_varlink *v, uint64_t timeout);
 
 int sd_varlink_is_idle(sd_varlink *v);
+int sd_varlink_is_connected(sd_varlink *v);
 
 int sd_varlink_flush(sd_varlink *v);
 int sd_varlink_close(sd_varlink *v);