man/sd_bus_message_new_signal.xml


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139

<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->

<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>
    <refname>sd_bus_message_new_signal_to</refname>

    <refpurpose>Create a signal message</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</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>

      <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>
    </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
    sent, no reply is expected. See
    <citerefentry><refentrytitle>sd_bus_message_new_method_call</refentrytitle><manvolnum>1</manvolnum></citerefentry>
    for a short description of the meaning of the <parameter>path</parameter>,
    <parameter>interface</parameter>, and <parameter>member</parameter> parameters.
    </para>

    <para><function>sd_bus_message_new_signal_to()</function> is a shorthand for creating a new bus message
    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>
  </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>

    <refsect2>
      <title>Errors</title>

      <para>Returned errors may indicate the following problems:</para>

      <variablelist>
        <varlistentry>
          <term><constant>-EINVAL</constant></term>

          <listitem><para>The output parameter <parameter>m</parameter> is
          <constant>NULL</constant>.</para>

          <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>

        <varlistentry>
          <term><constant>-ENOTCONN</constant></term>

          <listitem><para>The bus parameter <parameter>bus</parameter> is <constant>NULL</constant> or
          the bus is not connected.</para></listitem>
        </varlistentry>

        <varlistentry>
          <term><constant>-ENOMEM</constant></term>

          <listitem><para>Memory allocation failed.</para></listitem>
        </varlistentry>
      </variablelist>
    </refsect2>
  </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>

    <para>
      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_bus_emit_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>
      <citerefentry><refentrytitle>sd_bus_message_set_destination</refentrytitle><manvolnum>3</manvolnum></citerefentry>
    </para>
  </refsect1>

</refentry>