Debian Codegraph @

upstream/debian-trixie/man3/sd_bus_set_address.3

raw
1 '\" t
2 .TH "SD_BUS_SET_ADDRESS" "3" "" "systemd 257.13" "sd_bus_set_address"
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_address, sd_bus_get_address, sd_bus_set_exec \- Set or query the address of the bus connection
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_address('u
32 .BI "int sd_bus_set_address(sd_bus\ *" "bus" ", const\ char\ *" "address" ");"
33 .HP \w'int\ sd_bus_get_address('u
34 .BI "int sd_bus_get_address(sd_bus\ *" "bus" ", const\ char\ **" "address" ");"
35 .HP \w'int\ sd_bus_set_exec('u
36 .BI "int sd_bus_set_exec(sd_bus\ *" "bus" ", const\ char\ *" "path" ", char\ *const\ *" "argv" ");"
37 .SH "DESCRIPTION"
38 .PP
39 \fBsd_bus_set_address()\fR
40 configures a list of addresses of bus brokers to try to connect to from a subsequent
41 \fBsd_bus_start\fR(3)
42 call\&. The argument is a
43 ";"\-separated list of addresses to try\&. Each item must be one of the following:
44 .sp
45 .RS 4
46 .ie n \{\
47 \h'-04'\(bu\h'+03'\c
48 .\}
49 .el \{\
50 .sp -1
51 .IP \(bu 2.3
52 .\}
53 A unix socket address specified as
54 "unix:guid=\fIguid\fR,path=\fIpath\fR"
55 or
56 "unix:guid=\fIguid\fR,abstract=\fIpath\fR"\&. Exactly one of the
57 \fIpath=\fR
58 and
59 \fIabstract=\fR
60 keys must be present, while
61 \fIguid=\fR
62 is optional\&.
63 .RE
64 .sp
65 .RS 4
66 .ie n \{\
67 \h'-04'\(bu\h'+03'\c
68 .\}
69 .el \{\
70 .sp -1
71 .IP \(bu 2.3
72 .\}
73 A TCP socket address specified as
74 "tcp:[guid=\fIguid\fR,][host=\fIhost\fR][,port=\fIport\fR][,family=\fIfamily\fR]"\&. One or both of the
75 \fIhost=\fR
76 and
77 \fIport=\fR
78 keys must be present, while the rest is optional\&.
79 \fIfamily\fR
80 may be either
81 \fBipv4\fR
82 or
83 \fBipv6\fR\&.
84 .RE
85 .sp
86 .RS 4
87 .ie n \{\
88 \h'-04'\(bu\h'+03'\c
89 .\}
90 .el \{\
91 .sp -1
92 .IP \(bu 2.3
93 .\}
94 An executable to spawn specified as
95 "unixexec:guid=\fIguid\fR,path=\fIpath\fR,argv1=\fIargument\fR,argv2=\fIargument\fR,\&.\&.\&."\&. The
96 \fIpath=\fR
97 key must be present, while
98 \fIguid=\fR
99 is optional\&.
100 .RE
101 .sp
102 .RS 4
103 .ie n \{\
104 \h'-04'\(bu\h'+03'\c
105 .\}
106 .el \{\
107 .sp -1
108 .IP \(bu 2.3
109 .\}
110 A machine (container) to connect to specified as
111 "x\-machine\-unix:guid=\fIguid\fR,machine=\fImachine\fR,pid=\fIpid\fR"\&. Exactly one of the
112 \fImachine=\fR
113 and
114 \fIpid=\fR
115 keys must be present, while
116 \fIguid=\fR
117 is optional\&.
118 \fImachine\fR
119 is the name of a local container\&. See
120 \fBmachinectl\fR(1)
121 for more information about the "machine" concept\&.
122 "machine=\&.host"
123 may be used to specify the host machine\&. A connection to the standard system bus socket inside of the specified machine will be created\&.
124 .RE
125 .PP
126 In all cases, parameter
127 \fIguid\fR
128 is an identifier of the remote peer, in the syntax accepted by
129 \fBsd_id128_from_string\fR(3)\&. If specified, the identifier returned by the peer after the connection is established will be checked and the connection will be rejected in case of a mismatch\&.
130 .PP
131 Note that the addresses passed to
132 \fBsd_bus_set_address()\fR
133 might not be verified immediately\&. If they are invalid, an error may be returned e\&.g\&. from a subsequent call to
134 \fBsd_bus_start\fR(3)\&.
135 .PP
136 \fBsd_bus_get_address()\fR
137 returns any previously set addresses\&. In addition to being explicitly set by
138 \fBsd_bus_set_address()\fR, the address will also be set automatically by
139 \fBsd_bus_open\fR(3)
140 and similar calls, based on environment variables or built\-in defaults\&.
141 .PP
142 \fBsd_bus_set_exec()\fR
143 is a shorthand function for setting a
144 "unixexec"
145 address that spawns the given executable with the given arguments\&. If
146 \fIargv\fR
147 is
148 \fBNULL\fR, the given executable is spawned without any extra arguments\&.
149 .SH "RETURN VALUE"
150 .PP
151 On success, these functions return a non\-negative integer\&. On failure, they return a negative errno\-style error code\&.
152 .SS "Errors"
153 .PP
154 Returned errors may indicate the following problems:
155 .PP
156 \fB\-EINVAL\fR
157 .RS 4
158 The input parameters
159 \fIbus\fR
160 or
161 \fIaddress\fR
162 are
163 \fBNULL\fR\&.
164 .sp
165 Added in version 246\&.
166 .RE
167 .PP
168 \fB\-ENOPKG\fR
169 .RS 4
170 The bus object
171 \fIbus\fR
172 could not be resolved\&.
173 .sp
174 Added in version 246\&.
175 .RE
176 .PP
177 \fB\-EPERM\fR
178 .RS 4
179 The input parameter
180 \fIbus\fR
181 is in a wrong state (\fBsd_bus_set_address()\fR
182 may only be called once on a newly\-created bus object)\&.
183 .sp
184 Added in version 246\&.
185 .RE
186 .PP
187 \fB\-ECHILD\fR
188 .RS 4
189 The bus object
190 \fIbus\fR
191 was created in a different process\&.
192 .sp
193 Added in version 246\&.
194 .RE
195 .PP
196 \fB\-ENODATA\fR
197 .RS 4
198 The bus object
199 \fIbus\fR
200 has no address configured\&.
201 .sp
202 Added in version 246\&.
203 .RE
204 .SH "NOTES"
205 .PP
206 Functions described here are available as a shared library, which can be compiled against and linked to with the
207 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
208 file\&.
209 .PP
210 The code described here uses
211 \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
212 \fBsetenv\fR(3)
213 from a parallel thread\&. It is recommended to only do calls to
214 \fBsetenv()\fR
215 from an early phase of the program when no other threads have been started\&.
216 .SH "HISTORY"
217 .PP
218 \fBsd_bus_set_address()\fR,
219 \fBsd_bus_get_address()\fR, and
220 \fBsd_bus_set_exec()\fR
221 were added in version 246\&.
222 .SH "SEE ALSO"
223 .PP
224 \fBsystemd\fR(1), \fBsd-bus\fR(3), \fBsd_bus_new\fR(3), \fBsd_bus_start\fR(3), \fBsystemd-machined.service\fR(8), \fBmachinectl\fR(1)