Debian Codegraph @

upstream/debian-unstable/man3/sd_bus_set_property.3

raw
1 '\" t
2 .TH "SD_BUS_SET_PROPERTY" "3" "" "systemd 261~rc3" "sd_bus_set_property"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 sd_bus_set_property, sd_bus_set_propertyv, sd_bus_get_property, sd_bus_get_property_trivial, sd_bus_get_property_string, sd_bus_get_property_strv \- Set or query D\-Bus service properties
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-bus\&.h>
29 .fi
30 .ft
31 .HP \w'int\ sd_bus_set_property('u
32 .BI "int sd_bus_set_property(sd_bus\ *" "bus" ", const\ char\ *" "destination" ", const\ char\ *" "path" ", const\ char\ *" "interface" ", const\ char\ *" "member" ", sd_bus_error\ *" "ret_error" ", const\ char\ *" "type" ", \&.\&.\&.);"
33 .HP \w'int\ sd_bus_set_propertyv('u
34 .BI "int sd_bus_set_propertyv(sd_bus\ *" "bus" ", const\ char\ *" "destination" ", const\ char\ *" "path" ", const\ char\ *" "interface" ", const\ char\ *" "member" ", sd_bus_error\ *" "ret_error" ", const\ char\ *" "type" ", va_list\ " "ap" ");"
35 .HP \w'int\ sd_bus_get_property('u
36 .BI "int sd_bus_get_property(sd_bus\ *" "bus" ", const\ char\ *" "destination" ", const\ char\ *" "path" ", const\ char\ *" "interface" ", const\ char\ *" "member" ", sd_bus_error\ *" "ret_error" ", sd_bus_message\ **" "reply" ", const\ char\ *" "type" ");"
37 .HP \w'int\ sd_bus_get_property_trivial('u
38 .BI "int sd_bus_get_property_trivial(sd_bus\ *" "bus" ", const\ char\ *" "destination" ", const\ char\ *" "path" ", const\ char\ *" "interface" ", const\ char\ *" "member" ", sd_bus_error\ *" "ret_error" ", char\ " "type" ", void\ *" "ret_ptr" ");"
39 .HP \w'int\ sd_bus_get_property_string('u
40 .BI "int sd_bus_get_property_string(sd_bus\ *" "bus" ", const\ char\ *" "destination" ", const\ char\ *" "path" ", const\ char\ *" "interface" ", const\ char\ *" "member" ", sd_bus_error\ *" "ret_error" ", char\ **" "ret" ");"
41 .HP \w'int\ sd_bus_get_property_strv('u
42 .BI "int sd_bus_get_property_strv(sd_bus\ *" "bus" ", const\ char\ *" "destination" ", const\ char\ *" "path" ", const\ char\ *" "interface" ", const\ char\ *" "member" ", sd_bus_error\ *" "ret_error" ", char\ ***" "ret" ");"
43 .SH "DESCRIPTION"
44 .PP
45 These functions set or query D\-Bus properties\&. D\-Bus properties are service fields exposed via the
46 \fBorg\&.freedesktop\&.DBus\&.Properties\fR
47 interface\&. Under the hood, these functions call methods of the
48 \fBorg\&.freedesktop\&.DBus\&.Properties\fR
49 interface and as a result their semantics are similar to
50 \fBsd_bus_call_method\fR(3)\&.
51 .PP
52 \fBsd_bus_set_property()\fR
53 sets a D\-Bus property\&. If setting the property fails or an internal error occurs, an error is returned and an extended description of the error is optionally stored in
54 \fIret_error\fR
55 if it is not
56 \fBNULL\fR\&.
57 \fItype\fR
58 and the arguments that follow it describe the new value of the property and must follow the format described in
59 \fBsd_bus_message_append\fR(3)\&.
60 .PP
61 \fBsd_bus_set_propertyv()\fR
62 is equivalent to
63 \fBsd_bus_set_property()\fR, except that it is called with a
64 "va_list"
65 instead of a variable number of arguments\&.
66 .PP
67 \fBsd_bus_get_property()\fR
68 queries a D\-Bus property\&. If retrieving the property fails or an internal error occurs, an error is returned and an extended description of the error is optionally stored in
69 \fIret_error\fR
70 if it is not
71 \fBNULL\fR\&. On success, the property is stored in
72 \fIreply\fR\&.
73 \fItype\fR
74 describes the property type and must follow the format described in
75 \fBsd_bus_message_append\fR(3)\&.
76 .PP
77 \fBsd_bus_get_property_trivial()\fR,
78 \fBsd_bus_get_property_string()\fR
79 and
80 \fBsd_bus_get_property_strv()\fR
81 are shorthands for
82 \fBsd_bus_get_property()\fR
83 that are used to query basic, string and string vector properties respectively\&. The caller is responsible for freeing the string and string vector results stored in
84 \fIret\fR
85 by
86 \fBsd_bus_get_property_string()\fR
87 and
88 \fBsd_bus_get_property_strv()\fR\&.
89 .SH "RETURN VALUE"
90 .PP
91 On success, these functions return a non\-negative integer\&. On failure, they return a negative errno\-style error code\&.
92 .SS "Errors"
93 .PP
94 See the
95 \fBsd_bus_call_method\fR(3)
96 man page for a list of possible errors\&.
97 .SH "NOTES"
98 .PP
99 Functions described here are available as a shared library, which can be compiled against and linked to with the
100 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
101 file\&.
102 .PP
103 The code described here uses
104 \fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call
105 \fBsetenv\fR(3)
106 from a parallel thread\&. It is recommended to only do calls to
107 \fBsetenv()\fR
108 from an early phase of the program when no other threads have been started\&.
109 .SH "HISTORY"
110 .PP
111 \fBsd_bus_set_property()\fR,
112 \fBsd_bus_set_propertyv()\fR,
113 \fBsd_bus_get_property()\fR,
114 \fBsd_bus_get_property_trivial()\fR,
115 \fBsd_bus_get_property_string()\fR, and
116 \fBsd_bus_get_property_strv()\fR
117 were added in version 246\&.
118 .SH "SEE ALSO"
119 .PP
120 \fBsystemd\fR(1), \fBsd-bus\fR(3), \fBsd_bus_call_method\fR(3)