picnoir
/
Systemd
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Merge pull request #9776 from keszybz/sd-bus-docs 

More man pages for sd-bus and related changes
This commit is contained in:
Lennart Poettering 2018-08-02 17:07:03 +02:00 committed by GitHub
parent 99521cab77 46fdbae32e
commit 27d4866ad8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
25 changed files with 1550 additions and 75 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
man/id128-app-specific.c Normal file
View File

@ -0,0 +1,11 @@
#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;
}

25
man/journal-iterate-unique.c Normal file
View File

@ -0,0 +1,25 @@
#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;
}

64
man/print-unit-path.c Normal file
View File

@ -0,0 +1,64 @@
#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);
}

51
man/rules/meson.build
View File

@ -166,7 +166,10 @@ manpages = [
'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',
@ -210,15 +213,53 @@ manpages = [
'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'],
@ -252,6 +293,11 @@ manpages = [
''],
['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',
@ -260,6 +306,7 @@ manpages = [
'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',

13
man/sd-bus.xml
View File

@ -60,10 +60,17 @@
<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>,
@ -74,8 +81,10 @@
<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>

35
man/sd_bus_default.xml
View File

@ -24,8 +24,11 @@
<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>
@ -56,16 +59,34 @@
<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>
@ -126,6 +147,20 @@
<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>),

129
man/sd_bus_message_get_type.xml Normal file
View File

@ -0,0 +1,129 @@
<?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 &lt;systemd/sd-bus.h&gt;</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>

189
man/sd_bus_message_new.xml Normal file
View File

@ -0,0 +1,189 @@
<?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 &lt;systemd/sd-bus.h&gt;</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>

166
man/sd_bus_message_new_method_call.xml Normal file
View File

@ -0,0 +1,166 @@
<?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 &lt;systemd/sd-bus.h&gt;</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>

120
man/sd_bus_message_new_signal.xml Normal file
View File

@ -0,0 +1,120 @@
<?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 &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>
</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>

88
man/sd_bus_message_rewind.xml Normal file
View File

@ -0,0 +1,88 @@
<?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 &lt;systemd/sd-bus.h&gt;</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>

70
man/sd_bus_message_set_destination.xml
View File

@ -6,7 +6,6 @@
-->
<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>
@ -19,8 +18,14 @@
<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>
@ -33,31 +38,77 @@
<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>
@ -69,13 +120,16 @@
<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>

127
man/sd_bus_message_set_expect_reply.xml Normal file
View File

@ -0,0 +1,127 @@
<?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 &lt;systemd/sd-bus.h&gt;</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>

99
man/sd_bus_message_verify_type.xml Normal file
View File

@ -0,0 +1,99 @@
<?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 &lt;systemd/sd-bus.h&gt;</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>

26
man/sd_bus_new.xml
View File

@ -48,7 +48,7 @@
<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>
@ -96,19 +96,21 @@
block is left:</para>
<programlisting>{
__attribute__((cleanup(sd_bus_unrefp)) sd_bus *bus = NULL;
int r;
…
r = sd_bus_default(&amp;bus);
if (r &lt; 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(&amp;bus);
if (r &lt; 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>

2
man/sd_bus_path_encode.xml
View File

@ -80,7 +80,7 @@
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

107
man/sd_bus_slot_ref.xml Normal file
View File

@ -0,0 +1,107 @@
<?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 &lt;systemd/sd-bus.h&gt;</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>

109
man/sd_bus_slot_set_description.xml Normal file
View File

@ -0,0 +1,109 @@
<?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 &lt;systemd/sd-bus.h&gt;</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>

88
man/sd_bus_slot_set_userdata.xml Normal file
View File

@ -0,0 +1,88 @@
<?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 &lt;systemd/sd-bus.h&gt;</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>

12
man/sd_id128_get_machine.xml
View File

@ -120,17 +120,7 @@
<para>Here's a simple example for an application specific machine ID:</para>
<programlisting>#include &lt;systemd/sd-id128.h&gt;
#include &lt;stdio.h&gt;
#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, &amp;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>

27
man/sd_journal_query_unique.xml
View File

@ -140,32 +140,7 @@
following example lists all unit names referenced in the
journal:</para>
<programlisting>#include &lt;stdio.h&gt;
#include &lt;string.h&gt;
#include &lt;systemd/sd-journal.h&gt;
int main(int argc, char *argv[]) {
sd_journal *j;
const void *d;
size_t l;
int r;
r = sd_journal_open(&amp;j, SD_JOURNAL_LOCAL_ONLY);
if (r &lt; 0) {
fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
return 1;
}
r = sd_journal_query_unique(j, "_SYSTEMD_UNIT");
if (r &lt; 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>

26
man/sd_login_monitor_new.xml
View File

@ -115,13 +115,13 @@
code block is left:</para>
<programlisting>{
__attribute__((cleanup(sd_login_monitor_unrefp)) sd_login_monitor *m = NULL;
int r;
…
r = sd_login_monitor_default(&amp;m);
if (r &lt; 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(&amp;m);
if (r &lt; 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
@ -176,13 +176,13 @@
int msec;
sd_login_monitor_get_timeout(m, &amp;t);
if (t == (uint64_t) -1)
msec = -1;
msec = -1;
else {
struct timespec ts;
uint64_t n;
clock_gettime(CLOCK_MONOTONIC, &amp;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, &amp;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

16
man/send-unit-files-changed.c Normal file
View File

@ -0,0 +1,16 @@
#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);
}

2
src/libsystemd/sd-bus/bus-message.c
View File

@ -5433,6 +5433,7 @@ int bus_message_parse_fields(sd_bus_message *m) {
_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);
@ -5442,6 +5443,7 @@ _public_ int sd_bus_message_set_destination(sd_bus_message *m, const char *desti
_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);

23
tools/meson-check-api-docs.sh
View File

@ -2,10 +2,33 @@
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"