--- /dev/null
+#include <stdio.h>
+#include <systemd/sd-id128.h>
+
+#define OUR_APPLICATION_ID SD_ID128_MAKE(c2,73,27,73,23,db,45,4e,a6,3b,b9,6e,79,b5,3e,97)
+
+int main(int argc, char *argv[]) {
+ sd_id128_t id;
+ sd_id128_get_machine_app_specific(OUR_APPLICATION_ID, &id);
+ printf("Our application ID: " SD_ID128_FORMAT_STR "\n", SD_ID128_FORMAT_VAL(id));
+ return 0;
+}
--- /dev/null
+#include <stdio.h>
+#include <string.h>
+#include <systemd/sd-journal.h>
+
+int main(int argc, char *argv[]) {
+ sd_journal *j;
+ const void *d;
+ size_t l;
+ int r;
+
+ r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY);
+ if (r < 0) {
+ fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
+ return 1;
+ }
+ r = sd_journal_query_unique(j, "_SYSTEMD_UNIT");
+ if (r < 0) {
+ fprintf(stderr, "Failed to query journal: %s\n", strerror(-r));
+ return 1;
+ }
+ SD_JOURNAL_FOREACH_UNIQUE(j, d, l)
+ printf("%.*s\n", (int) l, (const char*) d);
+ sd_journal_close(j);
+ return 0;
+}
--- /dev/null
+#include <stdio.h>
+#include <string.h>
+#include <unistd.h>
+#include <sys/types.h>
+
+#include <systemd/sd-bus.h>
+#define _cleanup_(f) __attribute__((cleanup(f)))
+
+/* This is equivalent to:
+ * busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 \
+ * org.freedesktop.systemd1.Manager GetUnitByPID $$
+ *
+ * Compile with 'cc -lsystemd print-unit-path.c'
+ */
+
+#define DESTINATION "org.freedesktop.systemd1"
+#define PATH "/org/freedesktop/systemd1"
+#define INTERFACE "org.freedesktop.systemd1.Manager"
+#define MEMBER "GetUnitByPID"
+
+static int log_error(int error, const char *message) {
+ fprintf(stderr, "%s: %s\n", message, strerror(-error));
+ return error;
+}
+
+static int print_unit_path(sd_bus *bus) {
+ _cleanup_(sd_bus_message_unrefp) sd_bus_message *m = NULL;
+ _cleanup_(sd_bus_error_free) sd_bus_error error = SD_BUS_ERROR_NULL;
+ _cleanup_(sd_bus_message_unrefp) sd_bus_message *reply = NULL;
+ int r;
+
+ r = sd_bus_message_new_method_call(bus, &m,
+ DESTINATION, PATH, INTERFACE, MEMBER);
+ if (r < 0)
+ return log_error(r, "Failed to create bus message");
+
+ r = sd_bus_message_append(m, "u", (unsigned) getpid());
+ if (r < 0)
+ return log_error(r, "Failed to append to bus message");
+
+ r = sd_bus_call(bus, m, -1, &error, &reply);
+ if (r < 0)
+ return log_error(r, "Call failed");
+
+ const char *ans;
+ r = sd_bus_message_read(reply, "o", &ans);
+ if (r < 0)
+ return log_error(r, "Failed to read reply");
+
+ printf("Unit path is \"%s\".\n", ans);
+
+ return 0;
+}
+
+int main(int argc, char **argv) {
+ _cleanup_(sd_bus_flush_close_unrefp) sd_bus *bus = NULL;
+ int r;
+
+ r = sd_bus_open_system(&bus);
+ if (r < 0)
+ return log_error(r, "Failed to acquire bus");
+
+ print_unit_path(bus);
+}
'sd_bus_open_system',
'sd_bus_open_system_machine',
'sd_bus_open_system_remote',
- 'sd_bus_open_user'],
+ 'sd_bus_open_system_with_description',
+ 'sd_bus_open_user',
+ 'sd_bus_open_user_with_description',
+ 'sd_bus_open_with_description'],
''],
['sd_bus_error',
'3',
'3',
['sd_bus_message_get_realtime_usec', 'sd_bus_message_get_seqnum'],
''],
+ ['sd_bus_message_get_type',
+ '3',
+ ['sd_bus_message_is_method_call',
+ 'sd_bus_message_is_method_error',
+ 'sd_bus_message_is_signal'],
+ ''],
+ ['sd_bus_message_new',
+ '3',
+ ['SD_BUS_MESSAGE_METHOD_CALL',
+ 'SD_BUS_MESSAGE_METHOD_ERROR',
+ 'SD_BUS_MESSAGE_METHOD_RETURN',
+ 'SD_BUS_MESSAGE_SIGNAL',
+ 'sd_bus_message_get_bus',
+ 'sd_bus_message_ref',
+ 'sd_bus_message_unref',
+ 'sd_bus_message_unrefp'],
+ ''],
+ ['sd_bus_message_new_method_call',
+ '3',
+ ['sd_bus_message_new_method_return'],
+ ''],
['sd_bus_message_new_method_error',
'3',
['sd_bus_message_new_method_errno',
'sd_bus_message_new_method_errnof',
'sd_bus_message_new_method_errorf'],
''],
+ ['sd_bus_message_new_signal', '3', [], ''],
['sd_bus_message_read', '3', ['sd_bus_message_readv'], ''],
['sd_bus_message_read_basic', '3', [], ''],
- ['sd_bus_message_set_destination', '3', ['sd_bus_message_set_sender'], ''],
+ ['sd_bus_message_rewind', '3', [], ''],
+ ['sd_bus_message_set_destination',
+ '3',
+ ['sd_bus_message_get_destination',
+ 'sd_bus_message_get_interface',
+ 'sd_bus_message_get_member',
+ 'sd_bus_message_get_path',
+ 'sd_bus_message_get_sender',
+ 'sd_bus_message_set_sender'],
+ ''],
+ ['sd_bus_message_set_expect_reply',
+ '3',
+ ['sd_bus_message_get_auto_start',
+ 'sd_bus_message_get_expect_reply',
+ 'sd_bus_message_set_auto_start'],
+ ''],
+ ['sd_bus_message_verify_type', '3', [], ''],
['sd_bus_negotiate_fds',
'3',
['sd_bus_negotiate_creds', 'sd_bus_negotiate_timestamp'],
''],
['sd_bus_set_sender', '3', ['sd_bus_get_sender'], ''],
['sd_bus_set_watch_bind', '3', ['sd_bus_get_watch_bind'], ''],
+ ['sd_bus_slot_ref',
+ '3',
+ ['sd_bus_slot_get_bus', 'sd_bus_slot_unref', 'sd_bus_slot_unrefp'],
+ ''],
+ ['sd_bus_slot_set_description', '3', ['sd_bus_slot_get_description'], ''],
['sd_bus_slot_set_destroy_callback',
'3',
['sd_bus_destroy_t',
'sd_bus_track_set_destroy_callback'],
''],
['sd_bus_slot_set_floating', '3', ['sd_bus_slot_get_floating'], ''],
+ ['sd_bus_slot_set_userdata', '3', ['sd_bus_slot_get_userdata'], ''],
['sd_bus_track_add_name',
'3',
['sd_bus_track_add_sender',
<citerefentry><refentrytitle>sd_bus_message_copy</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_message_get_cookie</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>sd_bus_message_get_type</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>sd_bus_message_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>sd_bus_message_new_method_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_message_new_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>sd_bus_message_new_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_message_read_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_message_read</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>sd_bus_message_rewind</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_message_set_destination</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>sd_bus_message_set_expect_reply</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>sd_bus_message_verify_type</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_negotiate_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_path_encode</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_set_sender</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_set_watch_bind</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-<citerefentry><refentrytitle>sd_bus_set_slot_destroy_callback</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
-<citerefentry><refentrytitle>sd_bus_set_slot_floating</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>sd_bus_slot_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>sd_bus_slot_set_destroy_callback</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>sd_bus_slot_set_floating</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>sd_bus_slot_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_track_add_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_track_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</literallayout>
<refname>sd_bus_default_system</refname>
<refname>sd_bus_open</refname>
+ <refname>sd_bus_open_with_description</refname>
<refname>sd_bus_open_user</refname>
+ <refname>sd_bus_open_user_with_description</refname>
<refname>sd_bus_open_system</refname>
+ <refname>sd_bus_open_system_with_description</refname>
<refname>sd_bus_open_system_remote</refname>
<refname>sd_bus_open_system_machine</refname>
<paramdef>sd_bus **<parameter>bus</parameter></paramdef>
</funcprototype>
+ <funcprototype>
+ <funcdef>int <function>sd_bus_open_with_description</function></funcdef>
+ <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
+ <paramdef>const char *<parameter>description</parameter></paramdef>
+ </funcprototype>
+
<funcprototype>
<funcdef>int <function>sd_bus_open_user</function></funcdef>
<paramdef>sd_bus **<parameter>bus</parameter></paramdef>
</funcprototype>
+ <funcprototype>
+ <funcdef>int <function>sd_bus_open_user_with_description</function></funcdef>
+ <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
+ <paramdef>const char *<parameter>description</parameter></paramdef>
+ </funcprototype>
+
<funcprototype>
<funcdef>int <function>sd_bus_open_system</function></funcdef>
<paramdef>sd_bus **<parameter>bus</parameter></paramdef>
</funcprototype>
+ <funcprototype>
+ <funcdef>int <function>sd_bus_open_system_with_description</function></funcdef>
+ <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
+ <paramdef>const char *<parameter>description</parameter></paramdef>
+ </funcprototype>
+
<funcprototype>
<funcdef>int <function>sd_bus_open_system_remote</function></funcdef>
<paramdef>sd_bus **<parameter>bus</parameter></paramdef>
<function>sd_bus_default_system()</function> to connect to the
user or system buses.</para>
+ <para><function>sd_bus_open_with_description()</function>,
+ <function>sd_bus_open_user_with_description()</function>, and
+ <function>sd_bus_open_system_with_description()</function> are similar to
+ <function>sd_bus_open()</function>, <function>sd_bus_open_user()</function>, and
+ <function>sd_bus_open_system()</function>, but allow a description string to be set, see
+ <citerefentry><refentrytitle>sd_bus_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
+ <parameter>description</parameter> may be <constant>NULL</constant>, in which case this function
+ is equivalent to <function>sd_bus_open()</function>. This description string is used in log
+ messages about the bus object, and including a "name" for the bus makes them easier to
+ understand. Some messages are emitted during bus initialization, hence using this function is
+ prefereable to setting the description later with
+ <function>sd_bus_open_with_description()</function>. The argument is copied internally and will
+ not be referenced after the function returns.</para>
+
<para>If the <varname>$DBUS_SESSION_BUS_ADDRESS</varname> environment
variable is set
(cf. <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>),
--- /dev/null
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1+ -->
+
+<refentry id="sd_bus_message_get_type" xmlns:xi="http://www.w3.org/2001/XInclude">
+
+ <refentryinfo>
+ <title>sd_bus_message_get_type</title>
+ <productname>systemd</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>sd_bus_message_get_type</refentrytitle>
+ <manvolnum>3</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>sd_bus_message_get_type</refname>
+ <refname>sd_bus_message_is_signal</refname>
+ <refname>sd_bus_message_is_method_call</refname>
+ <refname>sd_bus_message_is_method_error</refname>
+
+ <refpurpose>Query bus message addressing metadata</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
+
+ <funcprototype>
+ <funcdef>int <function>sd_bus_message_get_type</function></funcdef>
+ <paramdef>sd_bus_message *<parameter>message</parameter></paramdef>
+ <paramdef>uint8_t *<parameter>type</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>int <function>sd_bus_message_is_signal</function></funcdef>
+ <paramdef>sd_bus_message *<parameter>message</parameter></paramdef>
+ <paramdef>const char *<parameter>interface</parameter></paramdef>
+ <paramdef>const char *<parameter>member</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>int <function>sd_bus_message_is_method_call</function></funcdef>
+ <paramdef>sd_bus_message *<parameter>message</parameter></paramdef>
+ <paramdef>const char *<parameter>interface</parameter></paramdef>
+ <paramdef>const char *<parameter>member</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>int <function>sd_bus_message_is_method_error</function></funcdef>
+ <paramdef>sd_bus_message *<parameter>message</parameter></paramdef>
+ <paramdef>const char *<parameter>name</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para><function>sd_bus_message_get_type()</function> returns the type of a message in the output
+ parameter <parameter>type</parameter>, one of <constant>SD_BUS_MESSAGE_METHOD_CALL</constant>,
+ <constant>SD_BUS_MESSAGE_METHOD_RETURN</constant>,
+ <constant>SD_BUS_MESSAGE_METHOD_ERROR</constant>, <constant>SD_BUS_MESSAGE_SIGNAL</constant>.
+ This type is either specified as a parameter when the message is created using
+ <citerefentry><refentrytitle>sd_bus_set_message_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ or is set automatically when the message is created using
+ <citerefentry><refentrytitle>sd_bus_set_message_new_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_bus_set_message_new_method_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_bus_set_message_new_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ and similar functions.
+ </para>
+
+ <para><function>sd_bus_message_is_signal()</function> checks if message <parameter>m</parameter>
+ is a signal message. If <parameter>interface</parameter> is non-null, it also checks if the
+ message has the same interface set. If <parameter>member</parameter> is non-null, it also checks
+ if the message has the same member set. Also see
+ <citerefentry><refentrytitle>sd_bus_set_message_new_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>. It returns true when all checks pass.</para>
+
+ <para><function>sd_bus_message_is_method_call()</function> checks if message <parameter>m</parameter>
+ is a method call message. If <parameter>interface</parameter> is non-null, it also checks if the
+ message has the same interface set. If <parameter>member</parameter> is non-null, it also checks
+ if the message has the same member set. Also see
+ <citerefentry><refentrytitle>sd_bus_set_message_new_method_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>. It returns true when all checks pass.</para>
+
+ <para><function>sd_bus_message_is_method_error()</function> checks if message <parameter>m</parameter>
+ is an error reply message. If <parameter>name</parameter> is non-null, it also checks if the
+ message has the same error identifier set. Also see
+ <citerefentry><refentrytitle>sd_bus_set_message_new_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>. It returns true when all checks pass.</para>
+</refsect1>
+
+ <refsect1>
+ <title>Return Value</title>
+
+ <para>On success, those functions return 0 or a positive
+ integer. On failure, it returns a negative errno-style error code.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Errors</title>
+
+ <para>Returned errors may indicate the following problems:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>-EINVAL</constant></term>
+
+ <listitem><para>The <parameter>message</parameter> parameter or the output parameter are
+ <constant>NULL</constant>.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <xi:include href="libsystemd-pkgconfig.xml" />
+
+ <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_message_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_bus_message_set_destination</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ </para>
+ </refsect1>
+
+</refentry>
--- /dev/null
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1+ -->
+
+<refentry id="sd_bus_message_new" xmlns:xi="http://www.w3.org/2001/XInclude">
+ <refentryinfo>
+ <title>sd_bus_message_new</title>
+ <productname>systemd</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>sd_bus_message_new</refentrytitle>
+ <manvolnum>3</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>sd_bus_message_new</refname>
+ <refname>sd_bus_message_ref</refname>
+ <refname>sd_bus_message_unref</refname>
+ <refname>sd_bus_message_unrefp</refname>
+ <refname>SD_BUS_MESSAGE_METHOD_CALL</refname>
+ <refname>SD_BUS_MESSAGE_METHOD_RETURN</refname>
+ <refname>SD_BUS_MESSAGE_METHOD_ERROR</refname>
+ <refname>SD_BUS_MESSAGE_SIGNAL</refname>
+ <refname>sd_bus_message_get_bus</refname>
+
+ <refpurpose>Create a new bus message object and create or destroy references to it</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
+
+ <funcsynopsisinfo><token>enum</token> {
+ <constant>SD_BUS_MESSAGE_METHOD_CALL</constant>,
+ <constant>SD_BUS_MESSAGE_METHOD_RETURN</constant>,
+ <constant>SD_BUS_MESSAGE_METHOD_ERROR</constant>,
+ <constant>SD_BUS_MESSAGE_SIGNAL</constant>,
+};</funcsynopsisinfo>
+
+ <funcprototype>
+ <funcdef>int <function>sd_bus_message_new</function></funcdef>
+ <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
+ <paramdef>sd_bus_message **<parameter>m</parameter></paramdef>
+ <paramdef>uint8_t <parameter>type</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>sd_bus_message *<function>sd_bus_message_ref</function></funcdef>
+ <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>sd_bus_message *<function>sd_bus_message_unref</function></funcdef>
+ <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>void <function>sd_bus_message_unrefp</function></funcdef>
+ <paramdef>sd_bus_message **<parameter>mp</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>sd_bus *<function>sd_bus_message_get_bus</function></funcdef>
+ <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para><function>sd_bus_message_new()</function> creates a new bus message object attached to the
+ bus <parameter>bus</parameter> and returns it in the output parameter <parameter>m</parameter>.
+ This object is reference-counted, and will be destroyed when all references are gone. Initially,
+ the caller of this function owns the sole reference to the message object. Note that the message
+ object holds a reference to the bus object, so the bus object will not be destroyed as long as
+ the message exists.</para>
+
+ <para>Note: this is a low-level call. In most cases functions like
+ <citerefentry><refentrytitle>sd_bus_message_new_method_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_bus_message_new_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_bus_message_new_method_return</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ and <citerefentry><refentrytitle>sd_bus_message_new_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ that create a message of a certain type and initialize various fields are easier to use.</para>
+
+ <para>The <parameter>type</parameter> parameter specifies the type of the message. It must be
+ one of <constant>SD_BUS_MESSAGE_METHOD_CALL</constant> — a method call,
+ <constant>SD_BUS_MESSAGE_METHOD_RETURN</constant> — a method call reply,
+ <constant>SD_BUS_MESSAGE_METHOD_ERROR</constant> — an error reply to a method call,
+ <constant>SD_BUS_MESSAGE_SIGNAL</constant> — a broadcast message with no reply.
+ </para>
+
+ <para>The flag to allow interactive authorization is initialized based on the current value set
+ in the bus object, see
+ <citerefentry><refentrytitle>sd_bus_set_allow_interactive_authorization</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
+ This may be changed using
+ <citerefentry><refentrytitle>sd_bus_message_set_allow_interactive_authorization</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
+ </para>
+
+ <para><function>sd_bus_message_ref()</function> increases the reference counter of
+ <parameter>m</parameter> by one.</para>
+
+ <para><function>sd_bus_message_unref()</function> decreases the reference counter of
+ <parameter>m</parameter> by one. Once the reference count has dropped to zero, message object is
+ destroyed and cannot be used anymore, so further calls to
+ <function>sd_bus_message_ref()</function> or <function>sd_bus_message_unref()</function> are
+ illegal.</para>
+
+ <para><function>sd_bus_message_unrefp()</function> is similar to
+ <function>sd_bus_message_unref()</function> but takes a pointer to a
+ pointer to an <type>sd_bus_message</type> object. This call is useful in
+ conjunction with GCC's and LLVM's <ulink
+ url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up
+ Variable Attribute</ulink>. See
+ <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ for an example how to use the cleanup attribute.</para>
+
+ <para><function>sd_bus_message_ref()</function> and <function>sd_bus_message_unref()</function>
+ execute no operation if the passed in bus object address is
+ <constant>NULL</constant>. <function>sd_bus_message_unrefp()</function> will first dereference
+ its argument, which must not be <constant>NULL</constant>, and will execute no operation if
+ <emphasis>that</emphasis> is <constant>NULL</constant>.
+ </para>
+
+ <para><function>sd_bus_message_get_bus()</function> returns the bus object that message
+ <parameter>m</parameter> is attached to.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Return Value</title>
+
+ <para>On success, <function>sd_bus_message_new()</function> returns 0 or a positive integer. On
+ failure, it returns a negative errno-style error code.</para>
+
+ <para><function>sd_bus_message_ref()</function> always returns the argument.
+ </para>
+
+ <para><function>sd_bus_message_unref()</function> always returns
+ <constant>NULL</constant>.</para>
+
+ <para><function>sd_bus_message_get_bus()</function> always returns the bus object.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Errors</title>
+
+ <para>Returned errors may indicate the following problems:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>-EINVAL</constant></term>
+
+ <listitem><para>Specified <parameter>type</parameter> is invalid.</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>
+ </refsect1>
+
+ <xi:include href="libsystemd-pkgconfig.xml" />
+
+ <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_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_bus_message_new_method_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_bus_message_new_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_bus_message_new_method_return</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_bus_message_new_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ </para>
+ </refsect1>
+
+</refentry>
--- /dev/null
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1+ -->
+
+<refentry id="sd_bus_message_new_method_call"
+ xmlns:xi="http://www.w3.org/2001/XInclude">
+
+ <refentryinfo>
+ <title>sd_bus_message_new_method_call</title>
+ <productname>systemd</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>sd_bus_message_new_method_call</refentrytitle>
+ <manvolnum>3</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>sd_bus_message_new_method_call</refname>
+ <refname>sd_bus_message_new_method_return</refname>
+
+ <refpurpose>Create a method call message</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
+
+ <funcprototype>
+ <funcdef>int sd_bus_message_new_method_call</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>
+
+ <funcprototype>
+ <funcdef>int sd_bus_message_new_method_return</funcdef>
+ <paramdef>sd_bus_message *<parameter>call</parameter></paramdef>
+ <paramdef>sd_bus_message **<parameter>m</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>The <function>sd_bus_message_new_method_call()</function> function creates a new bus
+ message object that encapsulates a D-Bus method call, and returns it in the
+ <parameter>m</parameter> output parameter. The call will be made on the destination
+ <parameter>destination</parameter>, path <parameter>path</parameter>, on the interface
+ <parameter>interface</parameter>, member <parameter>member</parameter>.</para>
+
+ <para>Briefly, the <emphasis>destination</emphasis> is a dot-separated name that identifies a
+ service connected to the bus. The <emphasis>path</emphasis> is a slash-separated identifier of
+ an object within the destination that resembles a file system path. The meaning of this path is
+ defined by the destination. The <emphasis>interface</emphasis> is a dot-separated name that
+ resembles a Java interface name that identifies a group of methods and signals supported by the
+ object identified by path. Methods and signals are collectively called
+ <emphasis>members</emphasis> and are identified by a simple name composed of ASCII letters,
+ numbers, and underscores. See the <ulink
+ url="https://dbus.freedesktop.org/doc/dbus-tutorial.html#concepts">D-Bus Tutorial</ulink> for an
+ in-depth explanation.</para>
+
+ <para>The <parameter>destination</parameter> parameter may be <constant>NULL</constant>. The
+ <parameter>interface</parameter> parameter may be <constant>NULL</constant>, if the destination
+ has only a single member with the given name and there is no ambiguity if the interface name is
+ omitted.</para>
+
+ <para>The <function>sd_bus_message_new_method_call()</function> function creates a new bus
+ message object that is a reply to the method call <parameter>call</parameter> and returns it in
+ the <parameter>m</parameter> output parameter. The <parameter>call</parameter> parameter must be
+ a method call message. The sender of <parameter>call</parameter> is used as the destination.
+ </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>
+ </refsect1>
+
+ <refsect1 id='errors'>
+ <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>destination</parameter> parameter is non-null and is not a valid D-Bus
+ service name (<literal>org.somewhere.Something</literal>), the <parameter>path</parameter>
+ parameter is not a valid D-Bus path (<literal>/an/object/path</literal>), the
+ <parameter>interface</parameter> parameter is non-null and 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>
+
+ <para>The <parameter>call</parameter> parameter is not a method call object.</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>
+
+ <varlistentry>
+ <term><constant>-EPERM</constant></term>
+
+ <listitem>
+ <para>The <parameter>call</parameter> parameter is not sealed.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>-EOPNOTSUPP</constant></term>
+
+ <listitem>
+ <para>The <parameter>call</parameter> message does not have a cookie.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <xi:include href="libsystemd-pkgconfig.xml" />
+
+ <refsect1>
+ <title>Examples</title>
+
+ <example>
+ <title>Make a call to a D-Bus method that takes a single parameter</title>
+
+ <programlisting><xi:include href="print-unit-path.c" parse="text" /></programlisting>
+ <para>This defines a minimally useful program that will open a connection to the bus, create a
+ message object, send it, wait for the reply, and finally extract and print the answer. It does
+ error handling and proper memory management.</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_path_encode</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ </para>
+ </refsect1>
+
+</refentry>
--- /dev/null
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1+ -->
+
+<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>
+
+ <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>
+ </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_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>
+ </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>
+ </refsect1>
+
+ <refsect1 id='errors'>
+ <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>
+ </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>
+ </para>
+ </refsect1>
+
+</refentry>
--- /dev/null
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1+ -->
+
+<refentry id="sd_bus_message_rewind"
+ xmlns:xi="http://www.w3.org/2001/XInclude">
+
+ <refentryinfo>
+ <title>sd_bus_message_rewind</title>
+ <productname>systemd</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>sd_bus_message_rewind</refentrytitle>
+ <manvolnum>3</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>sd_bus_message_rewind</refname>
+
+ <refpurpose>Return to begining of message or current container</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
+
+ <funcprototype>
+ <funcdef>int <function>sd_bus_message_rewind</function></funcdef>
+ <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
+ <paramdef>int <parameter>complete</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para><function>sd_bus_message_rewind()</function> moves the "read pointer" in the message
+ <parameter>m</parameter> to either the begining of the message (if
+ <parameter>complete</parameter> is true) or to the beginning of the currently open container. If
+ no container is open, <parameter>complete</parameter> has no effect.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Return Value</title>
+
+ <para>
+ On success, this function returns 0 or a positive integer. The value is zero if the current
+ container or whole message in case no container is open is empty, and positive otherwise. On
+ failure, it returns a negative errno-style error code.
+ </para>
+ </refsect1>
+
+ <xi:include href="libsystemd-pkgconfig.xml" />
+
+ <refsect1>
+ <title>Errors</title>
+
+ <para>Returned errors may indicate the following problems:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>-EINVAL</constant></term>
+
+ <listitem><para>The <parameter>m</parameter> parameter is <constant>NULL</constant>.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>-EPERM</constant></term>
+
+ <listitem><para>The message <parameter>m</parameter> has not been sealed.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </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_message_read</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ </para>
+ </refsect1>
+
+</refentry>
-->
<refentry id="sd_bus_message_set_destination" xmlns:xi="http://www.w3.org/2001/XInclude">
-
<refentryinfo>
<title>sd_bus_message_set_destination</title>
<productname>systemd</productname>
<refnamediv>
<refname>sd_bus_message_set_destination</refname>
+ <refname>sd_bus_message_get_destination</refname>
+ <refname>sd_bus_message_get_path</refname>
+ <refname>sd_bus_message_get_interface</refname>
+ <refname>sd_bus_message_get_member</refname>
<refname>sd_bus_message_set_sender</refname>
- <refpurpose>Set the destination or sender service name of a bus message</refpurpose>
+ <refname>sd_bus_message_get_sender</refname>
+
+ <refpurpose>Set and query bus message addressing information</refpurpose>
</refnamediv>
<refsynopsisdiv>
<paramdef>const char *<parameter>destination</parameter></paramdef>
</funcprototype>
+ <funcprototype>
+ <funcdef>const char* <function>sd_bus_message_get_destination</function></funcdef>
+ <paramdef>sd_bus_message *<parameter>message</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>const char* <function>sd_bus_message_get_path</function></funcdef>
+ <paramdef>sd_bus_message *<parameter>message</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>const char* <function>sd_bus_message_get_interface</function></funcdef>
+ <paramdef>sd_bus_message *<parameter>message</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>const char* <function>sd_bus_message_get_member</function></funcdef>
+ <paramdef>sd_bus_message *<parameter>message</parameter></paramdef>
+ </funcprototype>
+
<funcprototype>
<funcdef>int <function>sd_bus_message_set_sender</function></funcdef>
<paramdef>sd_bus_message *<parameter>message</parameter></paramdef>
<paramdef>const char *<parameter>sender</parameter></paramdef>
</funcprototype>
+
+ <funcprototype>
+ <funcdef>const char* <function>sd_bus_message_get_sender</function></funcdef>
+ <paramdef>sd_bus_message *<parameter>message</parameter></paramdef>
+ </funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
- <para><function>sd_bus_message_set_destination()</function> sets the destination service name for the specified bus
- message object. The specified name must be a valid unique or well-known service name.</para>
+ <para><function>sd_bus_message_set_destination()</function> sets the destination service name
+ for the specified bus message object. The specified name must be a valid unique or well-known
+ service name.</para>
+
+ <para><function>sd_bus_message_get_destination()</function>,
+ <function>sd_bus_message_get_path()</function>,
+ <function>sd_bus_message_get_interface()</function>, and
+ <function>sd_bus_message_get_member()</function> return the destination, path, interface, and
+ member fields from <parameter>message</parameter> header. The return value will be
+ <constant>NULL</constant> is <parameter>message</parameter> is <constant>NULL</constant> or the
+ message is of a type that doesn't use those fields or the message doesn't have them set. See
+ <citerefentry><refentrytitle>sd_bus_message_new_method_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ and
+ <citerefentry><refentrytitle>sd_bus_message_set_destination</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ for more discussion of those values.</para>
+
<para><function>sd_bus_message_set_sender()</function> sets the sender service name for the specified bus message
object. The specified name must be a valid unique or well-known service name. This function is useful only for
messages to send on direct connections as for connections to bus brokers the broker will fill in the destination
field anyway, and the sender field set by original sender is ignored.</para>
+
+ <para><function>sd_bus_message_get_sender()</function> returns the sender field from
+ <parameter>message</parameter>.</para>
+
+ <para>When a string is returned, it is a pointer to internal storage, and may not be modified or
+ freed. It is only valid as long as the <parameter>message</parameter> remains referenced and
+ this field hasn't been changed by a different call.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
- <para>On success, these calls return 0 or a positive integer. On failure, these calls return a negative errno-style
- error code.</para>
+ <para>On success, these calls return 0 or a positive integer. On failure, these calls return a
+ negative errno-style error code.</para>
</refsect1>
<refsect1>
<varlistentry>
<term><constant>-EINVAL</constant></term>
- <listitem><para>A specified parameter is invalid.</para></listitem>
+ <listitem><para>The <parameter>message</parameter> parameter or the output parameter are
+ <constant>NULL</constant>.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-EPERM</constant></term>
- <listitem><para>The message is already sealed.</para></listitem>
+ <listitem><para>For <function>sd_bus_message_set_destination</function> or
+ <function>sd_bus_message_set_sender</function>, the message is already
+ sealed.</para></listitem>
</varlistentry>
<varlistentry>
--- /dev/null
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1+ -->
+
+<refentry id="sd_bus_message_set_expect_reply" xmlns:xi="http://www.w3.org/2001/XInclude">
+
+ <refentryinfo>
+ <title>sd_bus_message_set_expect_reply</title>
+ <productname>systemd</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>sd_bus_message_set_expect_reply</refentrytitle>
+ <manvolnum>3</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>sd_bus_message_set_expect_reply</refname>
+ <refname>sd_bus_message_get_expect_reply</refname>
+ <refname>sd_bus_message_set_auto_start</refname>
+ <refname>sd_bus_message_get_auto_start</refname>
+
+ <refpurpose>Set and query bus message metadata</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
+
+ <funcprototype>
+ <funcdef>int <function>sd_bus_message_set_expect_reply</function></funcdef>
+ <paramdef>sd_bus_message *<parameter>message</parameter></paramdef>
+ <paramdef>int <parameter>b</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>int <function>sd_bus_message_get_expect_reply</function></funcdef>
+ <paramdef>sd_bus_message *<parameter>message</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>int <function>sd_bus_message_set_auto_start</function></funcdef>
+ <paramdef>sd_bus_message *<parameter>message</parameter></paramdef>
+ <paramdef>int <parameter>b</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>int <function>sd_bus_message_get_auto_start</function></funcdef>
+ <paramdef>sd_bus_message *<parameter>message</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para><function>sd_bus_message_set_expect_reply()</function> sets or clears the
+ <constant>NO_REPLY_EXPECTED</constant> flag on the message <parameter>m</parameter>. This flag
+ matters only for method call messages and is used to specify that no method return or error
+ reply is expected. It is ignored for other types. Thus, for a method call message, calling
+ <programlisting>sd_bus_message_set_expect_reply(…, 0)</programlisting> sets the flag and
+ suppresses the reply.</para>
+
+ <para><function>sd_bus_message_get_expect_reply()</function> checks if the
+ <constant>NO_REPLY_EXPECTED</constant> flag is set on the message <parameter>m</parameter>. It
+ will return positive if it is not set, and zero if it is.</para>
+
+ <para><function>sd_bus_message_set_auto_start()</function> sets or clears the
+ <constant>NO_AUTO_START</constant> flag on the message <parameter>m</parameter>. When the flag
+ is set the bus must not launch an owner for the destination name in response to this message.
+ Calling
+ <programlisting>sd_bus_message_set_auto_start(…, 0)</programlisting> sets the flag.
+ </para>
+
+ <para><function>sd_bus_message_get_auto_start()</function> checks if the
+ <constant>NO_AUTO_START</constant> flag is set on the message <parameter>m</parameter>. It
+ will return positive if it is not set, and zero if it is.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Return Value</title>
+
+ <para>On success, these functions return 0 or a positive integer. On failure, they return a
+ negative errno-style error code.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Errors</title>
+
+ <para>Returned errors may indicate the following problems:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>-EINVAL</constant></term>
+
+ <listitem><para>The <parameter>message</parameter> parameter is
+ <constant>NULL</constant>.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>-EPERM</constant></term>
+
+ <listitem><para>The message <parameter>message</parameter> is sealed
+ when trying to set a flag.</para>
+
+ <para>The message <parameter>message</parameter> has wrong
+ type.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <xi:include href="libsystemd-pkgconfig.xml" />
+
+ <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_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ </para>
+ </refsect1>
+
+</refentry>
--- /dev/null
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1+ -->
+
+<refentry id="sd_bus_message_verify_type" xmlns:xi="http://www.w3.org/2001/XInclude">
+ <refentryinfo>
+ <title>sd_bus_message_verify_type</title>
+ <productname>systemd</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>sd_bus_message_verify_type</refentrytitle>
+ <manvolnum>3</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>sd_bus_message_verify_type</refname>
+
+ <refpurpose>Check if the message has specified type at the current location</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
+
+ <funcprototype>
+ <funcdef>int sd_bus_message_verify_type</funcdef>
+ <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
+ <paramdef>char <parameter>type</parameter></paramdef>
+ <paramdef>const char* <parameter>contents</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para><function>sd_bus_message_verify_type()</function> checks if the complete type at the
+ current location in the message <parameter>m</parameter> matches the specified
+ <parameter>type</parameter> and <parameter>contents</parameter>. If non-zero, parameter
+ <parameter>type</parameter> must be one of the types specified in
+ <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+ If non-null, parameter <parameter>contents</parameter> must be a valid sequence of complete
+ types. If both <parameter>type</parameter> and <parameter>contents</parameter> are specified
+ <parameter>type</parameter> must be a container type.</para>
+
+ <para>If <parameter>type</parameter> is specified, the type in the message must match. If
+ <parameter>contents</parameter> is specified, the type in the message must be a container type
+ with this signature.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Return Value</title>
+
+ <para>On success, this call returns true if the type matches and zero if not (the message
+ <parameter>m</parameter> contains different data or the end of the message has been reached). On
+ failure, it returns a negative errno-style error code.</para>
+ </refsect1>
+
+ <refsect1 id='errors'>
+ <title>Errors</title>
+
+ <para>Returned errors may indicate the following problems:</para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><constant>-EINVAL</constant></term>
+
+ <listitem><para><parameter>m</parameter> or both <parameter>type</parameter> and
+ <parameter>contents</parameter> are <constant>NULL</constant>.</para>
+
+ <para>Arguments do not satisfy other contraints listed above.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><constant>-EPERM</constant></term>
+
+ <listitem><para>Message <parameter>m</parameter> is not sealed.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <xi:include href="libsystemd-pkgconfig.xml" />
+
+ <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_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ </para>
+ </refsect1>
+
+</refentry>
<funcprototype>
<funcdef>void <function>sd_bus_unrefp</function></funcdef>
- <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
+ <paramdef>sd_bus **<parameter>busp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
block is left:</para>
<programlisting>{
- __attribute__((cleanup(sd_bus_unrefp)) sd_bus *bus = NULL;
- int r;
- …
- r = sd_bus_default(&bus);
- if (r < 0)
- fprintf(stderr, "Failed to allocate bus: %s\n", strerror(-r));
- …
+ __attribute__((cleanup(sd_bus_unrefp)) sd_bus *bus = NULL;
+ int r;
+ …
+ r = sd_bus_default(&bus);
+ if (r < 0)
+ fprintf(stderr, "Failed to allocate bus: %s\n", strerror(-r));
+ …
}</programlisting>
- <para><function>sd_bus_ref()</function>,
- <function>sd_bus_unref()</function> and
- <function>sd_bus_unrefp()</function> execute no operation if the
- passed in bus object is <constant>NULL</constant>.</para>
+ <para><function>sd_bus_ref()</function> and <function>sd_bus_unref()</function>
+ execute no operation if the passed in bus object address is
+ <constant>NULL</constant>. <function>sd_bus_unrefp()</function> will first
+ dereference its argument, which must not be <constant>NULL</constant>, and will
+ execute no operation if <emphasis>that</emphasis> is <constant>NULL</constant>.
+ </para>
</refsect1>
<refsect1>
always be <constant>NUL</constant>-terminated. The returned string
will be the concatenation of the bus path prefix plus an escaped
version of the external identifier string. This operation may be
- reversed with <function>sd_bus_decode()</function>. It is
+ reversed with <function>sd_bus_path_decode()</function>. It is
recommended to only use external identifiers that generally
require little escaping to be turned into valid bus path
identifiers (for example, by sticking to a 7-bit ASCII character
--- /dev/null
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1+ -->
+
+<refentry id="sd_bus_slot_ref" xmlns:xi="http://www.w3.org/2001/XInclude">
+ <refentryinfo>
+ <title>sd_bus_slot_ref</title>
+ <productname>systemd</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>sd_bus_slot_ref</refentrytitle>
+ <manvolnum>3</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>sd_bus_slot_ref</refname>
+ <refname>sd_bus_slot_unref</refname>
+ <refname>sd_bus_slot_unrefp</refname>
+ <refname>sd_bus_slot_get_bus</refname>
+
+ <refpurpose>Create and destroy references to a bus slot object</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
+
+ <funcprototype>
+ <funcdef>sd_bus_slot *<function>sd_bus_slot_ref</function></funcdef>
+ <paramdef>sd_bus_slot *<parameter>slot</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>sd_bus_slot *<function>sd_bus_slot_unref</function></funcdef>
+ <paramdef>sd_bus_slot *<parameter>slot</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>void <function>sd_bus_slot_unrefp</function></funcdef>
+ <paramdef>sd_bus_slot **<parameter>slotp</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>sd_bus *<function>sd_bus_slot_get_bus</function></funcdef>
+ <paramdef>sd_bus_slot *<parameter>m</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para><function>sd_bus_slot_ref()</function> increases the reference counter of
+ <parameter>slot</parameter> by one.</para>
+
+ <para><function>sd_bus_slot_unref()</function> decreases the reference counter of
+ <parameter>slot</parameter> by one. Once the reference count has dropped to zero, slot object is
+ destroyed and cannot be used anymore, so further calls to <function>sd_bus_slot_ref()</function>
+ or <function>sd_bus_slot_unref()</function> are illegal.</para>
+
+ <para><function>sd_bus_slot_unrefp()</function> is similar to
+ <function>sd_bus_slot_unref()</function> but takes a pointer to a pointer to an
+ <type>sd_bus_slot</type> object. This call is useful in conjunction with GCC's and LLVM's <ulink
+ url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up Variable
+ Attribute</ulink>. See
+ <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ for an example how to use the cleanup attribute.</para>
+
+ <para><function>sd_bus_slot_ref()</function> and <function>sd_bus_slot_unref()</function>
+ execute no operation if the passed in bus object address is
+ <constant>NULL</constant>. <function>sd_bus_slot_unrefp()</function> will first dereference
+ its argument, which must not be <constant>NULL</constant>, and will execute no operation if
+ <emphasis>that</emphasis> is <constant>NULL</constant>.
+ </para>
+
+ <para><function>sd_bus_slot_get_bus()</function> returns the bus object that message
+ <parameter>slot</parameter> is attached to.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Return Value</title>
+
+ <para><function>sd_bus_slot_ref()</function> always returns the argument.</para>
+
+ <para><function>sd_bus_slot_unref()</function> always returns <constant>NULL</constant>.</para>
+
+ <para><function>sd_bus_slot_get_bus()</function> always returns the bus object.</para>
+ </refsect1>
+
+ <xi:include href="libsystemd-pkgconfig.xml" />
+
+ <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_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_bus_message_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_bus_slot_new_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_bus_call_method_async</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ </para>
+ </refsect1>
+
+</refentry>
--- /dev/null
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1+ -->
+
+<refentry id="sd_bus_slot_set_description" xmlns:xi="http://www.w3.org/2001/XInclude">
+ <refentryinfo>
+ <title>sd_bus_slot_set_description</title>
+ <productname>systemd</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>sd_bus_slot_set_description</refentrytitle>
+ <manvolnum>3</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>sd_bus_slot_set_description</refname>
+ <refname>sd_bus_slot_get_description</refname>
+
+ <refpurpose>Set or query the description of bus slot objects</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
+
+ <funcprototype>
+ <funcdef>int <function>sd_bus_slot_set_description</function></funcdef>
+ <paramdef>sd_bus_slot* <parameter>slot</parameter></paramdef>
+ <paramdef>const char *<parameter>description</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>int <function>sd_bus_slot_get_description</function></funcdef>
+ <paramdef>sd_bus_slot* <parameter>bus</parameter></paramdef>
+ <paramdef>const char **<parameter>description</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para><function>sd_bus_slot_set_description()</function> sets the description string
+ that is used in logging to the specified string. The string is copied internally
+ and freed when the bus slot object is deallocated. The
+ <parameter>description</parameter> argument may be <constant>NULL</constant>, in
+ which case the description is unset.</para>
+
+ <para><function>sd_bus_slot_get_description()</function> returns a description string in
+ <parameter>description</parameter>. If the string is not set, e.g. with
+ <function>sd_bus_slot_set_description()</function>, and the slot is a bus match callback slot,
+ the match string will be returned. Otherwise, <constant>-ENXIO</constant> is returned.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Return Value</title>
+
+ <para>On success, these functions return 0 or a positive integer. On failure,
+ they return a negative errno-style error code.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Errors</title>
+
+ <para>Returned errors may indicate the following problems:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>-EINVAL</constant></term>
+
+ <listitem><para>An required argument is <constant>NULL</constant>.</para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>-ENXIO</constant></term>
+
+ <listitem><para>The bus slot object has no description.</para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <variablelist>
+ <varlistentry>
+ <term><constant>-ENOMEM</constant></term>
+
+ <listitem><para>Memory allocation failed.</para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ </refsect1>
+
+ <xi:include href="libsystemd-pkgconfig.xml" />
+
+ <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_slot_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_bus_slot_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ </para>
+ </refsect1>
+
+</refentry>
--- /dev/null
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1+ -->
+
+<refentry id="sd_bus_slot_set_userdata" xmlns:xi="http://www.w3.org/2001/XInclude">
+
+ <refentryinfo>
+ <title>sd_bus_slot_set_userdata</title>
+ <productname>systemd</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>sd_bus_slot_set_userdata</refentrytitle>
+ <manvolnum>3</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>sd_bus_slot_set_userdata</refname>
+ <refname>sd_bus_slot_get_userdata</refname>
+
+ <refpurpose>Set and query the value in the "userdata" field</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
+
+ <funcprototype>
+ <funcdef>void* <function>sd_bus_slot_set_userdata</function></funcdef>
+ <paramdef>sd_bus_slot* <parameter>slot</parameter></paramdef>
+ <paramdef>void* <parameter>userdata</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>void* <function>sd_bus_slot_get_userdata</function></funcdef>
+ <paramdef>sd_bus_slot* <parameter>slot</parameter></paramdef>
+ </funcprototype>
+
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>The userdata pointer allows data to be passed between the point where a callback is
+ registered, for example when a filter is added using
+ <citerefentry><refentrytitle>sd_bus_add_filter</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ or an asynchronous function call is made using
+ <citerefentry><refentrytitle>sd_bus_call_async</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ and the point where the callback is called, without having any global state. The pointer has
+ type <type>void*</type> and is not used by the sd-bus functions in any way, except to pass to
+ the callback function.</para>
+
+ <para>Usually, the userdata field is set when the slot object is initially
+ registered. <function>sd_bus_slot_set_userdata()</function> may be used to change it later for
+ the bus slot object <parameter>slot</parameter>. Previous value of the field is returned. The
+ argument and returned value may be <constant>NULL</constant>. It will be passed as the
+ <parameter>userdata</parameter> argument to the callback function attached to the slot.</para>
+
+ <para><function>sd_bus_slot_set_userdata()</function> gets the value of the userdata field in
+ the bus slot object <parameter>slot</parameter>.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Return Value</title>
+
+ <para>On success, these functions return the value of the userdata field before the function
+ call. If the <parameter>slot</parameter> object is <constant>NULL</constant>,
+ <constant>NULL</constant> will be returned to signify an error, but this is not distinguishable
+ from the userdata field value being <constant>NULL</constant>.</para>
+ </refsect1>
+
+ <xi:include href="libsystemd-pkgconfig.xml" />
+
+ <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_slot_set_destroy_callback</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_bus_slot_get_current_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ </para>
+ </refsect1>
+
+</refentry>
<para>Here's a simple example for an application specific machine ID:</para>
- <programlisting>#include <systemd/sd-id128.h>
-#include <stdio.h>
-
-#define OUR_APPLICATION_ID SD_ID128_MAKE(c2,73,27,73,23,db,45,4e,a6,3b,b9,6e,79,b5,3e,97)
-
-int main(int argc, char *argv[]) {
- sd_id128_t id;
- sd_id128_get_machine_app_specific(OUR_APPLICATION_ID, &id);
- printf("Our application ID: " SD_ID128_FORMAT_STR "\n", SD_ID128_FORMAT_VAL(id));
- return 0;
-}</programlisting>
+ <programlisting><xi:include href="id128-app-specific.c" parse="text" /></programlisting>
</example>
</refsect1>
following example lists all unit names referenced in the
journal:</para>
- <programlisting>#include <stdio.h>
-#include <string.h>
-#include <systemd/sd-journal.h>
-
-int main(int argc, char *argv[]) {
- sd_journal *j;
- const void *d;
- size_t l;
- int r;
-
- r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY);
- if (r < 0) {
- fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
- return 1;
- }
- r = sd_journal_query_unique(j, "_SYSTEMD_UNIT");
- if (r < 0) {
- fprintf(stderr, "Failed to query journal: %s\n", strerror(-r));
- return 1;
- }
- SD_JOURNAL_FOREACH_UNIQUE(j, d, l)
- printf("%.*s\n", (int) l, (const char*) d);
- sd_journal_close(j);
- return 0;
-}</programlisting>
-
+ <programlisting><xi:include href="journal-iterate-unique.c" parse="text" /></programlisting>
</refsect1>
<refsect1>
code block is left:</para>
<programlisting>{
- __attribute__((cleanup(sd_login_monitor_unrefp)) sd_login_monitor *m = NULL;
- int r;
- …
- r = sd_login_monitor_default(&m);
- if (r < 0)
- fprintf(stderr, "Failed to allocate login monitor object: %s\n", strerror(-r));
- …
+ __attribute__((cleanup(sd_login_monitor_unrefp)) sd_login_monitor *m = NULL;
+ int r;
+ …
+ r = sd_login_monitor_default(&m);
+ if (r < 0)
+ fprintf(stderr, "Failed to allocate login monitor object: %s\n", strerror(-r));
+ …
}</programlisting>
<para><function>sd_login_monitor_flush()</function> may be used to
int msec;
sd_login_monitor_get_timeout(m, &t);
if (t == (uint64_t) -1)
- msec = -1;
+ msec = -1;
else {
- struct timespec ts;
- uint64_t n;
- clock_gettime(CLOCK_MONOTONIC, &ts);
- n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;
- msec = t > n ? (int) ((t - n + 999) / 1000) : 0;
+ struct timespec ts;
+ uint64_t n;
+ clock_gettime(CLOCK_MONOTONIC, &ts);
+ n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;
+ msec = t > n ? (int) ((t - n + 999) / 1000) : 0;
}</programlisting>
<para>The code above does not do any error checking for brevity's
--- /dev/null
+#include <systemd/sd-bus.h>
+#define _cleanup_(f) __attribute__((cleanup(f)))
+
+int send_unit_files_changed(sd_bus *bus) {
+ _cleanup_(sd_bus_message_unrefp) sd_bus_message *message = NULL;
+ int r;
+
+ r = sd_bus_message_new_signal(bus, &message,
+ "/org/freedesktop/systemd1",
+ "org.freedesktop.systemd1.Manager",
+ "UnitFilesChanged");
+ if (r < 0)
+ return r;
+
+ return sd_bus_send(bus, message, NULL);
+}
_public_ int sd_bus_message_set_destination(sd_bus_message *m, const char *destination) {
assert_return(m, -EINVAL);
assert_return(destination, -EINVAL);
+ assert_return(service_name_is_valid(destination), -EINVAL);
assert_return(!m->sealed, -EPERM);
assert_return(!m->destination, -EEXIST);
_public_ int sd_bus_message_set_sender(sd_bus_message *m, const char *sender) {
assert_return(m, -EINVAL);
assert_return(sender, -EINVAL);
+ assert_return(service_name_is_valid(sender), -EINVAL);
assert_return(!m->sealed, -EPERM);
assert_return(!m->sender, -EEXIST);
set -eu
+sd_good=0
+sd_total=0
+udev_good=0
+udev_total=0
+
for symbol in `nm -g --defined-only "$@" | grep " T " | cut -d" " -f3 | sort -u` ; do
if test -f ${MESON_BUILD_ROOT}/man/$symbol.3 ; then
echo "✓ Symbol $symbol() is documented."
+ good=1
else
printf " \x1b[1;31mSymbol $symbol() lacks documentation.\x1b[0m\n"
+ good=0
fi
+
+ case $symbol in
+ sd_*)
+ ((sd_good+=good))
+ ((sd_total+=1))
+ ;;
+ udev_*)
+ ((udev_good+=good))
+ ((udev_total+=1))
+ ;;
+ *)
+ echo 'unknown symbol prefix'
+ exit 1
+ esac
done
+
+echo "libsystemd: $sd_good/$sd_total libudev: $udev_good/$udev_total"
projects / thirdparty / systemd.git / commitdiff
