Debian Codegraph @

upstream/debian-unstable/man3/sd_bus_message_set_destination.3

raw
1 '\" t
2 .TH "SD_BUS_MESSAGE_SET_DESTINATION" "3" "" "systemd 261~rc3" "sd_bus_message_set_destination"
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_message_set_destination, sd_bus_message_get_destination, sd_bus_message_get_path, sd_bus_message_get_interface, sd_bus_message_get_member, sd_bus_message_set_sender, sd_bus_message_get_sender \- Set and query bus message addressing information
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_message_set_destination('u
32 .BI "int sd_bus_message_set_destination(sd_bus_message\ *" "message" ", const\ char\ *" "destination" ");"
33 .HP \w'const\ char*\ sd_bus_message_get_destination('u
34 .BI "const char* sd_bus_message_get_destination(sd_bus_message\ *" "message" ");"
35 .HP \w'const\ char*\ sd_bus_message_get_path('u
36 .BI "const char* sd_bus_message_get_path(sd_bus_message\ *" "message" ");"
37 .HP \w'const\ char*\ sd_bus_message_get_interface('u
38 .BI "const char* sd_bus_message_get_interface(sd_bus_message\ *" "message" ");"
39 .HP \w'const\ char*\ sd_bus_message_get_member('u
40 .BI "const char* sd_bus_message_get_member(sd_bus_message\ *" "message" ");"
41 .HP \w'int\ sd_bus_message_set_sender('u
42 .BI "int sd_bus_message_set_sender(sd_bus_message\ *" "message" ", const\ char\ *" "sender" ");"
43 .HP \w'const\ char*\ sd_bus_message_get_sender('u
44 .BI "const char* sd_bus_message_get_sender(sd_bus_message\ *" "message" ");"
45 .SH "DESCRIPTION"
46 .PP
47 \fBsd_bus_message_set_destination()\fR
48 sets the destination service name for the specified bus message object\&. The specified name must be a valid unique or well\-known service name\&.
49 .PP
50 \fBsd_bus_message_get_destination()\fR,
51 \fBsd_bus_message_get_path()\fR,
52 \fBsd_bus_message_get_interface()\fR, and
53 \fBsd_bus_message_get_member()\fR
54 return the destination, path, interface, and member fields from
55 \fImessage\fR
56 header\&. The return value will be
57 \fBNULL\fR
58 is
59 \fImessage\fR
60 is
61 \fBNULL\fR
62 or the message is of a type that does not use those fields or the message does not have them set\&. See
63 \fBsd_bus_message_new_method_call\fR(3)
64 and
65 \fBsd_bus_message_set_destination\fR(3)
66 for more discussion of those values\&.
67 .PP
68 \fBsd_bus_message_set_sender()\fR
69 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\&.
70 .PP
71 \fBsd_bus_message_get_sender()\fR
72 returns the sender field from
73 \fImessage\fR\&.
74 .PP
75 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
76 \fImessage\fR
77 remains referenced and this field has not been changed by a different call\&.
78 .SH "RETURN VALUE"
79 .PP
80 On success, these calls return 0 or a positive integer\&. On failure, these calls return a negative errno\-style error code\&.
81 .SS "Errors"
82 .PP
83 Returned errors may indicate the following problems:
84 .PP
85 \fB\-EINVAL\fR
86 .RS 4
87 The
88 \fImessage\fR
89 parameter or the output parameter are
90 \fBNULL\fR\&.
91 .RE
92 .PP
93 \fB\-EPERM\fR
94 .RS 4
95 For
96 \fBsd_bus_message_set_destination()\fR
97 and
98 \fBsd_bus_message_set_sender()\fR, the message is already sealed\&.
99 .RE
100 .PP
101 \fB\-EEXIST\fR
102 .RS 4
103 The message already has a destination or sender field set\&.
104 .RE
105 .SH "NOTES"
106 .PP
107 Functions described here are available as a shared library, which can be compiled against and linked to with the
108 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
109 file\&.
110 .PP
111 The code described here uses
112 \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
113 \fBsetenv\fR(3)
114 from a parallel thread\&. It is recommended to only do calls to
115 \fBsetenv()\fR
116 from an early phase of the program when no other threads have been started\&.
117 .SH "HISTORY"
118 .PP
119 \fBsd_bus_message_set_destination()\fR
120 and
121 \fBsd_bus_message_set_sender()\fR
122 were added in version 237\&.
123 .PP
124 \fBsd_bus_message_get_destination()\fR,
125 \fBsd_bus_message_get_path()\fR,
126 \fBsd_bus_message_get_interface()\fR,
127 \fBsd_bus_message_get_member()\fR, and
128 \fBsd_bus_message_get_sender()\fR
129 were added in version 240\&.
130 .SH "SEE ALSO"
131 .PP
132 \fBsystemd\fR(1), \fBsd-bus\fR(3), \fBsd_bus_new\fR(3), \fBsd_bus_set_sender\fR(3)