man/sd_bus_message_new_signal.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
   5
   6 <refentry id="sd_bus_message_new_signal"
   7           xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>sd_bus_message_new_signal</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>sd_bus_message_new_signal</refentrytitle>
  16     <manvolnum>3</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>sd_bus_message_new_signal</refname>
  21
  22     <refpurpose>Create a signal message</refpurpose>
  23   </refnamediv>
  24
  25   <refsynopsisdiv>
  26     <funcsynopsis>
  27       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  28
  29       <funcprototype>
  30         <funcdef>int sd_bus_message_new_signal</funcdef>
  31         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  32         <paramdef>sd_bus_message **<parameter>m</parameter></paramdef>
  33         <paramdef>const char *<parameter>path</parameter></paramdef>
  34         <paramdef>const char *<parameter>interface</parameter></paramdef>
  35         <paramdef>const char *<parameter>member</parameter></paramdef>
  36       </funcprototype>
  37     </funcsynopsis>
  38   </refsynopsisdiv>
  39
  40   <refsect1>
  41     <title>Description</title>
  42
  43     <para>The <function>sd_bus_message_new_signal()</function> function creates a new bus message
  44     object that encapsulates a D-Bus signal, and returns it in the <parameter>m</parameter> output
  45     parameter. The signal will be sent to path <parameter>path</parameter>, on the interface
  46     <parameter>interface</parameter>, member <parameter>member</parameter>. When this message is
  47     sent, no reply is expected. See
  48     <citerefentry><refentrytitle>sd_bus_message_new_call</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  49     for a short description of the meaning of the <parameter>path</parameter>,
  50     <parameter>interface</parameter>, and <parameter>member</parameter> parameters.
  51     </para>
  52   </refsect1>
  53
  54   <refsect1>
  55     <title>Return Value</title>
  56
  57     <para>This function returns 0 if the message object was successfully created, and a negative
  58     errno-style error code otherwise.</para>
  59
  60     <refsect2>
  61       <title>Errors</title>
  62
  63       <para>Returned errors may indicate the following problems:</para>
  64
  65       <variablelist>
  66         <varlistentry>
  67           <term><constant>-EINVAL</constant></term>
  68
  69           <listitem><para>The output parameter <parameter>m</parameter> is
  70           <constant>NULL</constant>.</para>
  71
  72           <para>The <parameter>path</parameter> parameter is not a valid D-Bus path
  73           (<literal>/an/object/path</literal>), the <parameter>interface</parameter> parameter is not
  74           a valid D-Bus interface name (<literal>an.interface.name</literal>), or the
  75           <parameter>member</parameter> parameter is not a valid D-Bus member
  76           (<literal>Name</literal>).</para></listitem>
  77         </varlistentry>
  78
  79         <varlistentry>
  80           <term><constant>-ENOTCONN</constant></term>
  81
  82           <listitem><para>The bus parameter <parameter>bus</parameter> is <constant>NULL</constant> or
  83           the bus is not connected.</para></listitem>
  84         </varlistentry>
  85
  86         <varlistentry>
  87           <term><constant>-ENOMEM</constant></term>
  88
  89           <listitem><para>Memory allocation failed.</para></listitem>
  90         </varlistentry>
  91       </variablelist>
  92     </refsect2>
  93   </refsect1>
  94
  95   <xi:include href="libsystemd-pkgconfig.xml" />
  96
  97   <refsect1>
  98     <title>Examples</title>
  99
 100     <example>
 101       <title>Send a simple signal</title>
 102
 103       <programlisting><xi:include href="send-unit-files-changed.c" parse="text" /></programlisting>
 104
 105       <para>This function in systemd sources is used to emit the
 106       <literal>UnitFilesChanged</literal> signal when the unit files have been changed.
 107       </para>
 108     </example>
 109   </refsect1>
 110
 111   <refsect1>
 112     <title>See Also</title>
 113
 114     <para>
 115       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 116       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 117     </para>
 118   </refsect1>
 119
 120 </refentry>