2018-07-25 00:23:29 +03:00
<?xml version='1.0'?>
2019-03-14 16:40:58 +03:00
< !DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
2023-12-25 17:48:33 +03:00
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
2020-11-09 07:23:58 +03:00
<!-- SPDX - License - Identifier: LGPL - 2.1 - or - later -->
2018-07-25 00:23:29 +03:00
<refentry id= "sd_bus_message_new_signal"
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo >
<title > sd_bus_message_new_signal</title>
<productname > systemd</productname>
</refentryinfo>
<refmeta >
<refentrytitle > sd_bus_message_new_signal</refentrytitle>
<manvolnum > 3</manvolnum>
</refmeta>
<refnamediv >
<refname > sd_bus_message_new_signal</refname>
2022-10-31 23:11:48 +03:00
<refname > sd_bus_message_new_signal_to</refname>
2018-07-25 00:23:29 +03:00
<refpurpose > Create a signal message</refpurpose>
</refnamediv>
<refsynopsisdiv >
<funcsynopsis >
<funcsynopsisinfo > #include < systemd/sd-bus.h> </funcsynopsisinfo>
<funcprototype >
<funcdef > int sd_bus_message_new_signal</funcdef>
<paramdef > sd_bus *<parameter > bus</parameter> </paramdef>
<paramdef > sd_bus_message **<parameter > m</parameter> </paramdef>
<paramdef > const char *<parameter > path</parameter> </paramdef>
<paramdef > const char *<parameter > interface</parameter> </paramdef>
<paramdef > const char *<parameter > member</parameter> </paramdef>
</funcprototype>
2022-10-31 23:11:48 +03:00
<funcprototype >
<funcdef > int sd_bus_message_new_signal_to</funcdef>
<paramdef > sd_bus *<parameter > bus</parameter> </paramdef>
<paramdef > sd_bus_message **<parameter > m</parameter> </paramdef>
<paramdef > const char *<parameter > destination</parameter> </paramdef>
<paramdef > const char *<parameter > path</parameter> </paramdef>
<paramdef > const char *<parameter > interface</parameter> </paramdef>
<paramdef > const char *<parameter > member</parameter> </paramdef>
</funcprototype>
2018-07-25 00:23:29 +03:00
</funcsynopsis>
</refsynopsisdiv>
<refsect1 >
<title > Description</title>
<para > The <function > sd_bus_message_new_signal()</function> function creates a new bus message
object that encapsulates a D-Bus signal, and returns it in the <parameter > m</parameter> output
parameter. The signal will be sent to path <parameter > path</parameter> , on the interface
<parameter > interface</parameter> , member <parameter > member</parameter> . When this message is
2018-07-26 21:00:36 +03:00
sent, no reply is expected. See
2024-11-11 22:10:00 +03:00
<citerefentry > <refentrytitle > sd_bus_message_new_method_call</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry>
2018-07-26 21:00:36 +03:00
for a short description of the meaning of the <parameter > path</parameter> ,
<parameter > interface</parameter> , and <parameter > member</parameter> parameters.
</para>
2022-10-31 23:11:48 +03:00
<para > <function > sd_bus_message_new_signal_to()</function> is a shorthand for creating a new bus message
2023-02-09 16:30:43 +03:00
to a specific destination. It's behavior is similar to calling
<function > sd_bus_message_new_signal()</function> followed by calling
<citerefentry > <refentrytitle > sd_bus_message_set_destination</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> .
</para>
2018-07-25 00:23:29 +03:00
</refsect1>
<refsect1 >
<title > Return Value</title>
<para > This function returns 0 if the message object was successfully created, and a negative
errno-style error code otherwise.</para>
2019-03-21 16:53:00 +03:00
<refsect2 >
<title > Errors</title>
2018-07-25 00:23:29 +03:00
2019-03-21 16:53:00 +03:00
<para > Returned errors may indicate the following problems:</para>
2018-07-25 00:23:29 +03:00
2019-03-21 16:53:00 +03:00
<variablelist >
<varlistentry >
<term > <constant > -EINVAL</constant> </term>
2018-07-25 00:23:29 +03:00
2019-03-21 16:53:00 +03:00
<listitem > <para > The output parameter <parameter > m</parameter> is
<constant > NULL</constant> .</para>
2018-07-25 00:23:29 +03:00
2019-03-21 16:53:00 +03:00
<para > The <parameter > path</parameter> parameter is not a valid D-Bus path
(<literal > /an/object/path</literal> ), the <parameter > interface</parameter> parameter is not
a valid D-Bus interface name (<literal > an.interface.name</literal> ), or the
<parameter > member</parameter> parameter is not a valid D-Bus member
(<literal > Name</literal> ).</para> </listitem>
</varlistentry>
2018-07-25 00:23:29 +03:00
2019-03-21 16:53:00 +03:00
<varlistentry >
<term > <constant > -ENOTCONN</constant> </term>
2018-07-25 00:23:29 +03:00
2019-03-21 16:53:00 +03:00
<listitem > <para > The bus parameter <parameter > bus</parameter> is <constant > NULL</constant> or
the bus is not connected.</para> </listitem>
</varlistentry>
2018-07-25 00:23:29 +03:00
2019-03-21 16:53:00 +03:00
<varlistentry >
<term > <constant > -ENOMEM</constant> </term>
2018-07-25 00:23:29 +03:00
2019-03-21 16:53:00 +03:00
<listitem > <para > Memory allocation failed.</para> </listitem>
</varlistentry>
</variablelist>
</refsect2>
2018-07-25 00:23:29 +03:00
</refsect1>
<xi:include href= "libsystemd-pkgconfig.xml" />
<refsect1 >
<title > Examples</title>
<example >
<title > Send a simple signal</title>
<programlisting > <xi:include href= "send-unit-files-changed.c" parse= "text" /> </programlisting>
<para > This function in systemd sources is used to emit the
<literal > UnitFilesChanged</literal> signal when the unit files have been changed.
</para>
</example>
</refsect1>
<refsect1 >
<title > See Also</title>
2023-12-22 21:09:32 +03:00
<para > <simplelist type= "inline" >
<member > <citerefentry > <refentrytitle > systemd</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry> </member>
<member > <citerefentry > <refentrytitle > sd-bus</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> </member>
<member > <citerefentry > <refentrytitle > sd_bus_emit_signal</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> </member>
<member > <citerefentry > <refentrytitle > sd_bus_message_set_destination</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> </member>
</simplelist> </para>
2018-07-25 00:23:29 +03:00
</refsect1>
</refentry>