Debian Codegraph @

upstream/debian-unstable/man3/sd_bus_set_address.3

raw
1 '\" t
2 .TH "SD_BUS_SET_ADDRESS" "3" "" "systemd 261~rc3" "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 .sp
85 Note:
86 \fIconnections over TCP are made without encryption\fR\&. Thus, this mode should only be used in specific situations where integrity and confidentiality of the connection is not necessary or is ensured through some other means\&. For local connections,
87 "unix:"
88 connections should be used instead\&.
89 .RE
90 .sp
91 .RS 4
92 .ie n \{\
93 \h'-04'\(bu\h'+03'\c
94 .\}
95 .el \{\
96 .sp -1
97 .IP \(bu 2.3
98 .\}
99 An executable to spawn specified as
100 "unixexec:guid=\fIguid\fR,path=\fIpath\fR,argv1=\fIargument\fR,argv2=\fIargument\fR,\&.\&.\&."\&. The
101 \fIpath=\fR
102 key must be present, while
103 \fIguid=\fR
104 is optional\&.
105 .RE
106 .sp
107 .RS 4
108 .ie n \{\
109 \h'-04'\(bu\h'+03'\c
110 .\}
111 .el \{\
112 .sp -1
113 .IP \(bu 2.3
114 .\}
115 A machine (container) to connect to specified as
116 "x\-machine\-unix:guid=\fIguid\fR,machine=\fImachine\fR,pid=\fIpid\fR"\&. Exactly one of the
117 \fImachine=\fR
118 and
119 \fIpid=\fR
120 keys must be present, while
121 \fIguid=\fR
122 is optional\&.
123 \fImachine\fR
124 is the name of a local container\&. See
125 \fBmachinectl\fR(1)
126 for more information about the "machine" concept\&.
127 "machine=\&.host"
128 may be used to specify the host machine\&. A connection to the standard system bus socket inside of the specified machine will be created\&.
129 .RE
130 .PP
131 In all cases, parameter
132 \fIguid\fR
133 is an identifier of the remote peer, in the syntax accepted by
134 \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\&.
135 .PP
136 Note that the addresses passed to
137 \fBsd_bus_set_address()\fR
138 might not be verified immediately\&. If they are invalid, an error may be returned e\&.g\&. from a subsequent call to
139 \fBsd_bus_start\fR(3)\&.
140 .PP
141 \fBsd_bus_get_address()\fR
142 returns any previously set addresses\&. In addition to being explicitly set by
143 \fBsd_bus_set_address()\fR, the address will also be set automatically by
144 \fBsd_bus_open\fR(3)
145 and similar calls, based on environment variables or built\-in defaults\&.
146 .PP
147 \fBsd_bus_set_exec()\fR
148 is a shorthand function for setting a
149 "unixexec"
150 address that spawns the given executable with the given arguments\&. If
151 \fIargv\fR
152 is
153 \fBNULL\fR, the given executable is spawned without any extra arguments\&.
154 .SH "RETURN VALUE"
155 .PP
156 On success, these functions return a non\-negative integer\&. On failure, they return a negative errno\-style error code\&.
157 .SS "Errors"
158 .PP
159 Returned errors may indicate the following problems:
160 .PP
161 \fB\-EINVAL\fR
162 .RS 4
163 The input parameters
164 \fIbus\fR
165 or
166 \fIaddress\fR
167 are
168 \fBNULL\fR\&.
169 .sp
170 Added in version 246\&.
171 .RE
172 .PP
173 \fB\-ENOPKG\fR
174 .RS 4
175 The bus object
176 \fIbus\fR
177 could not be resolved\&.
178 .sp
179 Added in version 246\&.
180 .RE
181 .PP
182 \fB\-EPERM\fR
183 .RS 4
184 The input parameter
185 \fIbus\fR
186 is in a wrong state (\fBsd_bus_set_address()\fR
187 may only be called once on a newly\-created bus object)\&.
188 .sp
189 Added in version 246\&.
190 .RE
191 .PP
192 \fB\-ECHILD\fR
193 .RS 4
194 The bus object
195 \fIbus\fR
196 was created in a different process\&.
197 .sp
198 Added in version 246\&.
199 .RE
200 .PP
201 \fB\-ENODATA\fR
202 .RS 4
203 The bus object
204 \fIbus\fR
205 has no address configured\&.
206 .sp
207 Added in version 246\&.
208 .RE
209 .SH "NOTES"
210 .PP
211 Functions described here are available as a shared library, which can be compiled against and linked to with the
212 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
213 file\&.
214 .PP
215 The code described here uses
216 \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
217 \fBsetenv\fR(3)
218 from a parallel thread\&. It is recommended to only do calls to
219 \fBsetenv()\fR
220 from an early phase of the program when no other threads have been started\&.
221 .SH "HISTORY"
222 .PP
223 \fBsd_bus_set_address()\fR,
224 \fBsd_bus_get_address()\fR, and
225 \fBsd_bus_set_exec()\fR
226 were added in version 246\&.
227 .SH "SEE ALSO"
228 .PP
229 \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)